RECEIVEMESSAGE

Receives a message and optional attachments from a queue.

Supports:

MQSeries, MQSeries C, MSMQ, Rendezvous, Rendezvous-CM

Syntax

Example

Syntax

CALL RECEIVEMESSAGE(qid, rc, event, attchflg, props , value1, value2,... data1, data2,...>>);

Required Arguments

qid: Numeric, input

Specifies the handle of an open queue that is obtained from a previous OPENQUEUE function call.

rc: Numeric, output

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

event

Character, output

Contains a description of the event that occurs as a result of the message being received. Possible event types are:

DELIVERY: Specifies that the message was delivered.

NO_MESSAGE: Specifies that no message is on queue.

ERROR: Specifies that an error has occurred. This event results in a nonzero value for rc .

You need to initialize this parameter to a length of at least 10 before making the call so that there is room for the value to be placed in the string. Otherwise, the message might be truncated.

attchflg

Numeric, output

Indicates whether an attachment is associated with the received message. Possible return values are as follows:

0: Specifies that no attachments are associated with this message.

1: Specifies that attachments are associated with this message. You can call GETATTACHMENT to receive the attachments.

props

Character, input

Identifies one or more message properties that are associated with the message that is received. This parameter is a character string. Each property is separated by a comma. The following receive message properties are valid for MQSeries:

ACCOUNTINGTOKEN
APPLIDENTITYDATA
APPLORIGINDATA
PUTAPPLNAME
PUTAPPLTYPE

The following receive message properties are valid for MSMQ:

ADMINQUEUE
AUTHENTICATE
DESCRIPTION
SENDERCERT

The following receive message properties are valid for both MQSeries and MSMQ:

CORRELATIONID
FEEDBACK
MAP
MSGID
MSGTYPE
OPTIONS
QUEUEDTIME
RESPQUEUE
TIMEOUT
TRANSACTION
USERID

The following receive message properties are valid for Rendezvous and Rendezvous-CM:

MAP
RESPQUEUE
TIMEOUT

The following receive message properties are valid for Rendezvous-CM only:

CERTIFIED
RELAYAGENTACTION
SENDERNAME

values

Character or numeric

Provides the values that are associated with each property that is specified via the props parameter. You must associate a value with each property that is identified with the props parameter. The property values can be an input, output, or both.

Descriptions and values for the received message properties are:

ACCOUNTINGTOKEN: Binary string, output

Specifies an MQSeries accounting token.

ADMINQUEUE: Character, output

Specifies an MSMQ administrator queue.

APPLIDENTITYDATA: Character, output

Specifies MQSeries application identity data.

APPLORIGINDATA: Character, output

Specifies MQSeries application origin data.

AUTHENTICATE

Character, output

Indicates MSMQ authentication enablement. Possible authenticate return values are as follows:

NO: Specifies that the message was not authenticated.

YES: Specifies that the message was authenticated.

CORRELATIONID: Binary string, input or output

Specifies a correlation identifier. For MQSeries and MSMQ transports, on input this property can be used for filtering purposes. However, do not try to filter with this property when you are receiving attachment messages. The original CORRELATIONID is not associated with the attachment header message, although the original CORRELATIONID is embedded within the attachment header itself and will be presented accurately. This type of processing is needed because an attachment consists of multiple messages that must be uniquely identified. A CORRELATIONID that is set by the application is not guaranteed to be unique.

CERTIFIED

Character, output

Specifies a Certified Message (CM) indicator. Possible return values are as follows:

NO: Specifies that the message was received by the normal transport or the listener has not been certified.

YES: Specifies that the message was received within the certified delivery transport.

DESCRIPTION: Character, output

Specifies a message description.

FEEDBACK: Numeric, output

For MQSeries, specifies a feedback code. For MSMQ, specifies a class.

MAP: Character, input

Specifies a data map name.

MSGID: Binary string, input or output

Indicates the message identifier. On input, this property can be used for filtering purposes for both MQSeries and MSMQ transports.

MSGTYPE: Numeric, output

Indicates the message type.

OPTIONS

Character, input

Specifies the receive options. The following options are valid:

POSITIONFIRST: (MQSeries/MSMQ)

Indicates to reposition to the first message in the queue.

CONVERSION_EXIT: (MQSeries only)

Specifies to use the MQSeries conversion exit. Otherwise, SAS performs all necessary data conversion internally.

PUTAPPLNAME: Character, output

Indicates an MQSeries application name.

PUTAPPLTYPE: Character, output

Indicates an MQSeries application type.

QUEUEDTIME: Character, output

Indicates the time at which the message was queued.

RELAYAGENTACTION

Character, input

Specifies connect or disconnect actions for the relay agent. The following values are valid:

CONNECT: Indicates to connect to the relay agent before receiving messages and attachments.

DISCONNECT: Indicates to disconnect from the relay agent after all messages associated with the call have been processed. If an attachment is received, the disconnect call is issued after the ACCEPTATTACHMENT call has processed all of the messages associated with the attachment and before the call returns to the DATA step. If ACCEPTATTACHMENT is not called, then the connection is not closed. If a connection was made to the relay agent during the call and an error occurs, then the error causes a disconnect from the relay agent.

BOTH: Indicates to connect to the relay agent, receive all messages, and then disconnect from the relay agent. If an attachment is received, the disconnect call is issued after the ACCEPTATTACHMENT call has processed all of the messages associated with the attachment and before the call returns to the DATA step. If ACCEPTATTACHMENT is not called, then the connection is not closed. If an error occurs in a call, then if a connection was made to the relay agent during the call, an error causes a disconnect from the relay agent.

RESPQUEUE: Character, output

Indicates the response queue name.

SENDERCERT: Character, output

Indicates the subject within received certificate (MSMQ).

SENDERNAME: Character, output

Indicates the name of the certified message (CM) transport used by the sender.

TIMEOUT: Numeric, input

Specifies the number of seconds the RECEIVEMESSAGE call should wait for a message to arrive before returning. A value of -1 resets the queue to a non-polling state, and the RECEIVEMESSAGE call will wait indefinitely for a message to arrive. If the POLL attribute was not specified on an OPENQUEUE call, using this option on a RECEIVEMESSAGE call turns the queue into a polling queue that does not wait indefinitely for a message to arrive. You can turn a polling queue into a non-polling queue that waits indefinitely by specifying '-1' as the value of the TIMEOUT property on a RECEIVEMESSAGE call. By setting a TIMEOUT value on a RECEIVEMESSAGE call, the TIMEOUT value for the current queue ID is set to the new value, and all subsequent RECEIVEMESSAGE calls will wait for the new time-out specified.

TRANSACTION: Numeric, input

Indicates the transaction object obtained from BEGINTRANSACTION.

USERID: Character, output

Indicates the user identifier who sent the message.

data: Character or numeric, output

When you issue RECEIVEMESSAGE, all data that is associated with a message is placed into an internal buffer. You can parse this data during the RECEIVEMESSAGE call with these optional parameters, or you can call PARSEMESSAGE at a later time to parse the data.

Example

The following example receives a message such as the one sent in the SENDMESSAGE example:

length msg $ 200;
length qid rc attchflg 8 event $ 10;
length msgtype 8 corrid $ 48 map $ 80;
length employee $ 20 id 8;
rc=0;
corrid='';
/* no filtering */
map='employeerecord';
/* data descriptor defined in repository...
   for example, "char,,20;double" */
call receivemessage(qid, rc, event, attchflg,
   'MSGTYPE,CORRELATIONID,MAP', msgtype, corrid,
   map, employee, id);
if rc ^= 0 then do;
   put 'RECEIVEMESSAGE: failed';
   msg = sysmsg();
   put msg;
end;
else do;
   put 'RECEIVEMESSAGE: succeeded';
   put 'Event = ' event;
   if event eq 'DELIVERY' then do;
      put 'Message has been delivered';
      if attchflg eq 1 then do;
      put 'Attachment(s) are associated
	    with this message';
         /* process attachments...*/
      end;
      put 'employee = ' employee;
      put 'id = ' id;
   end;
end;