MSMQ Call Routines

MSMQRECEIVEMSG

Reads a message from the queue.

Syntax
Arguments
Details
Example

Syntax

CALL MSMQRECEIVEMSG(hQueue, timeout, action, hCursor, transObj, rc <, propids, value1, value2, ...>);

Arguments

hQueue

Numeric, input

Specifies the MSMQ handle to an open queue. This parameter is obtained from a previous MSMQOPENQUEUE function call.

timeout

Numeric, input

Specifies the amount of time (in milliseconds) to wait for a message to be received from the queue. If you want to wait indefinitely for the message to be received, then set the timeout parameter to -1.

action

Character, input

Determines how and where the message is read from the queue. This parameter is also used to determine whether the message is removed after reading. Possible valid values:

RECEIVE: Reads the message at the current cursor location and removes it from the queue.
PEEK_CURRENT: Reads a message at the current cursor location but does not remove it from the queue. The cursor remains at the current message. If the hCursor parameter is 0, then the queue's cursor can point only to the first message in the queue.
PEEK_NEXT: Reads the next message in the queue (skipping the message at the current cursor location) but does not remove it from the queue. A cursor must already be created (by calling MSMQCREATECURSOR) before calling this routine. (hCursor = 0 is not allowed.)

hCursor

Numeric, input

Specifies the handle to a cursor that is used for looking at messages in the queue. The MSMQCREATECURSOR routine is used to create a cursor and obtain its handle.

transObj

Numeric, input

Specifies the transaction object that is obtained from a previous MSMQBEGINTRANS function call. If this value is set to zero, then it is assumed that this operation will not be part of a transaction.

rc

Numeric, output

Provides the return code from the CALL routine. If an error occurs, then the return code is nonzero. A return code of -1 reflects a SAS internal error. Otherwise, it represents an MSMQ error code. You can use the SAS function SYSMSG() to obtain a textual description of the return code.

propids

Character, input

Identifies one or more message properties that affects the message being received from the queue. This parameter is a character string with each applicable property separated by a comma. You must provide a value parameter for each property specified in the propids string. Each property ID in the propids string is associated positionally with a value parameter. The CALL routine returns the corresponding property value into each value parameter.

The following receive message properties and values are valid:

ACKNOWLEDGE

Retrieves the type of acknowledgment messages that MSMQ posts when the message was sent. Initialize the variable appropriately to prevent truncation of the retrieved value from occurring. Possible acknowledge types are as follows:

NONE: Specifies no acknowledgment messages are posted.
FULL_REACH_QUEUE: Specifies that positive and negative acknowledgments are posted, indicating whether the message reaches the queue.
FULL_RECEIVE: Specifies that positive and negative acknowledgments are posted, depending on whether the message is retrieved from the queue before its time-to-be-received timer expires.
NACK_REACH_QUEUE: Specifies that negative acknowledgments are posted when a message cannot reach the queue.
NACK_RECEIVE: Specifies that negative acknowledgments are posted when a message cannot be retrieved from the queue.

ADMIN_QUEUE

Retrieves the queue used for MSMQ-generated acknowledgment messages. This value is a character string that represents the pathname of the administration queue. You can use the MSMQPATHTOFORMAT CALL routine to obtain a queue identifier for this queue. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

APPSPECIFIC

Retrieves the application-generated information. The value is numeric, and the default is 0.

ARRIVEDTIME

Retrieves the time the message arrived at the queue. The value is a numeric that represents the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

AUTHENTICATED

Retrieves whether the message was authenticated. The following values are valid:

0 : Message is not authenticated.
1 : Message is authenticated.

BODY

Specifies whether the message body should be received. The following values are valid:

0 : Specifies not to retrieve the body of the message.
1 (default) : Specifies to retrieve the body of the message

BODY_SIZE

Retrieves the actual size of the message body. The body size is a numeric value.

BODY_TYPE

Retrieves the type of body the message contains. The value is numeric.

CLASS

Retrieves the class of the message. The value is a numeric.

CORRELATIONID

Retrieves the correlation identifier of the message. The value is a character string that represents binary data. Initialize the variable to a size of at least 40 to guarantee that truncation of the returned value does not occur.

DELIVERY

Retrieves how the message is delivered. Initialize the variable appropriately to prevent truncation of the returned value from occurring. The following values are valid:

EXPRESS: Specifies faster, non-guaranteed delivery.
RECOVERABLE: Specifies guaranteed delivery.

DEST_QUEUE

Retrieves the target queue of the message. This value is a character string that represents the pathname of the destination queue. You can use the MSMQPATHTOFORMAT CALL routine to obtain a queue identifier for this queue. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

JOURNAL

Retrieves journal enablement. Initialize the variable appropriately to prevent truncation of the returned value from occurring. The following values are valid:

NONE (default): Specifies the message is not kept in the originating machine's journal queue.
JOURNAL: Specifies the message is kept in the originating machine's journal queue.
DEADLETTER: Specifies the message is kept in a dead letter queue if it cannot be delivered.

Note: A combination can be specified by separating each value with a comma (for example, JOURNAL,DEADLETTER.) [cautionend]

LABEL

Retrieves a label for the message. The label value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

MSGID

Retrieves MSMQ-generated identifier of the message. The value is a character string that represents binary data. Initialize the variable to a size of at least 40 to guarantee that truncation of the returned value does not occur.

Note: This value is returned as a binary string. MSMQ Explorer displays the message identifier as a UUID concatenated with a sequence number. [cautionend]

PRIORITY

Retrieves the message's priority. The value is a numeric between 0 and 7. The highest priority is 7, and the default priority is 3.

PRIV_LEVEL

Retrieves the privacy level of the message. Initialize the variable appropriately to prevent truncation of the returned value from occurring. The following values are valid:

PUBLIC: Specifies the message is to be sent as clear-text.
PRIVATE: Specifies end-to-end encryption of the message body.

RESP_QUEUE

Retrieves the pathname of the queue where application-generated response messages are returned. The value is a character string that represents the pathname of the response queue. You can use the MSMQPATHTOFORMAT CALL routine to obtain a queue identifier for this queue. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

SENDER_CERT

Retrieves the certificate that was used to authenticate the message. This value is a character string. If an external certificate was used to authenticate the message, the information that is returned can be used to verify who sent the message (subject).

SENDERID

Retrieves who sent the message. The value is a character string.

SENTTIME

Retrieves the time the message was sent. The value is a numeric that represents the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

SRC_MACHINE_ID

Retrieves the UUID of the computer where the message was sent. This value is a UUID in the form of a character string that represents the binary data. Initialize the variable to a size of at least 32 to guarantee that truncation of the returned value does not occur.

TIME_TO_BE_RECEIVED

Retrieves the total time (in seconds) that the message is to be available. The value is a numeric with a default of infinity.

TIME_TO_REACH_QUEUE

Retrieves time limit (in seconds) for the message to reach the queue.

TRACE

Retrieves where report messages are sent when tracing a message. Initialize the variable appropriately to guarantee that truncation of the returned value does not occur. The following values are valid:

NONE: Specifies no tracing for this message.
REPORT: Specifies report messages are to be sent to the report queue that is specified by the source queue manager.

VERSION

Retrieves the version of MSMQ that is used to send the message. The value is a numeric.

Details

When reading messages, you can either peek at or retrieve them from the queue. The message is retrieved into an internal SAS buffer at which time you should call MSMQGETPARMS to set SAS variables (parameters) to that data.

Example

This example receives a message.

   length msg $ 200;
   length arrivet auth size respq sentt 8;
   length correlid msgid $ 40;
   length label $ 80;
   rc=0;
   hCursor=0;
   transobj=0;
   CALL MSMQRECEIVEMSG(hQueue, 0, "RECEIVE", hCursor, transobj, rc,
                    "ARRIVEDTIME,AUTHENTICATED,BODY_SIZE,CORRELATIONID,
                     LABEL,MSGID,RESP_QUEUE,SENTTIME",
                    arrivet, auth, size, correlid, label, msgid, respq, sentt);
   if rc ^= 0 then do;
    put 'MSMQReceiveMsg: failed';
    msg = sysmsg();
    put msg;
   end;
   else do;
    put 'MSMQReceiveMsg: succeeded';
    /* convert MSMQ arrived time to SAS datetime format */
    arrivet = arrivet + 10*365*24*3600 + 3*24*3600 - 5*3600;
    put 'arrived time is' arrivet datetime.;
    if auth = 1 then put 'message was authenticated';
    else put 'message was not authenticated';
    put 'message body size is ' size;
    put 'correlation id is ' correlid;
    put 'label is ' label;
    put 'msg id is ' msgid;
    put 'resp_queue qid handle is ' respq;
    /* convert MSMQ sent time to SAS datetime format */
    sentt = sentt + 10*365*24*3600 + 3*24*3600 - 5*3600;
    put 'sent time was' sentt datetime.;
   end;

Top of Page