Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs.beasys.com   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
MessageQ Doc Home   |   Programmer's Guide   |   Previous Topic   |   Next Topic   |   Contents   |   Index

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.

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.

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.

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.

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.

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.

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.

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:

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.

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.

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 use