MSMQ Call Routines

MSMQSENDMSG

Sends a message to the specified queue.

Syntax
Arguments
Example

Syntax

CALL MSMQSENDMSG(hQueue, hData, 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.

hData

Numeric, input

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

transObj

Numeric, input

Specifies the transaction object 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 sent. 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.

Note: All values are inputs to the MSMQSENDMSG routine except MSGID which returns a message identifier. [cautionend]

The following send message properties and values are valid:

ACKNOWLEDGE

Specifies the type of acknowledgment messages that MSMQ posts when the message is sent. A positive acknowledgment indicates the message sent was received successfully. A negative acknowledgment indicates the message was not received.

Possible acknowledge types are as follows:

NONE (default): 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, indicating whether the message is retrieved from the queue.
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

Specifies the pathname of the queue that is used for MSMQ-generated acknowledgment messages. The value is a character string that represents the pathname of the administration queue.

APPSPECIFIC

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

AUTH_LEVEL

Specifies whether the message needs to be authenticated.

The following AUTH_LEVEL types are valid:

NONE (default): Specifies that no authentication is necessary. (Messages are not signed.)
ALWAYS: Specifies that messages are always signed and authenticated by the destination queue manager.

BODY_TYPE

Specifies the type of body the message contains. The value is numeric and is defined by the application and must be coordinated between the sending and receiving portions of the application. The default value is 0.

CORRELATIONID

Specifies the correlation identifier of the message. The value is a character string that represents binary data.

DELIVERY

Specifies how the message is delivered. The following values are valid:

EXPRESS (default): Specifies faster, non-guaranteed delivery.
RECOVERABLE: Specifies guaranteed delivery.

ENCRYPTION_ALG

Specifies the encryption algorithm that is used to encrypt the message body of a private message. Possible values are as follows:

RC2 (Block cipher) (Default)
RC4 (Stream cipher)

HASH_ALG

Specifies the hashing algorithm that is used when authenticating messages. The following values are valid:

MD2: Message Digest 2 Algorithm
MD4: Message Digest 4 Algorithm
MD5 (default): Message Digest 5 Algorithm

JOURNAL

Specifies whether the message should be kept in a machine journal, sent to a dead letter queue, or neither. 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

Specifies a label for the message. The default is a blank label ().

MSGID

Specifies 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

Specifies 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

Specifies the privacy level of the message. The following values are valid:

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

RESP_QUEUE

Specifies 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.

SECURITY_CONTEXT

Specifies security information that MSMQ uses to authenticate messages. The value is the handle to the security context buffer that is returned from MSMQGETCONTEXT.

SENDER_CERT

Specifies the name of the system certificate store to use in order to locate external certificates during the authentication process. Generally, MY is used. For example, if a value of MY is used, the registry location used to retrieve the system certificate is as follows:

HKEY_CURRENTUSER\Software\Microsoft\SystemCertificates\MY\Certificates

TIME_TO_BE_RECEIVED

Specifies the total time (in seconds) that the message is to be available. The default value is infinite.

TIME_TO_REACH_QUEUE

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

TRACE

Specifies where report messages are sent when tracing a message. The following values are valid:

NONE (default): 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.

Note: The BODY message property is set internally, based on whether data is present. [cautionend]

Example

This example sends a message.

length msg $ 200;
rc=0;
transobj=0;
CALL MSMQSENDMSG(hQueue,
hData,
transobj,
rc,
"AUTH_LEVEL,APPSPECIFIC,CORRELATIONID,LABEL,PRIV_LEVEL,RESP_QUEUE",
"ALWAYS", 999, "0102030405060708090A0B0C0D0E0F1011121314",
"Secret test message", "PRIVATE", "mypc\respq");
if rc ^= 0 then do;
   put 'MSMQSendMsg: failed';
   msg = sysmsg();
   put msg;
end;
else put 'MSMQSendMsg: succeeded';

Top of Page