SAS 9.1.3 Integration Technologies » Developer's Guide

WebSphere MQ Functional Interface

Writing WebSphere MQ Applications

WebSphere MQ Code Samples

WebSphere MQ CALL Routines

	MQCONN
	MQDISC
	MQOPEN
	MQCLOSE
	MQPUT
	MQPUT1
	MQGET
	MQCMIT
	MQBACK
	MQINQ
	MQSET
	MQPMO
	MQGMO
	MQOD
	MQMD
	MQMAP
	MQSETPARMS
	MQGETPARMS
	MQRMH
	MQFREE

Prev | Next | Contents

Application Messaging

WebSphere MQ CALL Routines

MQCONN

Connects Base SAS to a WebSphere MQ queue manager.

Syntax

CALL MQCONN(name, hConn, compCode, reason);

name: Character48, input
Specifies a case-sensitive identifier (name) of the queue manager that has previously been configured by the system administrator.
hConn: Numeric, output
Returns the WebSphere MQ connection handle. This parameter is used by other CALL routines to identify the connection created by MQCONN.
compCode: Numeric, output
Returns the WebSphere MQ completion code. This parameter can be used to determine if an error occurred during the execution of this routine. If an error occurred, the compCode parameter will be non-zero, and the reason parameter will be set to the appropriate reason code.
reason: Numeric, output
Returns the WebSphere MQ reason code that qualifies compCode.
Note: A reason code of -1 reflects a SAS internal error, not a WebSphere MQ error. To obtain a textual description of a failure (either Base SAS or WebSphere MQ), use the SYSMSG() Base SAS function call.

Example

The following example connects the Base SAS session to the queue manager named TEST.

   hConn=0;
   Name="TEST";
   compCode=0;
   reason=0;
   CALL MQCONN(Name, hConn, compCode, reason);

MQDISC

Breaks the connection between a WebSphere MQ queue manager and Base SAS.

Syntax

CALL MQDISC(hConn, compCode, reason);

hConn: Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).
compCode: Numeric, output
Returns the WebSphere MQ completion code. This parameter can be used to determine if an error occurred during the execution of this routine. If an error occurred, compCode will be non-zero, and the reason parameter will be set to the appropriate reason code.
reason: Numeric, output
Returns the WebSphere MQ reason code that qualifies compCode.
Note: A reason code of -1 reflects a Base SAS internal error, not a WebSphere MQ error. To obtain a textual description of a failure (either Base SAS or WebSphere MQ), use the SYSMSG() Base SAS function call.

Example

The following example disconnects the Base SAS session from a queue manager identified by the parameter hConn.

   compCode=0;
   reason=0;
   CALL MQDISC(hConn, compCode, reason);

MQOPEN

Establishes access to a WebSphere MQ object (queue, process definition, or queue manager).

Syntax

CALL MQOPEN(hConn, hod, options, hObj, compCode, reason <, compCode1, reason1, compCode2, reason2, ...>);

hConn

Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).

hod

Numeric, input
Specifies the Base SAS internal object descriptor handle obtained from a previous MQOD function call.

options

Character, input
Specifies a String of open options each separated by a comma. The following open options are valid:

INPUT_AS_Q_DEF: Open to get messages using queue-defined default.
INPUT_SHARED: Open to get messages with shared access.
INPUT_EXCLUSIVE: Open to get messages with exclusive access.
BROWSE: Open to browse messages.
OUTPUT: Open to put messages.
INQUIRE: Open to query object attributes.
SET: Open to set object attributes.
SAVE_ALL_CONTEXT: Save context when message is received.
PASS_IDENTITY_CONTEXT: Allow identity context to be passed.
PASS_ALL_CONTEXT: Allow all context to be passed.
SET_IDENTITY_CONTEXT: Allow identity context to be set.
SET_ALL_CONTEXT: Allow all context to be set.
ALTERNATE_USER_AUTHORITY: Validate with specified user identifier.
FAIL_IF_QUIESCING: Fail if QMgr is quiescing.

hObj

Numeric, output
Returns the WebSphere MQ handle that will be used in subsequent message queuing calls to identify the object being accessed (a queue, a process definition, or queue manager).

compCode

Numeric, output
Returns the WebSphere MQ completion code. This parameter can be used to determine if an error occurred during the execution of this routine. If an error occurred, the compCode parameter will be non-zero, and the reason parameter will be set to the appropriate reason code.

reason

Numeric, output
Returns the WebSphere MQ reason code that qualifies compCode.

Note: A reason code of -1 reflects a Base SAS internal error, not a WebSphere MQ error. To obtain a textual description of a failure (either Base SAS or WebSphere MQ), use the SYSMSG() Base SAS function call.

compCodex, reasonx

Numeric, output
The compCodex and reasonx are an optional series of paired values that can be used when opening a distribution list in order to discern failures for specific queues within the distribution list. These parameters support features of WebSphere MQ Version 5.1 and later.

Example

This example opens a queue for input and output.

   options="INPUT_SHARED,OUTPUT";
   hObj=0;
   compCode=0;
   reason=0;
   CALL MQOPEN(hConn, hod, options, hObj, 
      compCode, reason);

MQCLOSE

Relinquishes access to a WebSphere MQ object (queue, process definition, queue manager).

Syntax

CALL MQCLOSE(hConn, hObj, options, compCode, reason);

hConn

Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).

hObj

Numeric, input
The hObj Specifies the WebSphere MQ handle to an open object that was obtained from a previous MQOPEN call.

options

Character, input
Specifies a string of options each separated by a comma. The following close options are valid:

NONE: No optional close processing required.
DELETE: Delete the permanent dynamic queue if no messages exist and no uncommitted get or put request is outstanding.
DELETE_PURGE: Delete and purge any messages on the permanent dynamic queue if no uncommitted get or put request is outstanding.

compCode

reason

Numeric, output
Returns the WebSphere MQ reason code that qualifies the completion code.

Note: A reason code of -1 reflects a Base SAS internal error, not an WebSphere MQ error. To obtain a textual description of a failure (either Base SAS or WebSphere MQ), use the SYSMSG() Base SAS function call.

Example

This example closes a queue.

   options="NONE";
   compCode=0;
   reason=0;
   CALL MQCLOSE(hConn, hObj, options, compCode, reason);

MQPUT

Puts a message on a WebSphere MQ queue that has been previously opened.

Syntax

CALL MQPUT(hConn, hObj, hmd, hpmo, hData, compCode, reason <, compCode1, reason1, compCode2, reason2, ...>);

hConn

Numeric, input
Specifies the WebSphere MQ Connection handle obtained from a previous MQCONN function call.

hObj

Numeric, input
Specifies the WebSphere MQ handle to an open object that was obtained from a previous MQOPEN call.

hmd

Numeric, input
Specifies the Base SAS internal message descriptor handle obtained from a previous MQMD function call.

hpmo

Numeric, input
Specifies the Base SAS internal put message options handle obtained from a previous MQPMO function call.

hData

Numeric, input
Specifies the Base SAS internal data descriptor handle obtained from a previous MQSETPARMS function call. If set to zero, it is assumed that no data will accompany this message.

For WebSphere MQ Version 5.1 and later, hData can also represent a reference message header obtained from a previous MQRMH function call.

compCode

reason

Numeric, output
Returns the WebSphere MQ reason code that qualifies compCode.

compCodex, reasonx

Example

This example sends a message to a queue.

   compCode=0;
   reason=0;
   CALL MQPUT(hConn, hObj, hmd, hpmo, hData, 
      compCode, reason);

MQPUT1

Sends a single message, often a reply, to a queue.

Syntax

CALL MQPUT1(hConn, hod, hmd, hpmo, hData, compCode, reason <, compCode1, reason2, compCode2, reason2, ...>);

hConn

Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).

hod

Numeric, input
Specifies the Base SAS internal object descriptor handle obtained from a previous MQOD function call.

hmd

Numeric, input
Specifies the Base SAS internal message descriptor handle obtained from a previous MQMD function call.

hpmo

Numeric, input
Specifies the Base SAS internal put message options handle obtained from a previous MQPMO function call.

hData

Numeric, input
Specifies the Base SAS internal data descriptor handle obtained from a previous MQSETPARMS function call. If set to zero, it is assumed that no data will accompany this message.

For WebSphere MQ Version 5.1 and later, hData can also represent a reference message header obtained from a previous MQRMH function call.

compCode

reason

Numeric, output
Returns the WebSphere MQ reason code that qualifies the completion code.

compCodex, reasonx

Details

Essentially, the MQPUT1 routine performs an MQOPEN, MQPUT and MQCLOSE in one API call. Note that the queue does not have to be open prior to making this call. Also note that the queue will be closed during the execution of this call.

Example

This example sends a message to a queue that might not already be opened.

   compCode=0;
   reason=0;
   CALL MQPUT1(hConn, hod, hmd, hpmo, hData, 
      compCode, reason);

MQGET

Retrieves a message from a local WebSphere MQ queue that has been previously opened.

Syntax

CALL MQGET(hConn, hObj, hmd, hgmo, msglen, compCode, reason);

hConn: Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).
hObj: Numeric, input
Specifies the WebSphere MQ handle to an open object that was obtained from a previous MQOPEN call.
hmd: Numeric, input
Specifies the Base SAS internal message descriptor handle obtained from a previous MQMD function call.
hgmo: Numeric, input
Specifies the Base SAS internal get message options handle obtained from a previous MQGMO function call.
msglen: Numeric, output
Returns the length of the received message. A length of zero signifies a message with no data, in which case there will be no need to call MQGETPARMS.
compCode: Numeric, output
Returns the WebSphere MQ completion code. This parameter can be used to determine if an error occurred during the execution of this routine. If an error occurred, the compCode parameter will be non-zero, and the reason parameter will be set to the appropriate reason code.
reason: Numeric, output
Returns the WebSphere MQ reason code that qualifies the completion code.
Note: A reason code of -1 reflects a Base SAS internal error, not a WebSphere MQ error. To obtain a textual description of a failure (either Base SAS or WebSphere MQ), use the SYSMSG() Base SAS function call.

Details

If data accompanies the message, it is retrieved into an internal Base SAS buffer. After the MQGET call completes, you should call MQGETPARMS to set Base SAS variables (parms) to that data or to retrieve the data into a physical binary or text file.

Example

This example gets a message from a queue.

   msglen=0;
   compCode=0;
   reason=0;
   CALL MQGET(hConn, hObj, hmd, hgmo, msglen, 
      compCode, reason);

MQCMIT

Commits all WebSphere MQ message puts and gets since the last syncpoint.

Syntax

CALL MQCMIT(hConn, compCode, reason);

hConn: Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).
compCode: Numeric, output
Returns the WebSphere MQ completion code. This parameter can be used to determine if an error occurred during the execution of this routine. If an error occurred, the compCode parameter will be non-zero, and the reason parameter will be set to the appropriate reason code.
reason: Numeric, output
Returns the WebSphere MQ reason code that qualifies the completion code.
Note: A reason code of -1 reflects a Base SAS internal error, not a WebSphere MQ error. To obtain a textual description of a failure (either Base SAS or WebSphere MQ), use the SYSMSG() Base SAS function call.

Example

This example commits a unit of work.

   compCode=0;
   reason=0;
   CALL MQCMIT(hConn, compCode, reason);

MQBACK

Backs out all WebSphere MQ message puts and gets since the last syncpoint.

Syntax

CALL MQBACK(hConn, compCode, reason);

hConn: Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).
compCode: Numeric, output
Returns the WebSphere MQ completion code. This parameter can be used to determine if an error occurred during the execution of this routine. If an error occurred, the compCode parameter will be non-zero, and the reason parameter will be set to the appropriate reason code.
reason: Numeric, output
Returns the WebSphere MQ reason code that qualifies the completion code.
Note: A reason code of -1 reflects a Base SAS internal error, not a WebSphere MQ error. To obtain a textual description of a failure (either Base SAS or WebSphere MQ), use the SYSMSG() Base SAS function call.

Example

This example reverts the messages in a queue back to the last synchronization point.

   compCode=0;
   reason=0;
   CALL MQBACK(hConn, compCode, reason);

MQINQ

Queries the attributes of a WebSphere MQ object (queue, process definition, queue manager).

Syntax

CALL MQINQ(hConn, hObj, compCode, reason, parms, value1 <,value2, ...>);

hConn

Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).

hObj

Numeric, input
Specifies the WebSphere MQ Object handle obtained from a previous MQOPEN function call that specified the INQUIRE option. This handle can represent a queue, process definition, or queue manager object.

compCode

reason

Numeric, output
Returns the WebSphere MQ reason code that qualifies the completion code.

parms

Character, input
Specifies a string of attributes that you want to query from the WebSphere MQ object. Each object attribute is separated by a comma. The value associated with each attribute is returned in a value parameter.

Not all attributes are valid for each type of object (queue, process definition, or queue manager). Valid object types are listed under each attribute.

value

Numeric/character, output
Returns the value for an attribute specified in the parms string. You must provide a value parameter for each attribute specified parms string. Variables used to store character values should be initialized appropriately to guarantee that truncation of a returned value does not occur.

The following attributes, objects, and value types are valid:

Numeric Output Types:

APPL_TYPE: (Process Definition)
Application type
CODED_CHAR_SET_ID: (Queue Manager)
Coded character set identifier
CURRENT_Q_DEPTH: (Queue)
Number of messages on queue
DEF_INPUT_OPEN_OPTION: (Queue)
Default open-for-input option
DEF_PERSISTENCE: (Queue)
Default message persistence
DEF_PRIORITY: (Queue)
Default message priority
DEFINITION_TYPE: (Queue)
Queue definition type
HARDEN_GET_BACKOUT: (Queue)
Whether to harden backout count
INHIBIT_GET: (Queue)
Whether get operations are allowed
INHIBIT_PUT: (Queue)
Whether put operations are allowed
MAX_HANDLES: (Queue Manager)
Maximum number of handles
USAGE: (Queue)
Usage
MAX_MSG_LENGTH: (Queue Manager and Queue)
Maximum message length
MAX_PRIORITY: (Queue Manager)
Maximum priority
MAX_Q_DEPTH: (Queue)
Maximum number of messages allowed on queue
MSG_DELIVERY_SEQUENCE: (Queue)
Whether message priority is relevant
OPEN_INPUT_COUNT: (Queue)
Number of MQOPEN calls that have the queue open for input
OPEN_OUTPUT_COUNT: (Queue)
Number of MQOPEN calls that have the queue open for output
Q_TYPE: (Queue)
Queue type
RETENTION_INTERVAL: (Queue)
Queue retention interval
BACKOUT_THRESHOLD: (Queue)
Backout threshold
SHAREABILITY: (Queue)
Whether queue can be shared
TRIGGER_CONTROL: (Queue)
Trigger control
TRIGGER_INTERVAL: (Queue Manager)
Trigger interval
TRIGGER_MSG_PRIORITY: (Queue)
Threshold message priority for triggers
TRIGGER_TYPE: (Queue)
Trigger type
TRIGGER_DEPTH: (Queue)
Trigger depth
SYNCPOINT: (Queue Manager)
Syncpoint availability
COMMAND_LEVEL: (Queue Manager)
Command level supported by queue manager
PLATFORM: (Queue Manager)
Platform on which the queue manager resides
MAX_UNCOMMITTED_MSGS: (Queue Manager)
Maximum number of uncommitted messages within a unit of work
Q_DEPTH_HIGH_LIMIT: (Queue)
High limit for queue depth
Q_DEPTH_LOW_LIMIT: (Queue)
Low limit for queue depth
Q_DEPTH_MAX_EVENT: (Queue)
Control attribute for queue depth max events
Q_DEPTH_HIGH_EVENT: (Queue)
Control attribute for queue depth high events
Q_DEPTH_LOW_EVENT: (Queue)
Control attribute for queue depth low events
SCOPE: (Queue)
Queue definition scope
Q_SERVICE_INTERVAL_EVENT: (Queue)
Control for queue service interval events
AUTHORITY_EVENT: (Queue Manager)
Control attribute for authority events
INHIBIT_EVENT: (Queue Manager)
Control attribute for inhibit events
LOCAL_EVENT: (Queue Manager)
Control attribute for local events
REMOTE_EVENT: (Queue Manager)
Control attribute for remote events
START_STOP_EVENT: (Queue Manager)
Control attribute for start stop events
PERFORMANCE_EVENT: (Queue Manager)
Control attribute for performance events
Q_SERVICE_INTERVAL: (Queue)
Limit for queue service interval

Character8 Output Types:

CREATION_TIME: (Queue)
Queue creation time

Character12 Output Types:

CREATION_DATE: (Queue)
Queue creation date

Character48 Output Types:

BASE_Q_NAME: (Queue)
Name of queue to which alias resolves
COMMAND_INPUT_Q_NAME: (Queue Manager)
System command input queue name
DEAD_LETTER_Q_NAME: (Queue Manager)
Dead letter queue name
INITIATION_Q_NAME: (Queue)
Initiation queue name
PROCESS_DESC: (Process Definition)
Description of process definition
PROCESS_NAME: (Process Definition and Queue)
Name of process definition
Q_MGR_NAME: (Queue Manager)
Queue manager name
Q_NAME: (Queue)
Queue name
REMOTE_Q_MGR_NAME: (Queue)
Name of remote queue manager
REMOTE_Q_NAME: (Queue)
Name of remote queue as known on remote queue manager
BACKOUT_REQ_Q_NAME: (Queue)
Excessive backout requeue name
XMIT_Q_NAME: (Queue)
Default transmission queue name

Character64 Output Types:

Q_DESC: (Queue)
Queue description
Q_MGR_DESC: (Queue Manager)
Queue manager description
TRIGGER_DATA: (Queue)
Trigger data

Character128 Output Types:

ENV_DATA: (Process Definition)
Environment data
USER_DATA: (Process Definition)
User data

Character256 Output Types:

APPL_ID: (Process Definition)
Application identifier

Example

This example queries about a queue's maximum depth and the maximum message length.

   length parms $ 30;
   compCode=0;
   reason=0;
   parms="MAX_Q_DEPTH,MAX_MSG_LENGTH";
   CALL MQINQ(hConn, hObj, compCode, 
      reason, parms, maxdepth, maxmsgl);

MQSET

Changes the attributes of a queue object.

Syntax

CALL MQSET(hConn, hObj, compCode, reason, parms, value1 <,value2, ...>);

hConn

Numeric, input
Specifies the WebSphere MQ connection handle (obtained from a previous MQCONN function call).

hObj

Numeric, input
Specifies the WebSphere MQ object handle obtained from a previous MQOPEN function call that specified the SET option. This handle represents a queue object.

compCode

reason

Numeric, output
Returns the WebSphere MQ reason code that qualifies the completion code.

parms

Character, input
Specifies a string of queue attributes that you want to set for a WebSphere MQ queue. Each queue attribute must be separated by a comma and must have a value associated with it. Only certain attributes (a subset of list for MQINQ) can be changed using this function call. Refer to the IBM WebSphere MQ documentation for more details.

value

Numeric/character, input
Provides the value for an attribute specified in the parms string. You must provide a value parameter for each attribute specified in the parms string and the data type must be of the proper type.

Example

This example changes the queue properties by inhibiting messages to be sent (put) to the queue.

   length parms $ 30;
   compCode=0;
   reason=0;
   parms="INHIBIT_PUT";
   inhibit=1;
   CALL MQSET(hConn, hObj, compCode, 
      reason, parms, inhibit);

MQPMO

Manipulates WebSphere MQ put message options to be used on a subsequent MQPUT call.

Syntax

CALL MQPMO(hpmo, action, rc <,parms ,value1, value2, ...>);

hpmo

Numeric, input/output
On input, it specifies the Base SAS internal put 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 put options.

action

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

GEN: Generate a handle representing default put message options as defined by WebSphere MQ.
SET: After a put message options handle has been generated, you can continue to set values as necessary.
INQ: After a put 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 occurred, the return code will be non-zero. The Base SAS function SYSMSG() can be used to obtain a textual description of the return code.

parms

Character, input
Specifies an optional string of put message options that you want to set for subsequent MQPUT 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/Character, input/output
Provides the value for an 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 put message options (parms) are valid:

CONTEXT: Numeric, input
Object handle of input queue.
RESOLVEDQNAME: Character48, output
Resolved name of destination queue.
RESOLVEDQMGRNAME: Character48, output
Resolved name of destination queue manager.
OPTIONS: Character, input
Character string of the attributes (options) to associate with subsequent MQPUT calls. Each option must be separated by a comma.

The following OPTIONS values are valid:

NONE: Default
SYNCPOINT: Put message inside current unit of work
NO_SYNCPOINT: Put message outside current unit of work
DEFAULT_CONTEXT: Associate default context with the message
PASS_IDENTITY_CONTEXT: Pass identity context from an input queue handle
PASS_ALL_CONTEXT: Pass all context from an input queue handle
SET_IDENTITY_CONTEXT: Set identity context from the application
SET_ALL_CONTEXT: Set all context from the application
ALTERNATE_USER_AUTHORITY: Validate with specified user identifier
FAIL_IF_QUIESCING: Fail if QMgr is quiescing
NO_CONTEXT: Associate no context with the message

The following OPTIONS values support WebSphere MQ Version 5.1 and later:

NEW_MSGID: Generate a new message identifier
NEW_CORRELID: Generate a new correlation identifier
LOGICAL_ORDER: Messages in groups and segments will be put in logical order

Example

This example demonstrates the generate, set and inquire actions of MQPMO routine.

   length parms $ 30;
   length rq rqmgr $ 48;

   /* generate default put message options */
   hpmo=0;
   action="GEN";
   rc=0;
   CALL MQPMO(hpmo, action, rc);

   /* set non-default put message options parameters */
   action="SET";
   parms="OPTIONS";
   options="SYNCPOINT,FAIL_IF_QUIESCING";
   CALL MQPMO(hpmo, action, rc, parms, options);

   /* inquire about resolved names after successful PUT */
   action="INQ";
   parms="RESOLVEDQNAME,RESOLVEDQMGRNAME";
   CALL MQPMO(hpmo, action, rc, parms, rq, rqmgr);

MQGMO

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

Syntax

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

hgmo

Numeric, input/output
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

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/character, input/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 syncpoint control
NO_SYNCPOINT: Get message without syncpoint 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
UNLOCK: Unlock message
BROWSE_MSG_UNDER_CURSOR: Browse message under browse cursor
FAIL_IF_QUIESCING: Fail if QMgr is quiescing
CONVERT: Convert message data

The following OPTIONS values support WebSphere MQ Version 5.1 and later:

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 will internally maintain 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, then 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. See Using the Object Spawner Message Queue Polling Support for more information about this option.

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

MATCHOPTIONS

Character, input
Character string of match options used to control selection criteria 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
SEQNUMBER: Retrieve message with specified sequence number
OFFSET: Retrieve message with specified offset

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);

MQOD

Manipulates object descriptor parameters to be used on a subsequent MQOPEN or MQPUT1 call.

Syntax

CALL MQOD(hod, action, rc <,parms ,value1, value2, ...>);

hod

Numeric, input/output
On input, it specifies a Base SAS internal object descriptor handle. The handle should be supplied when you are setting or querying a value. The handle is generated as output when action is to generate default object descriptor parameters.

action

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

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

rc

parms

Character, input
Specifies an optional string of object descriptor parameters that you want to set for subsequent MQOPEN or MQPUT1 calls. Each parameter must be separated by a comma and must have a value associated with it in the function's parameter list.

value

Numeric/character, input/output
Provides a value for an object descriptor parameter specified in the parms string. You must provide a value parameter for each object descriptor parameter 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 object descriptor parameters (parms) and values are valid:

OBJECTTYPE

Character, input
A string containing the object type. Possible OBJECTTYPE values are as follows:

Q (queue)
PROCESS (process)
Q_MGR (queue manager)

OBJECTNAME

Character48, input/output
Object name

OBJECTQMGRNAME

Character48, input/output
Object queue manager name

DYNAMICQNAME

Character48, input
Dynamic queue name.

ALTERNATEUSERID

Character12, input
Alternate user identifier

The following parameters support WebSphere MQ Version 5.1 and later:

DISTLIST: Character, input
Character string of queues in a distribution list each separated by commas (input). The format of a queue name is <qmgr.>queue.

Example

This example generates an object descriptor to OPEN a temporary dynamic queue that begins with the name Base SAS and is unique within the system. The example then queries the name of the temporary dynamic queue that was created after a successful OPEN.

   length qname $ 48;
   hod=0;
   action="GEN";
   rc=0;
   parms="OBJECTNAME,DYNAMICQNAME"
   model="SAMPLE.TEMP.MODEL";
   qname="SAS*";
   CALL MQOD(hod, action, rc, parms, model, qname);

   action="INQ";
   parms="OBJECTNAME";
   CALL MQOD(hod, action, rc, parms, qname);

   put 'dynamic queue name = ' qname;

MQMD

Manipulates message descriptor parameters to be used on a subsequent MQPUT, MQPUT1 or MQGET call.

Syntax

CALL MQMD(hmd, action, rc <,parms ,value1, value2, ...>);

hmd

Numeric, input/output
On input, specifies a Base SAS internal message descriptor handle. The handle should be supplied when you are setting or querying a value. The handle is generated as output when action is to generate default "message descriptor" parameters.

action

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

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

rc

parms

Character, input
Specifies an optional string of message descriptor parameters that you want to set for subsequent MQPUT, MQPUT1 or MQGET calls. Each parameter must be separated by a comma and must have a value associated with it in the function's parameter list.

value

Numeric/Character, input/output
Provides a value for a message descriptor parameter specified in the parms string. You must provide a value parameter for each message descriptor parameter 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.

Note: This routine supports both sending a message (MQPUT and MQPUT1) and receiving a message (MQGET). Therefore, the parameters and values serve as both input and as output to the function.

The following message descriptor parameters (parms) and values are valid:

REPORT

Character, input (PUT call) / output (GET call)
Character string of the report options to associate with subsequent function calls. Each option must be separated by a comma.

Possible REPORT option values are as follows:

NONE: No reports required
PASS_CORREL_ID: Pass correlation identifier
PASS_MSG_ID: Pass message identifier
COA: Confirmation-on-arrival reports required
COA_WITH_DATA: Confirmation-on-arrival reports with data required
COA_WITH_FULL_DATA: Confirmation-on-arrival reports with full data required
COD: Confirmation-on-delivery reports required
COD_WITH_DATA: Confirmation-on-delivery reports with data required
COD_WITH_FULL_DATA: Confirmation-on-delivery reports with full data required
EXPIRATION: Expiration reports required
EXPIRATION_WITH_DATA: Expiration reports with data required
EXPIRATION_WITH_FULL_DATA: Expiration reports with full data required
EXCEPTION: Exception reports required
EXCEPTION_WITH_DATA: Exception reports with data required
EXCEPTION_WITH_FULL_DATA: Exception reports with full data required
DISCARD_MSG: Discard message if undeliverable

The following REPORT option values support WebSphere MQ Version 5.1 and later:

PAN: Positive action notification report required
NAN: Negative action notification report required

MSGTYPE

Numeric, input (Put call)/output (Get call)
Message type. WebSphere MQ reserves the following message types:

1: MQMT_REQUEST
2: MQMT_REPLY
3: MQMT_REPORT
8: MQMT_DATAGRAM

Note: Application defined message types start at 65536 (MQMT_APPL_FIRST).

EXPIRY

Numeric, input (Put call)/output (Get call)
Expiry time

FEEDBACK

Numeric, input (Put call)/output (Get call)
Feedback code

ENCODING

Numeric, input (Put call)/output (Get call)
Data encoding

CODEDCHARSETID

Numeric, input (Put call)/output (Get call)
Coded character set identifier

FORMAT

Character8, input (Put call)/output (Get call)
Format name

PRIORITY

Numeric, input (Put call)/output (Get call)
Message priority

PERSISTENCE

Character, input (Put call)/output (Get call)
Message persistence. Possible persistence values are as follows:

NOT_PERSISTENT: Message is not persistent
PERSISTENT: Message is persistent
PERSISTENT_AS_Q_DEF: Message has default persistence

MSGID

Character, input/output
Message identifier character string representing binary data (2x24 characters: binary format).

CORRELID

Character, input (PUT call) / input/output (GET call)
Correlation identifier character string representing binary data (2x24 characters: binary format).

BACKOUTCOUNT

Numeric, output (GET call)
Backout counter

REPLYTOQ

Character48, input (PUT call) / output (GET call)
Name of reply-to-queue

REPLYTOQMGR

Character, input (PUT call) / output (GET call)
Name of reply queue manager

USERIDENTIFIER

Character12, input/output (PUT call) / output (GET call)
User identifier

ACCOUNTINGTOKEN

Character, input/output (PUT call) / output( GET call)
Accounting token character string representing binary data (2x32 characters: binary format).

APPLIDENTITYDATA

Character32, input/output (PUT call) / output (GET call)
Application data relating to identity

PUTAPPLTYPE

Numeric, input/output (PUT call) / output (GET call)
Type of application that put the message

PUTAPPLNAME

Character28, input/output (PUT call) / output (GET call)
Name of application that put the message

PUTDATE

Character8, input/output (PUT call) / output (GET call)
Date when message was put

PUTTIME

Character8, input/output (PUT call) / output (GET call)
Time when message was put on the queue

APPLORIGINDATA

Character4, input/output (PUT call) / output (GET call)
Application data relating to origin

The following parameters/values support WebSphere MQ Version 5.1 and later:

GROUPID

Character, input/output (PUT call) / input/output (GET call)
Group identifier character string representing binary data (2x24 characters: binary format).

MSGSEQNUMBER

Numeric, input/output (PUT call) / input/output (GET call)
Sequence number of logical message within group

OFFSET

Numeric, input/output (PUT call) / input/output (GET call)
Offset of data in physical message from start of logical message

MSGFLAGS

Numeric, input (PUT call) / output (GET call)
The following message flags are supported:

1: MQMF_SEGMENTATION_ALLOWED
2: MQMF_SEGMENT
4: MQMF_LAST_SEGMENT
8: MQMF_MSG_IN_GROUP
16: MQMF_LAST_MSG_IN_GROUP

Notes:

ENCODING and CODEDCHARSETID should not be set in most situations since you want a message to be described by its native numeric and character encoding which is the default attributes for these parms.
FORMAT should be set if you intend for a WebSphere MQ QMgr conversion exit to be invoked when an application GETs a message. The FORMAT name is the actual name of the conversion exit that will be invoked when an application GETs a message with the CONVERT get message option specified. The FORMAT name in the message descriptor is set when a message is PUT on a queue. Refer to WebSphere MQ literature for details on creating a conversion exit.
MSGID and CORRELID are updated on PUTs and GETs so remember to reset their values appropriately when performing multiple PUTs or GETs with the same message descriptor.

Example

This example sends a message to a queue, and then queries and displays the message descriptor values.

   length parms $ 57;
   length report $ 30 msgtype $ 8 msgid $ 48 correlid $48
      applname $ 28 putdate $ 8 puttime $ 8;

   /* generate a message descriptor to PUT a persistent */
   /* message on a permanent queue                       */
   hmd=0;
   action="GEN";
   rc=0;
   parms="PERSISTENCE"
   persist="PERSISTENT";
   CALL MQMD(hmd, action, rc, parms, persist);

   /* inquire about message descriptor values after GET  */
   /* operation completes successfully                   */
   action="INQ";
   parms="REPORT,MSGTYPE,MSGID,CORRELID,
      PUTAPPLNAME,PUTDATE,PUTTIME";
   CALL MQMD(hmd, action, rc, parms, report, msgtype, 
      msgid, correlid, applname, putdate, puttime);

   put 'report type is ' report;
   put 'message type is ' msgtype;
   put 'message id is ' msgid;
   put 'correlation id is ' correlid;
   put 'put application name is ' applname;
   put 'put date is ' putdate;
   put 'put time is ' puttime;

MQMAP

Defines a data map that can be subsequently used on a MQSETPARMS or MQGETPARMS call.

Syntax

CALL MQMAP(hMap, rc, desc1 <,desc2, desc3, ...>);

hMap

Numeric, output
Returns a Base SAS internal map descriptor handle. The handle generated will be used to reference the data map when setting or getting Base SAS variables in a message.

rc

descs

Character, input
Specifies a data map descriptor that defines the data type, data offset from the beginning of the message, and data length. A descriptor has the following format:

   "TYPE<,OFFSET,LENGTH>"

Where TYPE can be one of the following values:

CHAR (character data)
SHORT (short integer)
LONG (long integer)
DOUBLE (double precision floating point)

OFFSET is the offset from beginning of the message. This property is optional so that by default data is not aligned (data starts at next available position in message).

LENGTH is the length of the data being represented. This property is optional in most cases. The only time length is required is when setting up to receive character data. Specifying length for numeric data is ignored since length is implicitly defined.

Note: Type coercion is performed transparently when you put Base SAS variables into a WebSphere MQ message (MQSETPARMS) and also when you get Base SAS variables from a WebSphere MQ message (MQGETPARMS). That is, if the data that you are sending or receiving is of a different type than the Base SAS variable itself, the data will be coerced into the appropriate data type.

Example

This example defines a map to use to send and receive a message with a short, a long, a double and a character string. No alignment is specified for any data type, and strings will always be 200 characters in length (blank padded).

   hMap=0;
   rc=0;
   desc1="SHORT";
   desc2="LONG";
   desc3="DOUBLE";
   desc4="CHAR,,200"
   CALL MQMAP(hMap, rc, desc1, desc2, desc3, desc4);

MQSETPARMS

Creates a data descriptor that describes the actual Base SAS variables along with an associated data mapping. This data descriptor can then be used on a subsequent MQPUT or MQPUT1 call.

Syntax

CALL MQSETPARMS(hData, hMap, rc, parm1 <,parm2, parm3, ...>);

hData: Numeric, output
Returns a Base SAS internal data descriptor handle. The handle generated can be used to reference the data when sending a message to a queue.
hMap: Numeric, input
Specifies a Base SAS internal map descriptor handle obtained from a previous MQMAP function call. If set to zero, no external defined mapping is assumed and therefore, all data will be mapped according to Base SAS internal representations. That is, all numerics will be mapped as doubles and all strings will be mapped as character data of the current string length.
rc: Numeric, output
Provides the Base SAS return code from this function. If an error occurred, the return code will be non-zero. The Base SAS function SYSMSG() can be used to obtain a textual description of the return code.
parms: Numeric/character, input
Specifies the Base SAS variables to set.

Example

This example sets values of Base SAS variables into a message.

   hData=0;
   rc=0;
   parm1=100;
   parm2=9999;
   parm3=9999.9999;
   parm4="This is a test."
   CALL MQSETPARMS(hData, hMap, rc, 
      parm1, parm2, parm3, parm4);

MQGETPARMS

Retrieves values of Base SAS variables from a previous WebSphere MQ message that was received by a MQGET call.

Syntax

CALL MQGETPARMS(hMap, rc, parm1 <,parm2, parm3, ...>);

hMap: Numeric, input
Specifies a handle to a Base SAS internal map descriptor obtained from a previous MQMAP function call.
rc: Numeric, output
Provides the Base SAS return code from this function. If an error occurred, the return code will be non-zero. The Base SAS function SYSMSG() can be used to obtain a textual description of the return code.
parms: Numeric/character, output
Returns the Base SAS variables.

Note: Initialize variables appropriately to guarantee that truncation does not occur.

Details

This message is available until the next MQGET call is performed.

Example

This example gets values of Base SAS variables from a received message.

   length parm1 parm2 parm3;
   length parm4 $ 200;

   rc=0;
   CALL MQGETPARMS(hMap, rc, parm1, parm2, parm3, parm4);

MQRMH

Creates or manipulates a reference message header so that an application can put a message in this format, omitting the bulk data.

Syntax

CALL MQRMH(hrmh, action, rc, parms, value1, value2, ...);

hrmh

Numeric, input/output
Specifies a Base SAS internal handle to a reference message header. The handle is generated as output when action is to generate default message header parameters. The handle should be supplied when you are setting or querying a parameter.

action

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

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

rc

parms

Character, input
Specifies an optional string of reference message header parameters that you want to set. Each parameter must be separated by a comma and must have a value associated with it in the function's parameter list. The OBJECTTYPE, SRCNAME, and DESTNAME parameters should be defined.

value

Numeric/character, input/output
Provides a value for a reference message header parameter specified in the parms string. You must provide a value parameter for each reference message header parameter 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 reference message header parameters (parms) and values are valid:

ENCODING: Numeric, input
Data encoding
CODEDCHARSETID: Numeric, input
Coded character set identifier
FORMAT: Character8, input
Format name
OBJECTTYPE: Character8, input
Object type
SRCNAME: Character, input
Source object name
DESTNAME: Character, input
Destination object name

Details

This is a new function that supports WebSphere MQ Version 5.1 and later.

When the reference message header is read from the transmission queue by a message channel agent (MCA), a user-supplied message exit is invoked to process the reference message. A sample message exit is supplied by WebSphere MQ, amqsxrm. You will need to add this message exit to the sending and receiving channel definitions. The message exit on the sending side can append to the reference message the bulk data identified by the reference message header before the MCA sends the message through the channel to the next queue manager. When a reference message is received, the receiving message exit should create the object from the bulk data that is associated with the reference message header, and then pass on the reference message without the bulk data so that the reference message (without the bulk data) can later be retrieved by a program.

Example

This example goes through the process of connecting to a queue manager, preparing the queue, generating the message, closing the queue, and freeing all resources.

   data _null_;
   length hconn hobj cc reason 8;
   length rc hod hpmo hmd hrmh 8;
   length msg $ 200;

   hconn=0;
   hobj=0;
   hod=0;
   hpmo=0;
   hmd=0;
   hrmh=0;

   put '---------------- Connect to QMgr --------------';
   call mqconn("TESTQMGR", hconn, cc, reason);
   if cc ^= 0 then do;
      if reason = 2002 then do;
         put 'Already connected to QMgr ' qmgr;
      end;
      else do;
         if reason = 2059 then
            put 'MQCONN: QMgr not available... 
               needs to be started';
         else
            put 'MQCONN: failed with reason= ' reason;
         goto exit;
      end;
   end;
   else put 'MQCONN: successfully connected to QMgr ' qmgr;


   put '---------- Generate object descriptor ---------';
   call mqod(hod, "GEN", rc, "OBJECTNAME", "TESTQ");
   if rc ^= 0 then do;
      put 'MQOD: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQOD: successfully generated 
      object descriptor';


   put '-------- Open queue object for output ---------';
   call mqopen(hconn, hod, "OUTPUT", hobj, cc, reason);
   if cc ^= 0 then do;
      put 'MQOPEN: failed with reason= ' reason;
     goto exit;
   end;
   else put 'MQOPEN: successfully opened queue for output';


   put '--------- Generate put message options --------';
   call mqpmo(hpmo, "GEN", rc);
   if rc ^= 0 then do;
      put 'MQPMO: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQPMO: successfully generated put 
      message options';


   put '--------- Generate message descriptor ---------';
   /* format must be set to reference message header */
   call mqmd(hmd, "GEN", rc, "PERSISTENCE,FORMAT", 
      "PERSISTENT", "MQHREF");
   if rc ^= 0 then do;
      put 'MQMD: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQMD: successfully generated 
      message descriptor';

   /** reference message header **/
   call mqrmh(hrmh, "GEN", rc, 
      "SRCNAME,DESTNAME,OBJECTTYPE",
      "d:\test.txt", "d:\testdup.txt", "FLATFILE");
   if rc ^= 0 then do;
      put 'MQRMH: failed with rc= ' rc;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQRMH: successfully generated reference 
      message header';

   put '------------- Put message on queue ------------';
   call mqput(hconn, hobj, hmd, hpmo, hrmh, cc, reason);
   if cc ^= 0 then do;
      put 'MQPUT: failed with reason= ' reason;
      msg = sysmsg();
      put msg;
      goto exit;
   end;
   else put 'MQPUT: successfully put message on queue';


   exit:
   if hobj ^= 0 then do;
      put '----------------- Close queue ---------------';
      call mqclose(hconn, hobj, "NONE", cc, reason);
      if cc ^= 0 then do;
         put 'MQCLOSE: failed with reason= ' reason;
      end;
      else put 'MQCLOSE: successfully closed queue';
   end;


   if hconn ^= 0 then do;
      put '------------ Disconnect from QMgr -----------';
      call mqdisc(hconn, cc, reason);
      if cc ^= 0 then do;
         put 'MQDISC: failed with reason= ' reason;
      end;
      else put 'MQDISC: successfully disconnected 
         from QMgr';
   end;


   if hod ^= 0 then do;
      call mqfree(hod);
      put 'Object descriptor handle freed';
   end;
   if hpmo ^= 0 then do;
      call mqfree(hpmo);
      put 'Put message options handle freed';
   end;
   if hmd ^= 0 then do;
      call mqfree(hmd);
      put 'Message descriptor handle freed';
   end;
   if hrmh ^= 0 then do;
      call mqfree(hrmh);
      put 'Reference message header handle freed';
   end;
   run;

MQFREE

Frees a Base SAS internal handle, thereby releasing its resources.

Syntax

CALL MQFREE(handle);

handle

Numeric, input
Specifies the Base SAS internal handle obtained from one of the following previous function calls:

MQPMO (hpmo)
MQGMO (hgmo)
MQOD (hod)
MQMD (hmd)
MQMAP (hMap)
MQSETPARMS (hData)

The following new function supports WebSphere MQ Version 5.1 and later:

MQRMH (hrmh)

Example

This example frees the resources allocated by a handle.

   CALL MQFREE(handle);