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

This chapter contains detailed descriptions of all BEA MessageQ message-based services alphabetized by message type. Each description lists the message type code name, the name of the BEA MessageQ server performing the service, and a detailed definition of the message area and required arguments to send messages or read response and notification messages using the BEA MessageQ API or scripts. The definition of all BEA MessageQ message-based services messages is now provided in the p_msg.h include file.

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. Each message-based service description notes whether the data structure is RISC aligned and whether the server performs the endian conversion automatically.

Applications can register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. The AVAIL notification message is sent to registered applications when a queue in the selected group becomes active. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message.

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.

Note: The Avail Server performs endian conversion when this message is received between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _AVAIL {
    q_address target_q;
    } AVAIL;

Field	Data Type	Script Format	Description
target_q	q_address	DL	Address of queue that is now available.

Arguments

Argument	Data Type	Mechanism	Prototype	Access
Target	Supplied by AVAIL_REG	Supplied by AVAIL_REG	Target	Supplied by AVAIL_REG
Source	AVAIL_SERVER	PAMS_AVAIL_SERVER	Source	AVAIL_SERVER
Class	PAMS	MSG_CLAS_ PAMS	Class	PAMS
Type	AVAIL	MSG_TYPE_ AVAIL	Type	AVAIL

See Also

• AVAIL_DEREG

• AVAIL_REG

• AVAIL_REG_REPLY

• UNAVAIL

Example

The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.

Applications can register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. When notification messages are no longer needed, the application sends an AVAIL_DEREG message to the Avail Server to cancel registration. 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. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Avail Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _AVAIL_DEREG {
    int16 version;
    int16 filler;
    q_address target_q;
    q_address distribution_q;
    char req_ack;
    } AVAIL_DEREG;

Field	Data Type	Script Format	Description
version	word	DW	Format version number. Must be 20.
filler	word	DW	Spacing for RISC alignment.
target_q	q_address	DL	Queue being monitored for its -availability.
distribution_q	q_address	DL	Queue notified of availability.
req_ack	Boolean	DB	If response required, 1; else 0.

Arguments

Argument	Script Format	pams_get_msg Format
Target	AVAIL_SERVER	PAMS_AVAIL_SERVER
Source	Supplied by BEA MessageQ	Supplied by BEA MessageQ
Class	PAMS	MSG_CLAS_PAMS
Type	AVAIL_DEREG	MSG_TYPE_AVAIL_DEREG

See Also

• AVAIL

• AVAIL_REG

• AVAIL_REG_REPLY

• UNAVAIL

Example

The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.

Applications can register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message. If the application detaches from the distribution queue, the AVAIL registration is automatically deleted. The application must cancel notification, regardless of queue type, by sending a message of type AVAIL_DEREG. The application receives a AVAIL_REG_REPLY message indicating the status of the operation.

Note: The Avail Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _AVAIL_REG {
    int16 version;
    int16 filler;
    q_address target_q;
    q_address distribution_q;
    int32 timeout;
    } AVAIL_REG;

Field	Data Type	Script Format	Description
version	word	DW	Format version number. Must be 31.
filler	word	DW	Spacing for RISC alignment.
target_q	q_address	DL	Queue to be monitored for availability.
distribution_q	q_address	DL	Queue to receive availability messages.
timeout	int32	DL	Interval (specified in seconds) after which the function should timeout.

Arguments

Argument	Script Format	pams_get_msg Format
Target	AVAIL_SERVER	PAMS_AVAIL_SERVER
Source	Supplied by BEA MessageQ	Supplied by BEA MessageQ
Class	PAMS	MSG_CLAS_PAMS
Type	AVAIL_REG	MSG_TYPE_AVAIL_REG

See Also

• AVAIL_REG_REPLY

• AVAIL

• UNAVAIL

• AVAIL_DEREG

Example

The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.

Applications register to receive notification when queues become active or inactive in local and remote groups by sending an AVAIL_REG message to the Avail Server. The AVAIL_REG_REPLY message indicates whether the application has successfully registered or deregistered from receiving notification messages. See the Obtaining the Status of a Queue topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Avail Server performs endian conversion when this message is received between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _AVAIL_REG_REPLY {
    int16 status;
    uint16 reg_id;
    int16 number_reg;
    } AVAIL_REG_REPLY;

Field	Data Type	Script Format	Description
status	word	DW	Status code: 1 = success; 0 = failure.
reg_id	unsigned word	DW	Returned subscription ID.
number_reg	word	DW	Number of registrants left on the Avail list.

Arguments

Argument	Script Format	pams_get_msg Format
Target	Sender of AVAIL_REG/DEREG	Sender of AVAIL_REG/DEREG
Source	AVAIL_SERVER	PAMS_AVAIL_SERVER
Class	PAMS	MSG_CLAS_PAMS
Type	AVAIL_REG_REPLY	MSG_TYPE_AVAIL_REG_REPLY

See Also

• AVAIL_REG

• AVAIL_DEREG

• AVAIL

• UNAVAIL

Example

The AVAIL services example illustrates avail services, avail register, avail deregister, and getting avail messages. The complete code example called x_avail.c is contained in the examples directory.

Applications can register to receive notification when cross-group links are established and lost by sending an ENABLE_NOTIFY message to the Connect Server. When an application no longer needs to receive notification messages, it deregisters by sending a DISABLE_NOTIFY message to the Connect Server. The DISABLE_NOTIFY message can stop notification of cross-group link changes. See the Obtain Notification of Cross-Group Links Established and Lost topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Connect Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _ENABLE_NOTIFY {
    char reserved;
    char connection_flag;
    } ENABLE_NOTIFY;

Field	Data Type	Script Format	Description
reserved	unsigned char	DB	Reserved for use by BEA MessageQ.
connection_flag	unsigned char	DB	Boolean flag to cancel cross-group connection notification, 1; else 0.

Arguments

Argument	Script Format	pams_get_msg Format
Target	CONNECT_SERVER	PAMS_CONNECT_SERVER
Source	Supplied by BEA MessageQ	Supplied by BEA MessageQ
Class	PAMS	MSG_CLAS_PAMS
Type	DISABLE_NOTIFY	MSG_TYPE_DISABLE_NOTIFY

See Also

• ENABLE_NOTIFY

• LINK_COMPLETE

• LINK_LOST

DISABLE_Q_NOTIFY_REQ

Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. The DISABLE_Q_NOTIFY_REQ is sent to the Queue Server when the application no longer needs to receive notification messages. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Queue Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _Q_NOTIFY_REQ {
    int32 version;
    int32 user_tag;
    } Q_NOTIFY_REQ;

Field	Data Type	Script Format	Description
version	int32	DL	Version of request.
user_tag	int32	DL	User-specified code to identify this request.

Arguments

Argument	Script Format	pams_get_msg Format
Target	QUEUE_SERVER	PAMS_QUEUE_SERVER
Source	Requesting program	Requesting program
Class	PAMS	MSG_CLAS_PAMS
Type	DISABLE_Q_NOTIFY_REQ	MSG_TYPE_DISABLE_Q_ NOTIFY_REQ

See Also

• DISABLE_Q_NOTIFY_RESP

• ENABLE_Q_NOTIFY_REQ

• ENABLE_Q_NOTIFY_RESP

• Q_UPDATE

DISABLE_Q_NOTIFY_RESP

Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. The DISABLE_Q_NOTIFY_REQ message is sent to the Queue Server when the application no longer needs to receive notification messages. The DISABLE_Q_NOTIFY_RESP message indicates whether the application is successfully deregistered from receiving notification messages. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Queue Server performs endian conversion when this message is received between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

#define MAX_NUMBER_Q_RECS 50
typedef struct _Q_NOTIFY_RESP {
    int32 version;
    int32 user_tag;
    int32 status_code;
    int32 last_block_flag;
    int32 number_q_recs;
    struct  {
        q_address q_num;
        q_address q_owner;
        int32  q_type;
        int32  q_active_flag;
        int32  q_attached_flag;
        int32  q_owner_pid;
        } q_rec [50];
    } Q_NOTIFY_RESP;

Field	Data Type	Script Format	Description
version	int32	DL	Version of response.
user_tag	int32	DL	User-specified code from request.
status_code	int32	DL	0=Error 1=Success -2=Refused
last_block_flag	int32	DL	Last block Boolean flag.
number_q_recs	int32	DL	Number of records in this message.
q_num	q_address	DL	Queue number.
q_owner	q_address	DL	Queue owner (only for secondary queues (SQs)).
q_type	int32	DL	Queue type (numerically encoded P, S, M).
q_active_flag	int32	DL	Queue active Boolean flag.
q_attached_flag	int32	DL	Queue attached Boolean flag.
q_owner_pid	int32	DL	Queue owner process identification (PID).

Arguments

Argument	Script Format	pams_get_msg Format
Target	Requesting program	Requesting program
Source	QUEUE_SERVER	PAMS_QUEUE_SERVER
Class	PAMS	MSG_CLAS_PAMS
Type	DISABLE_Q_NOTIFY_RESP	MSG_TYPE_DISABLE_Q_ NOTIFY_RESP

See Also

• DISABLE_Q_NOTIFY_REQ

• ENABLE_Q_NOTIFY_REQ

• ENABLE_Q_NOTIFY_RESP

• Q_UPDATE

ENABLE_NOTIFY

Applications can register to receive notification when cross-group links are established and lost by sending an ENABLE_NOTIFY message to the Connect Server. See the Obtain Notification of Cross-Group Links Established and Lost topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Connect Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _ENABLE_NOTIFY {
    char reserved;
    char connection_flag;
    } ENABLE_NOTIFY;

Field	Data Type	Script Format	Description
reserved	unsigned char	DB	Reserved for use by BEA MessageQ.
connection_flag	unsigned char	DB	Boolean flag for cross-group connection notification, 1; else 0.

Arguments

Argument	Script Format	pams_get_msg Format
Target	CONNECT_SERVER	PAMS_CONNECT_SERVER
Source	Supplied by BEA MessageQ	Supplied by BEA MessageQ
Class	PAMS	MSG_CLAS_PAMS
Type	ENABLE_NOTIFY	MSG_TYPE_ENABLE_NOTIFY

See Also

• DISABLE_NOTIFY

• LINK_COMPLETE

• LINK_LOST

ENABLE_Q_NOTIFY_REQ

Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. This message requests a list of all active queues and then subsequent notification when queues become attached or detached and active or inactive. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Queue Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _Q_NOTIFY_REQ {
    int32 version;
    int32 user_tag;
    } Q_NOTIFY_REQ;

Field	Data Type	Script Format	Description
version	int32	DL	Version of request.
user_tag	int32	DL	User-specified code to identify this request.

Arguments

Argument	Script Format	pams_get_msg Format
Target	QUEUE_SERVER	PAMS_QUEUE_SERVER
Source	Requesting program	Requesting program
Class	PAMS	MSG_CLAS_PAMS
Type	ENABLE_Q_NOTIFY_REQ	MSG_TYPE_ENABLE_Q_NOTIFY_REQ

See Also

• DISABLE_Q_NOTIFY_REQ

• DISABLE_Q_NOTIFY_RESP

• ENABLE_Q_NOTIFY_RESP

• Q_UPDATE

ENABLE_Q_NOTIFY_RESP

Applications can register to receive notification when queue states change in local or remote groups by sending an ENABLE_Q_NOTIFY_REQ message. The ENABLE_Q_NOTIFY_RESP message delivers a list of all active queues and then subsequently notifies the application of attachments, detachments, and changes to active and inactive status using the Q_UPDATE message. See the Receiving Attachment Notifications topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Queue Server performs endian conversion when this message is received between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

#define MAX_NUMBER_Q_RECS 50
typedef struct _Q_NOTIFY_RESP {
    int32 version;
    int32 user_tag;
    int32 status_code;
    int32 last_block_flag;
    int32 number_q_recs;
    struct  {
        q_address q_num;
        q_address q_owner;
        int32  q_type;
        int32  q_active_flag;
        int32  q_attached_flag;
        int32  q_owner_pid;
        } q_rec [50];
    } Q_NOTIFY_RESP;

Field	Data Type	Script Format	Description
version	int32	DL	Version of response.
user_tag	int32	DL	User-specified code from request.
status_code	int32	DL	0=Error 1=Success -2=Refused
last_block_flag	int32	DL	Last block Boolean flag.
number_q_recs	int32	DL	Number of records in this message.
q_num	q_address	DL	Queue number.
q_owner	q_address	DL	Queue owner (only for secondary queues (SQs)).
q_type	int32	DL	Queue type (numerically encoded P, S, M).
q_active_flag	int32	DL	Queue active Boolean flag.
q_attached_flag	int32	DL	Queue attached Boolean flag.
q_owner_pid	int32	DL	Queue owner process identification (PID).

Arguments

Argument	Script Format	pams_get_msg Format
Target	Requesting program	Requesting program
Source	QUEUE_SERVER	PAMS_QUEUE_SERVER
Class	PAMS	MSG_CLAS_PAMS
Type	ENABLE_NOTIFY_RESP	MSG_TYPE_ENABLE_NOTIFY_RESP

See Also

• DISABLE_Q_NOTIFY_REQ

• DISABLE_Q_NOTIFY_RESP

• ENABLE_Q_NOTIFY_REQ

• Q_UPDATE

LINKMGT_REQ

Applications can use link management messages to explicitly control cross-group connections. Use the LINKMGT_REQ message to request a connection to a remote group, to disconnect from a remote group, or to obtain information about a remote BEA MessageQ group. See the Controlling Cross-Group Links topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Connect Server performs endian conversion when this message is sent between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _TADDRESS {
    int32 len;
    char str [16];
    } TADDRESS;

typedef struct _NODENAME {
     int32 len;
     char str [255];
     } NODENAME;

typedef struct _LINKMGT_REQ {
    int32 version;
    int32 user_tag;
    int32 function_code;
    int32 group_number;
    int32 connect_type;
    int32 reconnect_timer;
    int32 window_size;
    int32 window_delay;
    int32 reserved_space [10];

    TADDRESS transport_addr;
    NODENAME node_name;
    } LINKMGT_REQ;

Field	Data Type	Script Format	Description
version	int32	DL	Message version.
user_tag	int32	DL	User-specified code to identify this request.
function_code	int32	DL	Function of the message using PSYM_LINKMGT_CMD: _ENABLE _DISABLE _INQUIRY _CONNECT _DISCONNECT
group_number	int32	DL	Group number to receive action; valid values are between 1 and 32,000; PSYM_LINKMGT_ALL_GROUPS indicates all known links.
connect_type	int32	DL	Type of transport to use, as follows: PSYM_LINKMGT_TCPIP
reconnect_timer	int32	DL	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	int32	DL	Size of transmission window (cross-group protocol Version 3.0 and higher). Enter the number of messages or the following value: PSYM_LINKMGT_USE_PREVIOUS
window_delay	int32	DL	Transmission window delay in seconds (cross-group protocol Version 3.0 and higher). Enter the number of seconds or the following value: PSYM_LINKMGT_USE_PREVIOUS
reserved_space	10-int32 array	DL(10)	Reserved for BEA MessageQ use.
transport_addr_len	int32	DL	Length of transport address. Values 0 to 16 bytes; 0 = use previous setting.
transport_addr	char char str *	A	Transport address string that is 16 bytes in length; the TCP/IP port ID.
node_name_len	int32	DL	Length of node name string; 0 = use previous known value.
node_name	char	A	ASCII text of node name; length determined by node_name_len up to 255 characters.

Arguments

Argument	Script Format	pams_get_msg Format
Target	CONNECT_SERVER	PAMS_CONNECT_SERVER
Source	Requesting program	Requesting program
Class	PAMS	MSG_CLAS_PAMS
Type	LINKMGT_REQ	MSG_TYPE_LINKMGT_REQ

See Also

LINKMGT_RESP

Applications can use link management messages to explicitly control cross-group connections. Use the LINKMGT_REQ message to request a connection to a remote group, to disconnect from a remote group, or to obtain information about a remote BEA MessageQ group. The LINKMGT_RESP message notifies the requesting application if the connection or disconnection request was successful and supplies information about the cross-group connection. See the Controlling Cross-Group Links topic in the Using Message-Based Services section for an explanation of how to use this message.

Note: The Connect Server performs endian conversion when this message is received between processes that run on systems that use different hardware data formats. This message is also RISC aligned.

typedef struct _TADDRESS {
    int32 len;
    char str [16];
    } TADDRESS;

typedef struct _NODENAME {
     int32 len;
     char str [255];
     } NODENAME;

typedef struct _LINKMGT_RESP {
    int32 version;
    int32 user_tag;
    int32 status;
    int32 group_number;
    int32 in_link_state;
    int32 out_link_state;
    int32 connect_type;
    int32 platform_id;
    int32 reconnect_timer;
    int32 window_size;
    int32 window_delay;
    int32 reserved_space [10];
    TADDRESS transport_addr;
    NODENAME node_name;
    } LINKMGT_RESP;

Field	Data Type	Script Format	Description
version	int32	DL	Message version.
user_tag	int32	DL	User-specified code from request.
status	int32	DL	Completion status
group_number	int32	DL	Group number to receive action. Valid values are between 1 and 32,000; PSYM_LINKMGT_ALL_GROUPS indicates all known links.
in_link_state	int32	DL	State of inbound link at time of request. Values are: PSYM_LINKMGT_UNKNOWN PSYM_LINKMGT_NOCNT PSYM_LINKMGT_CONNECTED PSYM_LINKMGT_DISABLED
out_link_state	int32	DL	State of outbound link at time of request; same values as in_link_state.
connect_type	int32	DL	Type of transport to use as follows: PSYM_LINKMGT_TCPIP
platform_id	int32	DL	Platform type preceded by the prefix PSYM_PLATFORM. Valid values are: VAX_VMS VAX_ULTRIX RISC_ULTRIX HP9000_HPUX MOTOROLA_VR32 SPARC_SUNOS IBM_RS6000_AIX OS2 MSDOS PDP11_RSX VAXELN MACINTOSH SCO_UNIX M68K VMS_AXP UNIX WINDOWSNT OSF1_AXP DYNIX_X86 UNKNOWN
reconnect_timer	int32	DL	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	int32	DL	Size of transmission window (cross-group protocol Version 3.0 and higher).
window_delay	int32	DL	Transmission window delay in seconds (cross-group protocol Version 3.0 and higher).
reserved_space	10-int32 array	DL(10)	Reserved for BEA MessageQ use.
transport_addr_ len	int32	DL	Length of transport address. Values 0 to 16 bytes; 0 = use previous setting.
transport_addr	char	A	Transport address string 16 bytes in length, the TCP/IP port ID.
node_name_len	int32	DL	Length of node name string. 0 = use previous known value.
node_name	char	A	ASCII text of node name; length determined by node_name_len up to 255 characters.

Status Codes

Status Code	Description
PSYM_LINKMGT_ALREADYUP	Link already connected.
PSYM_LINKMGT_MSGCONTENT	Message incomplete or content inconsistent with dialog.