MSMQSENDMSG

Sends a message to the specified queue.

Syntax

Example

Syntax

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

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.

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

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.

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.

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