MSMQRECEIVEMSG

Reads a message from the queue.

Syntax

Details

Example

Syntax

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

Required 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 time-out 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.)

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.

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