WebSphere MQ Call Routines

MQGMO

Manipulates WebSphere MQ get message options to be used on a subsequent MQGET call.

Syntax
Arguments
Example

Syntax

CALL MQGMO(hgmo, action, rc <,parms ,value1,value2, ...>);

On input, it specifies a Base SAS internal get message options handle. The handle should be supplied when you are setting or querying an option. The handle is generated as output when action is to generate default WebSphere MQ get options.

action

Character, input

Specifies the desired action of this routine. The following action values are valid:

GEN: Generate a handle representing default get message options as defined by WebSphere MQ.
SET: After a get message options handle has been generated, you can continue to set values as necessary.
INQ: After a get message options handle has been generated, you can query its values.

rc

Numeric, output

Provides the Base SAS return code from this function. If an error occurs, then the return code is nonzero. You can use the Base SAS function SYSMSG() to obtain a textual description of the return code.

parms

Character, input

Specifies an optional string of get message options that you want to set for subsequent MQGET calls. Each option must be separated by a comma and must have a value associated with it in the function's parameter list.

value

Numeric or character, input or output

Provides the value for a get message option specified in the parms string. You must provide a value parameter for each option specified in the parms string and the data type must be of the proper type. Variables used to store character values being returned in an inquiry (INQ action) should be initialized appropriately to guarantee that truncation of a returned value does not occur.

The following get message options (parms) and values are valid:

OPTIONS

Character, input

Specifies a string of the attributes (options) to associate with subsequent MQGET calls. Each option must be separated by a comma.

The following OPTIONS values are valid:

NONE

Used to unset previously set OPTIONS

NO_WAIT (default)

Return immediately if no suitable message

WAIT

Wait for message to arrive

SYNCPOINT

Get message with synchpoint control

NO_SYNCPOINT

Get message without synchpoint control

BROWSE_FIRST

Browse from start of queue

BROWSE_NEXT

Browse from current position in queue

MSG_UNDER_CURSOR

Get message under browse cursor

LOCK

Lock message

This option is not supported on z/OS.

UNLOCK

Unlock message

This option is not supported on z/OS.

BROWSE_MSG_UNDER_CURSOR

Browse message under browse cursor

This option is not supported on z/OS.

FAIL_IF_QUIESCING

Fail if QMgr is quiescing

CONVERT

Convert message data

The following OPTIONS values support WebSphere MQ Version 5.1 and later (these values are not supported on z/OS):

LOGICAL_ORDER: Messages in groups and segments of logical messages are returned in logical order.
COMPLETE_MSG: Only complete logical messages are retrievable.
ALL_MSGS_AVAILABLE: All messages in a group must be available.
ALL_SEGMENTS_AVAILABLE: All segments in a logical message must be available.

Notes:

ACCEPT_TRUNCATED_MSG is not allowed since Base SAS internally maintains resizing of the internal GET buffer to handle any message size.
Specify CONVERT to allow WebSphere MQ to perform data conversion based on the FORMAT of a PUT message via a conversion exit routine that has been previously established at the QMgr. To allow Base SAS to perform the data conversion instead of using a WebSphere MQ conversion exit routine, do not specify the CONVERT option.

WAITINTERVAL

Numeric, input

Amount of time to wait for message to arrive in milliseconds.

RESOLVEDQNAME

Character48, output

Resolved name of destination queue.

SASQSID

Character36, input

A value equal to the environment variable of the same name, a 36-character string. The environment variable can be retrieved using the following in a SAS DATA step:

sid = sysget('SASQSID');

For queues that are monitored by the object spawner, the MsgDeliverySequence property must be set to Priority. For more information about this option, see Using Message Queue Polling with WebSphere MQ.

The following get message options are supported by WebSphere MQ Version 5.1 and later:

MATCHOPTIONS

Character, input

Character string of match options that is used to control selection criteria that are associated with subsequent MQGET calls. Each option must be separated by a comma. The following MATCHOPTIONS values are valid:

NONE

No matches

MSGID

Retrieve message with specified message identifier

CORRELID

Retrieve message with specified correlation identifier

GROUPID

Retrieve message with specified group identifier

This option is not supported on z/OS.

SEQNUMBER

Retrieve message with specified sequence number

This option is not supported on z/OS.

OFFSET

Retrieve message with specified offset

This option is not supported on z/OS.

GROUPSTATUS

Character, output

Flag indicating whether message was retrieved within a group

SEGMENTSTATUS

Character, output

Flag indicating whether message was retrieved within a segment of a logical message

SEGMENTATION

Character, output

Flag indicating whether further segmentation is allowed for the retrieved message

Example

This example generates get message options to wait 3 seconds for a GET message operation.

hgmo=0;
action="GEN";
rc=0;
parms="OPTIONS,WAITINTERVAL";
options="WAIT";
interval=3000;
CALL MQGMO(hgmo, action, rc, parms, options, interval);

Top of Page

MQGMO

Syntax

Arguments