Using Message-Based Services

 

BEA MessageQ applications regularly perform standard tasks such as checking the state of a queue or the status of a cross-group connection before sending a message. To make these tasks easier, BEA MessageQ offers message-based services, which are sets of predefined request, notification, and response messages exchanged between the application and BEA MessageQ server processes.

Table 5-1 describes the functions performed by using message-based services and lists the servers they are available through.

Table 5-1 Overview of Message-Based Services

You can . . .	Through the . . .
Obtain the status of a particular queue	Avail Server
Monitor and control link status	Connect Server
Obtain the current status of all queues	Queue Server
Register for broadcast messages	SBS Server
Manage message recovery files (OpenVMS systems only)	MRS Server
Transfer messages from one DQF file to another (OpenVMS systems only)	Qtransfer Server

How Message-Based Services Work

BEA MessageQ uses message-based services to perform routine tasks such as obtaining queue status. There are two request-response paradigms used by message-based services. For some kinds of services, the sender program sends a request to a BEA MessageQ server using a particular message. The BEA MessageQ server returns the response in a message using a particular message type and format. If information was requested, it is returned in the message area of the response message.

In other cases, a sender program may register to receive ongoing updates of information. In this case, the sender program sends a registration request and receives a response if the registration request is successful. In addition, the sender program receives event-driven messages providing up-to-date information as requested. To stop receiving the event-driven messages, the sender program must send a deregistration request to the BEA MessageQ server.

Service requests are directed to the primary queue of the BEA MessageQ server designated to provide the selected service. BEA MessageQ message-based service requests are delivered to BEA MessageQ servers using the BEA MessageQ application programming interface (API) or BEA MessageQ scripts. Similarly, applications obtain response and notification messages by reading these messages from their primary or response queue.

BEA MessageQ message-based services are sent between a user application program that functions as a requestor and a BEA MessageQ server process that fulfills the request. For messages to be properly understood between systems, message data must be sent and returned in the endian format understood by both the requestor and the server.

Most BEA MessageQ message-based services automatically perform this conversion if the endian format of the two systems is different. However, some message-based services do not perform this conversion. Therefore, the user application must convert the message to the endian format of the server system to ensure that the message data is correctly interpreted.

See the description of each message for information on whether BEA MessageQ performs the conversion or the application must check for differences in hardware data formats. See the Building and Testing Applications topic to learn how you can ensure that your application formats data properly and performs required conversions when sending standard messages between computer systems from different vendors.

Requesting a Service

You can send a service request message using the pams_put_msg function. Request messages use the type argument to identify the purpose of the message. Each request message has a predefined data structure.

To send a standard request message, supply the following:

Target	The symbolic name for the BEA MessageQ server fulfilling the request. For example, use PAMS_AVAIL_SERVER for requests handled by the BEA MessageQ Avail Server process.
Class	The class code PAMS indicating that the message is a BEA MessageQ message-based service request.
Type	The type code of the message you are sending. For example, AVAIL_REG.
Message data	The predefined data structure containing the information to be sent with the service request. The definition of all BEA MessageQ message-based services messages is now provided in the p_msg.h include file.

A detailed description of each message in the Message Reference topic explains each field in the data structure and provides a sample C message structure.

Receiving a Response

Each BEA MessageQ server returns response or notification messages to answer a service request. Most request messages have a response message. In addition, some service requests are answered by the BEA MessageQ server with a notification message that supplies information to the sender program as it becomes available.

When an application requests information using the pams_put_msg function, it provides the BEA MessageQ server with the group ID and queue number to which the response should be directed. The sender program then reads this queue using the pams_get_msg, pams_get_msgw, or pams_get_msga function to obtain the response information.

A BEA MessageQ server response and notification message provides the following:

Source	The symbolic name of the BEA MessageQ server fulfilling the request.
Class	The class code of the response is always PAMS, indicating that this is a BEA MessageQ message-based service.
Type	The type code of the message received. For example, AVAIL_REG_REPLY.
Message data	The predefined data structure used to provide requested information in the response or notification message. The definition of all BEA MessageQ message-based services messages is now provided in the p_msg.h include file.

A detailed description of each message in the Message Reference topic explains each field in the data structure and provides a sample C message structure.

Obtaining the Status of a Queue

BEA MessageQ message-based services enable applications to check whether a particular queue is available to receive messages. This set of messages returns information on the status of any active queue in a local or remote group.

To obtain information on the status of a particular queue, applications exchange the following messages with the Avail Server:

• AVAIL_REG-Request message to register to receive queue information.

• AVAIL_REG_REPLY-Response message to confirm registration or deregistration.

• AVAIL-Notification message to indicate that the queue is available.

• UNAVAIL-Notification message to indicate that the queue is unavailable.

• AVAIL_DEREG-Notification message to deregister from obtaining queue information.

  Figure 5-1 Avail Server Message Flow

  

An application program registers to receive availability messages by sending a message of type AVAIL_REG to the local Avail Server process. The Avail Server responds with a message of type AVAIL_REG_REPLY, acknowledging the notification request.

After registration, the requestor immediately receives an AVAIL or UNAVAIL message indicating the current availability of the target queue. Queue availability messages provide ongoing notification when a specific queue becomes attached or detached and when a link is connected or lost. If the queue becomes active because a process becomes attached, the Avail Server sends a message of type AVAIL. If it becomes -inactive, the server sends a message of type UNAVAIL.

Applications must cancel availability notification by sending a message of type AVAIL_DEREG. The application receives a AVAIL_REG_REPLY message indicating the status of the operation. It is important to note that if the distribution queue for an AVAIL registration becomes unavailable, the registration will be automatically deleted by BEA MessageQ. A subsequent attempt to deregister AVAIL services for this distribution queue will result in an error message indicating that the registration does not exist.

Monitoring and Controlling Link Status

This section describes how applications can use BEA MessageQ message-based services with the Connect Server process to obtain information on connections, queue entries, groups, cross-group connections, and link status.

Listing Cross-Group Connections, Entries, and Groups

An application can request a list of current cross-group connections or all configured cross-group entries from the Connect Server. This request allows the application to obtain the current BEA MessageQ cross-group configuration and active cross-group connections. In addition, the Connect Server can provide a list of known queues in a group and a list of all groups defined on a message queuing bus.

To obtain a list of all cross-group connections, configured groups, and queue entries, applications exchange the following messages with the Connect Server:

• LIST_ALL_CONNECTIONS (Request)-Request message to provide a list of all cross-group connections.

• LIST_ALL_CONNECTIONS (Response)-Response message to provide a list of all cross-group connections. Groups with no link connection are not listed.

• LIST_ALL_ENTRIES (Request)-Request message to provide a list of all queue entries for a group.

• LIST_ALL_ENTRIES (Response)-Response message to provide a list of all queue entries for a group.

• LIST_ALL_GROUPS (Request)-Request message to provide a list of groups on the message queuing bus.

• LIST_ALL_GROUPS (Response)-Response message to provide a list of all groups, connected and unconnected, on the message queuing bus.

  Figure 5-2 Requesting Cross-Group Information

  

To obtain a list of all groups defined on the message queuing bus, send a LIST_ALL_GROUPS message to the Connect Server. To obtain a list of all cross-group connections for the message bus or a list of all cross-group entries, send a LIST_ALL_CONNECTIONS message to the Connect Server. To obtain a list of queues in a group, send a LIST_ALL_ENTRIES message.

The reply to these requests is a variable-length message with the same type and class as the request. To read the information returned, the application uses the message size parameter returned by the pams_get_msg function and divides it by the byte size of the data object requested to determine the number of data entries returned. The byte size of these entries is described in the reference description of each message.

Obtain Notification of Cross-Group Links Established and Lost

An application can also use Connect Server messages to receive notification of cross-group links connected and disconnected in its own group. To obtain information on the status of cross-group links, use the following message-based services:

• ENABLE_NOTIFY-Request message to request notification of link changes.

• LINK_COMPLETE-Notification message to indicate that the cross-group link was created.

• LINK_LOST-Notification message to indicate that the cross-group link was lost.

• DISABLE_NOTIFY-Request message to request disabling of link change -notification.

  Figure 5-3 Requesting Cross-Group Link Status

  

Applications send an ENABLE_NOTIFY message to the Connect Server to receive ongoing notification when new connections are made or lost. Registered applications receive a LINK_COMPLETE notification message when a new cross-group connection is created. Applications receive a LINK_LOST message when a cross-group connection is lost. To deregister from -receiving further notification messages, the application sends a DISABLE_NOTIFY message to the Connect Server.

Note: To receive ongoing notification of queue attachments, we recommend the use of the Queue Server messages, such as ENABLE_Q_NOTIFY_REQ. The ENABLE_NOTIFY message should no longer be used to obtain queue attachment information.

Controlling Cross-Group Links

In addition to obtaining information on cross-group links, the Connect Server messages can be used to control cross-group connections through a feature called link management. Applications use link management messages to explicitly control the creation and deletion of cross-group links. Explicit control over remote links may be required by an application to restrict network communication with a particular node or to reduce network traffic.

The LINKMGT_REQ request message enables the following control functions:

• Inquire-Allows querying of a group's link state.

• Enable-Re-enables a link's address entries.

• Disable-Disables a link's address entries.

• Connect-Re-enables a link's address entries and connects to selected groups.

• Disconnect-Implicitly disables links and disconnects links to requested groups.

The LINKMGT_RESP response message notifies the requesting application if the request was successful and supplies information about the cross-group connection. Link management functions are also available through the System Manager utility on BEA MessageQ for OpenVMS systems. Figure 5-4 is a graphical representation of the functional relationship facilitated by LINKMGT_REQ and LINKMGT_RESP:

Figure 5-4 Using Link Management

Link management can also be event driven. For example, an application event can trigger a link to another group, which enables message exchange.

Note: When using link management, automatic creation of cross-group connections must be disabled with the generate connect option D (disable) in the %XGROUP section of the BEA MessageQ group initialization file to completely control all cross-group links. For more information, refer to the Enabling Network Connections in the Cross-Group Section topic in the BEA MessageQ Installation and Configuration Guide for each platform.

Link Management Control Functions

The link management request message allows for the following control functions:

• Inquire-Allows querying of a group's link state.

• Enable-Re-enables a link's address entries.

• Disable-Disables a link's address entries.

• Connect-Re-enables a link's address entries and connects to selected groups.

• Disconnect-Implicitly disables links and disconnects links to requested groups.

Inquire Function

The Inquire function of the link management request message allows querying of a single group's link state. To use the Inquire function, specify the group number of the local or remote group for which you want to learn the link state. This function does not allow you to specify any selection parameters other than the group number. Because you can only inquire about the link state of one group at a time, you cannot specify the PSYM_LINKMGT_ALL_GROUPS symbol in the group_number field.

The Inquire function performs endian translation when the request is sent to a Connect Server running on a system that uses a different byte order. Both the request and response messages are encoded in the endian of the request originator.

Request Message Format for the Inquire Function

Table 5-2 displays the Inquire function request message format:

Table 5-2 Inquire Function Request Message Format

Field	Required/ Optional	Setting
version	Required	10
user_tag	Required	User-specified code identifying the request.
function_code	Required	PSYM_LINKMGT_CMD_INQUIRY
group_number	Required	Group number to receive the action. Valid values are 1 to 32000.
connect_type	Optional	PSYM_LINKMGT_ALL_TRANSPORTS
reconnect_timer	Optional	PSYM_LINKMGT_USE_PREVIOUS
window_size	Optional	PSYM_LINKMGT_USE_PREVIOUS
window_delay	Optional	PSYM_LINKMGT_USE_PREVIOUS
transport_addr_len	Optional	0
node_name_len	Optional	0

Determining the Status of the Inquire Request

The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the inquiry request. Refer to Table 5-3 for a description of each status return and the corresponding user action.

Table 5-3 Inquire function status returns and user actions

PSYM_LINKMGT Return Code	Description	Outcome	Description/User Action
MSGCONTENT	Invalid value in request message	Error	One of the field values in the inquiry request message is invalid. Check the syntax of the request message against the list of valid values and re-issue the corrected request message.
MSGFMT	Unknown request version or function code	Error	Correct the syntax of the request message. The version field of the must contain the number 10. The function code field must contain the symbol PSYM_LINKMGT_CMD_INQUIRY.
NOGROUP	The selected group does not have a cross group entry	Error	You requested the link state for a group that is not defined in the cross-group table. This group has no cross-group links.
OPERATIONFAIL	The command was unable to be successfully completed	Error	The inquire function failed due to a system resource problem. Check the network connection to the target group to determine if the network link is up. Check the Connect Server to determine if it is running out of virtual memory. Check the log file to see if the cause of the error has been logged.
SUCCESS	The operation successfully completed	Success	Refer to the description of the link management response message below for a description of the data returned.

Response Message Format for Successful Inquire Requests

If the Inquire function is successful, the response message returns the status of both the incoming and outgoing cross-group links in the in_link_state and out_link_state fields. These fields specify the status of the link using the following symbols:

• PSYM_LINKMGT_CONNECTED-the incoming/outgoing cross-group link for the selected group is connected.

• PSYM_LINKMGT_NOCN-the incoming/outgoing cross-group link for the selected group is not connected.

• PSYM_LINKMGT_DISABLE-the incoming/outgoing cross-group link for the selected group is disabled.

If the link status for the group is PSYM_LINKMGT_CONNECTED, the response message contains the following information:

Field	Description
version	10
user_tag	User-specified code from the request message.
Status	PSYM_LINKMGT_SUCCESS
group_number	Group number that receives the action.
in_link_state	PSYM_LINKMGT_CONNECTED
out_link_state	PSYM_LINKMGT_CONNECTED
connect_type	Transport that message is connected over: PSYM_LINKMGT_TCPIP.
platform_id	Connected platform ID (PSYM_PLATFORM_xxxx).
reconnect_time	Reconnect timer value for this group.
window_size	Window size value negotiated for this group.
window_delay	Window delay value negotiated for this group.
transport_addr_len	Length of the transport_addr string.
transport_addr	ASCII representation of the TCP/IP port number.
node_name_len	Length of the node_name string.
node_name	Name of the node this link is connected to.

Enable Function

The Enable function of the link management request message re-enables a link's address entries if they have been disabled. All addresses in the cross-group connection table that match the selection criteria specified in the request message (for example, group number, connect type, node name, and transport address) will be enabled. All other address entries for the group or groups selected will be disabled. The Enable function will still complete if the link is already connected. The effects will not be visible until the existing link is lost.

The Enable function allows a link to occur only with the selected addresses for a group. If the group has a reconnection timer, the timer will be set to cause the connection to be attempted after the specified time and connections are not attempted immediately. Incoming connections are then allowed to occur.

• The Enable function offers the following selection options:

• If the group_number field is set to PSYM_LINKMGT_ALL_GROUPS, then the node name and transport address cannot be specified.

• If a specific group number is specified and PSYM_LINKMGT_ALL_TRANSPORTS is specified, then the node name and transport address cannot be specified.

• On OpenVMS systems, if an entry that matches the selection criteria is not found, one will be created providing the group exists. On UNIX and Windows NT systems, the Enable function only enables existing address entries. It does not modify connection parameters or add new address entries.

• On OpenVMS systems, if the window or reconnect timer information is supplied, the specified values overwrite the existing information of the select entries. On UNIX and Windows NT systems, the Enable function does not modify connection parameters.

  Note: The symbol PSYM_LINKMGT_ALL_TRANSPORTS is new to the LINK_MGT message API for BEA MessageQ Version 4.0. On OpenVMS systems, the Enable function requires that the requesting process have either OPER or the DMQ$OPERATOR rights identifier.

Request Message Format for the Enable Function

Table 5-4 displays the Enable function message format:

Table 5-4 Enable function message format

Field	Required/ Optional	Setting
version	Required	10
user_tag	Required	User-specified code identifying the request.
function_code	Required	PSYM_LINKMGT_CMD_ENABLE
group_number	Required	Group number to receive the action. Valid values are 1 to 32000. Or, use the PSYM_LINKMGT_ALL_GROUPS symbol to enable all known links for groups with the connect_type requested.
connect_type	Required	Select the following transport type: PSYM_LINKMGT_TCPIP
reconnect_timer	Optional	Time it takes for the COM Server or Group Control Process (GCP) to reconnect to a communications link. Enter the number of seconds or the following values: PSYM_LINKMGT_NO_TIMER PSYM_LINKMGT_USE_PREVIOUS
window_size	Optional	Size of transmission window (cross-group protocol Version 3.0 or higher).
window_delay	Optional	Transmission window delay in seconds (cross-group protocol Version 3.0 or higher).
transport_addr	Optional	Transport address string 16 bytes in length; the TCP/IP port ID
transport_addr_len	Optional	Length of transport address. Valid values are 0 to 16 bytes. Zero specifies the use of the previous setting.
node_name	Optional	ASCII text of node name. The length is determined by node_name_len up to 255 characters.
node_name_len	Optional	Length of the node name string. Zero specifies the use of the previous known value.

Determining the Status of the Enable Request

The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Enable request. See Table 5-5 for a description of each status return and the corresponding user action.

Table 5-5 Enable function status returns and user actions

PSYM_LINKMGT Return Code	Description	Outcome	Description/User Action
ALREADYUP	The link is already active	Warning	The Enable function completed although the link entries were already available.
MSGCONTENT	Invalid value in request message	Error	One of the field values in the enable request message is invalid. Check the syntax of the request message against the list of valid values and re-issue the corrected request message.
MSGFMT	Unknown request version or function code	Error	Correct the syntax of the request message. The version field of the must contain the number 10. The function code field must contain the symbol PSYM_LINKMGT_CMD_ENABLE.
NOGROUP	The selected group does not have a cross group entry	Error	No cross-group entries can be enabled because you requested the enable function for a group that is not defined in the cross-group table.
NOTRANSPORT	The selected group does not have any cross-group entries with specified transport	Error	No cross-group entries can be enabled because you requested the enable function for a group or groups that does not have a cross-group connection entry that uses the specified transport.
OPERATIONFAIL	The command was unable to be successfully completed	Error	The enable function failed due to a system resource problem. Check the Connect Server to determine if it is running out of virtual memory. Check the log file to see if the cause of the error has been logged.
SUCCESS	The operation successfully completed.	Success	Refer to the description of the link management response message below for a description of the data returned.

Response Message Format for Successful Enable Requests

If the Enable function is successful, the response message returns the information shown in the following table:

Field	Description
version	10
user_tag	User-specified code from the request message.
status	PAMS__SUCCESS
group_number	Group number or numbers to receive the action.
in_link_state	PSYM_LINKMGT_ENABLED
out_link_state	PSYM_LINKMGT_ENABLED
connect_type	Transport that message is connected over: PSYM_LINKMGT_TCPIP.
platform_id	Connected platform ID (PSYM_PLATFORM_xxxx).
reconnect_time	Reconnect timer value for this group.
window_size	Window size value negotiated for this group.
window_delay	Window delay value negotiated for this group.
transport_addr_len	Length of the transport_addr string.
transport_addr	ASCII representation of either the TCP/IP port number.
node_name_len	Length of the node_name string.
node_name	Name of the node this link is connected to.

Disable Function

The Disable function of the link management request message disables a link's address entries if they have been enabled. This prevents a link from occurring with the group's selected addresses. Connection attempts to and from the selected addresses are prevented.

All addresses in the group address table that match the selection criteria of the message (for example, group ID, connect type, node name, and transport address) will be disabled. All other address entries for the groups selected will not be affected. If no entry matches the group_number field, then PSYM_LINKMGT_NOGROUP is returned.

The Disable function takes matching cross-group entries out of the search list for connect processing.

Request Message Format for the Disable Function

Table 5-6 displays the Disable function message format:

Table 5-6 Disable Function Message Format

Field	Required/ Optional	Setting
version	Required	10
user_tag	Required	User-specified code identifying the request.
function_code	Required	PSYM_LINKMGT_CMD_DISABLE
group_number	Required	Group number to receive the action. Valid values are 1 to 32000. The PSYM_LINKMGT_ALL_GROUPS symbol indicates all known links for this group.
connect_type	Required	Select the following transport type: PSYM_LINKMGT_TCPIP
reconnect_timer	Optional	PSYM_LINKMGT_USE_PREVIOUS
window_size	Optional	PSYM_LINKMGT_USE_PREVIOUS
window_delay	Optional	PSYM_LINKMGT_USE_PREVIOUS
transport_addr	Optional	Transport address string 16 bytes in length; the TCP/IP port ID
transport_addr_len	Optional	Length of transport address. Valid values are 0 to 16 bytes. Zero indicates to use the previous setting.
node_name	Optional	ASCII text of node name. The length is determined by node_name_len up to 255 characters.
node_name_len	Optional	Length of the node name string. Zero indicates to use the previous known value.

Determining the Status of the Disable Request

The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Disable request. See Table 5-7 for a description of each status return and the corresponding user action.

Table 5-7 Disable Function Status Return and User Action

PSYM_LINKMGT Return Code	Description	Outcome	Description/User Action
MSGCONTENT	Invalid value in request message	Error	One of the field values in the disable request message is invalid. Check the syntax of the request message against the list of valid values and re-issue the corrected request message.
MSGFMT	Unknown request version or function code	Error	Correct the syntax of the request message. The version field of the must contain the number 10. The function code field must contain the symbol PSYM_LINKMGT_CMD_DISABLE.
NOGROUP	The selected group does not have a cross group entry	Error	No cross-group entries can be disabled because you requested the disable function for a group that is not defined in the cross-group table.
NOTRANSPORT	The selected group does not have any cross group entries with specified transport	Error	No cross-group entries can be disabled because you requested the disable function for a group or groups that does not have a cross-group connection entry that uses the specified transport.
OPERATIONFAIL	The command was unable to be successfully completed	Error	The disable function failed due to a system resource problem. Check the Connect Server to determine if it is running out of virtual memory. Check the log file to see if the cause of the error has been logged.
SUCCESS	The operation successfully completed.	Success	Refer to the description of the link management response message below for a description of the data returned.

Response Message Format for Successful Disable Requests

If the Disable function completes successfully, the response message contains the -following information:

Field	Description
version	10
user_tag	User-specified code from the request message.
status	PSYM_LINKMGT_SUCCESS
group_number	Group number that receives the action.
in_link_state	PSYM_LINKMGT_DISABLED
out_link_state	PSYM_LINKMGT_DISABLED
connect_type	Transport that message is connected over: PSYM_LINKMGT_TCPIP.
platform_id	Connected platform ID (PSYM_PLATFORM_xxxx).
reconnect_time	Reconnect timer value for this group.
window_size	Window size value negotiated for this group.
window_delay	Window delay value negotiated for this group.
transport_addr_len	Length of the transport_addr string.
transport_addr	ASCII representation of either the TCP/IP port number.
node_name_len	Length of the node_name string.
node_name	Name of the node this link is connected to.

Connect Function

The Connect function of the link management request message re-enables a link's address entries if they have been disabled, and causes an immediate connect attempt to occur with the selected groups if not already connected. Incoming connections are then allowed to occur. This function will still be able to complete even if the link is already connected. The effects of the function will not be visible until the existing link is lost.

All addresses in the group address table that match the selection criteria of the message (for example, group ID, connect type, node name, and transport address) will be enabled, and all other address entries for the groups selected will be disabled. If a matching entry is not found, then one will be created, providing the group exists. If the window or reconnect timer information is supplied, then those values will overwrite the existing information of the selected entries.

If the group_number field is set to PSYM_LINKMGT_ALL_GROUPS, then node name and transport address cannot be specified. If a specific group number is specified, and PSYM_LINKMGT_ALL_TRANSPORTS is specified, then node name and transport address cannot be specified.

On OpenVMS systems, the Connect function requires that the requesting process have either OPER or the DMQ$OPERATOR rights identifier.

Request Message Format for the Connect Function

Table 5-8 displays the Connect request function message format:

Table 5-8 Connect Request Function Message Format

Field	Required/ Optional	Setting
version	Required	10
user_tag	Required	User-specified code identifying the request, if supplied.
function_code	Required	PSYM_LINKMGT_CMD_CONNECT
group_number	Required	Group number to receive the action. Valid values are 1 to 32000. The PSYM_LINKMGT_ALL_GROUPS symbol indicates all known links for this group.
connect_type	Required	Select the following transport type: PSYM_LINKMGT_TCPIP
reconnect_timer	Optional	Time it takes for the COM Server to reconnect to a communications link. Enter the number of seconds or the following values: PSYM_LINKMGT_NO_TIMER PSYM_LINKMGT_USE_PREVIOUS
window_size	Optional	Size of transmission window (cross-group protocol Version 3.0 or higher).
window_delay	Optional	Transmission window delay in seconds (cross-group protocol Version 3.0 or higher).
transport_addr	Optional	Transport address string 16 bytes in length' the TCP/IP port ID
transport_addr_ len	Optional	Length of transport address. Valid values are 0 to 16 bytes. Zero specifies the use of the previous setting.
node_name	Optional	ASCII text of node name. The length is determined by node_name_len up to 255 characters.
node_name_len	Optional	Length of the node name string. Zero specifies the use of the previous known value.

Determining the Status of the Connect Request

The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Connect request. See Table 5-9 for a description of each status return and the corresponding user action.

Table 5-9 Connect function status returns and user actions

PSYM_LINKMGT Return Code	Description	Outcome	Description/User Action
ALREADYUP	The link is already active	Warning	The Connect function completed although the link entries were already available.
MSGCONTENT	Invalid value in request message	Error	One of the field values in the connect request message is invalid. Check the syntax of the request message against the list of valid values and re-issue the corrected request message.
MSGFMT	Unknown request version or function code	Error	Correct the syntax of the request message. The version field of the must contain the number 10. The function code field must contain the symbol PSYM_LINKMGT_CMD_CONNECT.
NOGROUP	The selected group does not have a cross group entry	Error	No cross-group links can be connected because you requested the connect function for a group that is not defined in the cross-group table.
NOTRANSPORT	The selected group does not have any cross group entries with specified transport	Error	No cross-group links can be connected because you requested the connect function for a group or groups that does not have a cross-group connection entry using the specified transport.
OPERATIONFAIL	The command was unable to be successfully completed	Error	The connect function failed due to a system resource problem. Check the Connect Server to determine if it is running out of virtual memory. Check the log file to see if the cause of the error has been logged.
SUCCESS	The operation successfully completed.	Success	Refer to the description of the link management response message below for a description of the data returned.

Response Message Format for Successful Connect Requests

If the Connect request is successful, the response message contains the following -information:

Field	Description
version	10
user_tag	User-specified code from the request message.
status	PSYM_LINKMGT_SUCCESS
group_number	Group number that receives the action.
in_link_state	PSYM_LINKMGT_CONNECTED
out_link_state	PSYM_LINKMGT_CONNECTED
connect_type	Transport that message is connected over: PSYM_LINKMGT_TCPIP.
platform_id	Connected platform ID (PSYM_PLATFORM_xxxx).
reconnect_time	Reconnect timer value for this group.
window_size	Window size value negotiated for this group.
window_delay	Window delay value negotiated for this group.
transport_addr_len	Length of the transport_addr string.
transport_addr	ASCII representation of either the TCP/IP port number.
node_name_len	Length of the node_name string.
node_name	Name of the node this link is connected to.

Disconnect Function

The Disconnect function of the link management request message requests implicit disables of links and disconnects any links to the requested group. All addresses in the group address table that match the selection criteria of the message (for example, group ID, connect type, node name, and transport address) will be disconnected. All other address entries for the groups selected will not be affected. If no entry matches the group_number field, then PSYM_LINKMGT_NOGROUP is returned. On OpenVMS systems, the Disconnect function requires that the requesting process have either OPER or the DMQ$OPERATOR rights identifier.

Request Message Format for the Disconnect Function

Table 5-10 displays the Disconnect function message format.

Table 5-10 Disconnect Function Message Format

Field	Required/ Optional	Setting
version	Required	10
user_tag	Required	User-specified code identifying the request.
function_code	Required	PSYM_LINKMGT_CMD_DISCONNECT
group_number	Required	Group number to receive the action. Valid values are 1 to 32000. The PSYM_LINKMGT_ALL_GROUPS symbol means disconnect all known links for this group.
connect_type	Required	Select the following transport type: PSYM_LINKMGT_TCPIP
reconnect_timer	Optional	PSYM_LINKMGT_USE_PREVIOUS
window_size	Optional	PSYM_LINKMGT_USE_PREVIOUS
window_delay	Optional	PSYM_LINKMGT_USE_PREVIOUS
transport_addr	Optional	Transport address string 16 bytes in length; the TCP/IP port ID
transport_addr_ len	Optional	Length of transport address. Valid values are 0 to 16 bytes. Zero specifies the use of the previous setting.
node_name	Optional	ASCII text of node name. The length is determined by node_name_len up to 255 characters.
node_name_len	Optional	Length of the node name string. Zero specifies the use of the previous known value.

Determining the Status of the Disconnect Request

The status field of the LINKMGT_RESP message contains a return code indicating the outcome of the Disconnect request. Refer to Table 5-11 for a description of each status return and the corresponding user action.

Table 5-11 Disconnect function status returns and user actions

PSYM_LINKMGT Return Code	Description	Outcome	Description/User Action
MSGCONTENT	Invalid value in request message	Error	One of the field values in the disconnect request message is invalid. Check the syntax of the request message against the list of valid values and re-issue the corrected request message.
MSGFMT	Unknown request version or function code	Error	Correct the syntax of the request message. The version field must contain the number 10. The function code field must contain the symbol PSYM_LINKMGT_CMD_DISCONNECT.
NOGROUP	The selected group does not have a cross-group entry	Error	No cross-group connections can be disconnected because you requested the disconnect function for a group that is not defined in the cross-group table.
NOTRANSPORT	The selected group does not have any cross-group entries with specified transport	Error	No cross-group links can be disconnected because you requested the disconnect function for a group or groups that does not have a cross-group connection entry that uses the specified transport.
OPERATIONFAIL	The command was unable to be successfully completed	Error	The disconnect function failed due to a system resource problem. Check the Connect Server to determine if it is running out of virtual memory. Check the log file to see if the cause of the error has been logged.
SUCCESS	The operation successfully completed.	Success	Refer to the description of the link management response message below for a description of the data returned.

Response Message Format for Successful Disconnect Functions

If the Disconnect function is successful, the response message returns the following -information:

Field	Description
version	10
user_tag	User-specified code from the request message.
status	PSYM_LINKMGT_SUCCESS
group_number	Group number that receives the action.
in_link_state	PSYM_LINKMGT_DISABLED
out_link_state	PSYM_LINKMGT_DISABLED
connect_type	Transport that message is connected over: PSYM_LINKMGT_TCPIP.
platform_id	Connected platform ID (PSYM_PLATFORM_xxxx).
reconnect_time	Reconnect timer value for this group.
window_size	Window size value negotiated for this group.
window_delay	Window delay value negotiated for this group.
transport_addr_len	Length of the transport_addr string.
transport_addr	ASCII representation of either the TCP/IP port number.
node_name_len	Length of the node_name string.
node_name	Name of the node this link is connected to.

Link Management Design Considerations

Table 5-12 lists important design considerations for applications using link management.

Table 5-12 Link Management Design Condsiderations

Feature	Description
Failover Node Table Disabled	When an application issues a LINKMGT_REQ request, the Connect Server disables the failover node table defined in the group initialization file. Disabling the failover node table ensures the application complete control over the attributes of the link request.
Additional Group Connections Disabled	When the application issues a LINKMGT_REQ request to disconnect a link, the Connect Server disables further connections to the group. Disabling connections ensures that no additional links to the group will occur until the application issues another LINKMGT_REQ request.
Connect Requests -Verified	When a connect request is made for a single group, the XGROUP_VERIFY table uses the information supplied in the message to determine whether to accept or reject the -request for a connection. Cross-group verification only works on incoming requests. The data structure for cross-group verification is overwritten by the information in the link management connect or disconnect message.
Connect and Disconnect Requests Acknowledged	When the Connect Server receives a connect message after a link is already successfully connected, the Connect Server rejects the second connect message. When the Connect Server receives a disconnect message after a link is already successfully disconnected, the Connect Server acknowledges the second disconnect message with a successful -return message.
Restrictions on Local and Remote Requests	The Connect Server will only accept link control requests from a local application. However, the Connect Server will accept link status inquiries from remote as well as local -applications.
Privileges Required	Application link control requests on the OpenVMS system require that the application have VMS OPER privilege or be granted the DMQ$OPERATOR rights identifier.

Learning the Current Status of Queues

This section describes how applications can use Queue Server message-based services to obtain status information on all active queues in a particular group or to obtain notification of queue status changes. The list of active queues displays all attached permanent and temporary queues.

Listing Attached Queues in a Group

The Queue Server process can provide applications with a list of all attached queues for a selected group. This information is available for local and remote groups and includes a listing of both permanent and temporary queues. To request this list, the application program sends a message of type LIST_ALL_Q_REQ to the Queue Server process.

To learn the status of all queues in a selected group, an application exchanges the following messages with the Queue Server:

• LIST_ALL_Q_REQ-Request message to request the status of all queues.

• LIST_ALL_Q_RESP-Response message to provide a list of all queues and their status.

  Figure 5-5 Listing All Queues

  

The application receives a response message from the Queue Server of type LIST_ALL_Q_RESP providing a list of all attached queues. Because a LIST_ALL_Q_RESP message may contain a long list of queue names, the application must allocate a sufficient buffer size to store the information returned.

Receiving Attachment Notifications

The Queue Server process can notify an application of all attached queues and subsequent queue attachments and detachments for its own group. An application registers for this service by sending a message of type ENABLE_Q_NOTIFY_REQ to the group's Queue Server process. The Queue Server responds with a message of type ENABLE_Q_NOTIFY_RESP, indicating the status of the registration request.

To learn the status of all queues and receive ongoing notification of new queue attachments and detachments, an application exchanges the following messages with the Queue Server:

• ENABLE_Q_NOTIFY_REQ-Request message to request the current status of all queues with notification of future queue status changes.

• ENABLE_Q_NOTIFY_RESP-Response message to provide the current status of all queues and confirmation that queue status changes will be reported.

• Q_UPDATE-Notification message to provide information on newly attached and detached queues in the selected group.

• DISABLE_Q_NOTIFY_REQ-Request message to request that notification of queue status changes be discontinued.

• DISABLE_Q_NOTIFY_RESP-Response message to indicate that notification of queue status changes has been successfully disabled.

  Figure 5-6 Listing Available Queues

  

The registration request places the sender's response queue number in the list of applications to receive notification of new attachments and detachments. Notifications are sent using a message of type Q_UPDATE. The application can cancel the notification registration by sending a message of type DISABLE_Q_NOTIFY_REQ. The Queue Server responds with a reply of type DISABLE_Q_NOTIFY_RESP indicating the status of the registration cancellation request.

Managing Message Recovery Files

BEA MessageQ message-based services are used with the MRS Server to maintain files for recoverable messaging and to turn MRS journaling capability on or off. Message-based services for performing these functions are available on OpenVMS systems only. The functions are also available through the BEA MessageQ Manager Utility on OpenVMS systems. For complete information on how to use the BEA MessageQ message recovery system, see the Sending Recoverable Messages topic.

BEA MessageQ uses the following four BEA MessageQ files for MRS message-based services:

Store and forward file (SAF)	Messages designated for recovery on the sender system.
Destination queue file (DQF)	Messages designated for recovery on the receiver system.
Dead letter journal (DLJ)	Undelivered messages not designated for recovery by BEA MessageQ. These messages can be delivered later from the DLJ by an application program.
Postconfirmation journal (PCJ)	Successfully delivered recoverable messages which form an audit trail of messaging events.

Opening, Closing, and Failing Over SAF and DQF Files

As part of message recovery on OpenVMS systems, the MRS Server opens a SAF or DQF file when a recoverable message is sent to the target queue. The following BEA MessageQ MRS message-based services are used to open, close, or rename message recovery files on Open VMS systems:

• MRS_SAF_SET-Request message to request the MRS Server to open, close, or rename the SAF file.

• MRS_SAF_SET_REP-Response message to indicate the status of the request.

• MRS_DQF_SET-Request message to request the MRS Server to open, close, or rename the file.

• MRS_DQF_SET_REP-Response message to indicate the status of the request.

Figure 5-7, MRS Server Message Flow, describes how to open, close, or rename message recovery files on OpenVMS systems:

Figure 5-7 MRS Server Message Flow

The MRS_DQF_SET message can be used to explicitly control the opening and closing of a DQF file. For example, an OpenVMS application can use the MRS_DQF_SET message to open a DQF file created at runtime in order to adjust its size before it begins storing recoverable messages. The MRS_SAF_SET message performs the same function for the SAF file.

The failover option of the MRS_DQF_SET message renames a DQF file, associating it with a new target queue that does not have a DQF file. The failover operation renames the destination queue file, and the messages in the store and forward (SAF) files directed to the original target are forwarded to the new target queue. You can use the MRS_SAF_SET message to fail over the SAF file.

The MRS_SAF_SET_REP and the MRS_DQF_SET_REP messages are responses to a request to open, close, or fail over an SAF or DQF file. The response message provides the status of the request.

Opening and Closing Auxiliary Journal Files

The dead letter journal (DLJ) file cannot be open simultaneously for read and write operations. For this reason, if an application has the task of delivering messages written to the DLJ file, it must close the current file before it can begin delivering the messages collected in it. The application must also open a new DLJ file to continue collecting undeliverable messages while it delivers the messages.

To open, close, or rename message recovery files on OpenVMS systems, an application exchanges the following messages with the MRS Server:

• MRS_SET_DLJ-Request message to request that the current DLJ file be closed and a new one opened.

• MRS_SET_DLJ_REP-Response message to indicate the status of the request.

• MRS_SET_PCJ-Request message to request that the current PCJ be closed and a new one opened.

• MRS_SET_PCJ_REP-Response message to indicate the status of the request.

Figure 5-8 illustrates the message exchange between the application and the MRS Server.

Figure 5-8 MRS Server Message Flow

The MRS_SET_DLJ message requests the MRS Server to close the current DLJ file and open a new one. The response message MRS_SET_DLJ_REP returns the status of the operation. The file specification for the newly created DLJ file is returned if the file is successfully opened.

As with the DLJ file, the postconfirmation journal (PCJ) file cannot be open simultaneously for read and write operations. For this reason, if an application has the task of reading the PCJ file to write a report of successful messaging transactions, it must first close the current file. The application must also open a new PCJ file to continue collecting successfully delivered recoverable messages.

An MRS_SET_PCJ message requests the MRS Server to close the current PCJ file and open a new one. An MRS_SET_PCJ_REP message is returned to the requestor and includes the status of the operation and the file specification if the file was successfully opened.

Note: In contrast to the MRS messages for opening and closing the SAF and DQF files, the DLJ and PCJ auxiliary recovery journals can be opened and closed in a single operation.

Controlling Journaling to the PCJ File

You can use the messages in Figure 5-9 to disable journaling when replacing a PCJ file and then reenable journaling:

• MRS_JRN_DISABLE-Request message to disable journaling to the PCJ file.

• MRS_JRN_DISABLE_REP-Response message to indicate the status of the request.

• MRS_JRN_ENABLE-Request message to enable journaling to the PCJ file.

• MRS_JRN_ENABLE_REP-Response message to indicate the status of the request.

  Figure 5-9 Disabling Journaling

  

Use the MRS_JRN_DISABLE message to disable journaling to the PCJ when you need to close the PCJ and open a new one. The MRS_JRN_DISABLE_REP message returns the status of the operation. Use the MRS_JRN_ENABLE message to enable journaling after you have opened a new PCJ file. The MRS_JRN_ENABLE_REP message returns the status of the operation.

Transferring the Contents of a Destination Queue File

You use MRS Server messages to transfer the entire contents of a DQF file at once. However, you can use Qtransfer Server messages to request that the contents of a DQF file be transferred one message at a time into another DQF file.

Transferring the contents of one DQF to another queue supports a failover scheme allowing an application on a node that is running to process messages from a DQF file on a node that is not running. Using Qtransfer Server messages you can blend the contents of two DQFs. Qtransfer Server messages are available on OpenVMS systems only.

To transfer the contents of one DQF file to another, an application exchanges the following messages with the Qtransfer Server:

• MRS_DQF_TRANSFER-Request message to request the transfer of the contents of a DQF file to another.

• MRS_DQF_TRANSFER_ACK-Notification message to acknowledge receipt of the request.

• MRS_DQF_TRANSFER_REP-Response message to indicate the final status of the transfer.

  Figure 5-10 Qtransfer Server Message Flow

  

The MRS_DQF_TRANSFER message requests the Qtransfer Server to open a DQF file and send its contents one message at a time to another recoverable queue. By providing a method for blending two recoverable queues, the Qtransfer Server provides a convenient failover mechanism when application processing is conducted on multiple nodes in a distributed processing network.

Using this failover method, when a node fails, Qtransfer Server messages can be used to transfer messages from a recoverable queue on a node that has failed to a recoverable queue on a node that is currently processing messages.

To acknowledge the receipt of an MRS_DQF_TRANSFER message, the Qtransfer Server sends an MRS_DQF_TRANSFER_ACK message. When each message is -successfully stored in the target DQF file, it is deleted from the source DQF file.

When all messages have been successfully stored in the target DQF file, or if an error has stopped the transfer, a message of type MRS_DQF_TRANSFER_REP is sent. The MRS_DQF_TRANSFER_REP message indicates the completion status of a message of type MRS_DQF_TRANSFER.