Common Messaging Interface Call Routines

SENDMESSAGE

Sends a message and optional attachments to a queue.

Transports supported:

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

Syntax
Arguments
Details
Example

Syntax

CALL SENDMESSAGE(qid, rc, props <, value1, value2,...<, data1, data2,...>>);

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.

props

Character, input

Identifies one or more message properties that affect the message being sent. This parameter is a character string with each applicable property separated by a comma. All values except MSGID are input to the SENDMESSAGE routine.

The following are valid send message properties for MQSeries:

ACCOUNTINGTOKEN
APPLIDENTITYDATA
APPLORIGINDATA
CODEDCHARSETID
ENCODING
FEEDBACK
FORMAT
PUTAPPLNAME
PUTAPPLTYPE
PUTDATE
PUTTIME
REPORT
USERID

The following are valid send message properties for MSMQ:

ACKNOWLEDGE
ADMINQUEUE
AUTHENTICATE
DESCRIPTION
ENCRYPT
ENCRYPTALG
HASHALG
JOURNAL
SENDERCERT

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

ALLOWREADPROTECT
ATTACHLIST
CORRELATIONID
MAP
MSGID
MSGTYPE
PERSIST
PRIORITY
RESPQUEUE
TIMEOUT
TRANSACTION

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

ATTACHLIST
ALLOWREADPROTECT
MAP
RESPQUEUE

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

ADDLISTENER
ALLOWLISTENER
DISALLOWLISTENER
RELAYAGENTACTION
TIMEOUT

values

Character or numeric, input or output

Provides values that are associated with the properties specified via the props parameter. You must associate a value with each property that is specified by props. All values except MSGID are input to the routine. For the MQSeries transport, MSGID is input and output. For the MSMQ transport, MSGID is only output. Descriptions and values for the send message properties are listed by transport, and the following values are valid:

ACCOUNTINGTOKEN

Binary string

MQSeries accounting token.

ACKNOWLEDGE

Character

MSMQ acknowledgment types. Possible acknowledge types are as follows:

NONE (Default): Specifies that no acknowledgment messages are posted.
FULL_REACH_QUEUE: Specifies that positive or negative acknowledgments are posted, depending on whether the message reaches the queue.
FULL_RECEIVE: Specifies that positive or negative acknowledgments are posted, depending on 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.

ADDLISTENER

Character

Identifies one or more certified message names (CMNAMEs) of the listeners. This parameter is a character string with each CMNAME separated by a comma.

Anticipates a listener (or listeners) for certified delivery agreement.

Note: If a listener is added, this feature applies to all future messages within the session. [cautionend]

ADMINQUEUE

Character

Specifies the MSMQ administrator queue.

ALLOWLISTENER

Character

Identifies one or more certified message names (CMNAMEs) of the listeners. This parameter is a character string with each CMNAME separated by a comma.

Allows listeners on the specified CMNAME to reinstate certified delivery. This feature overrides any DISALLOWLISTENER for listener CMNAME.

Note: If a listener is allowed, this feature applies to all future messages within the session. [cautionend]

ALLOWREADPROTECT

Character

Specifies the value "YES". You must assert this property on read-protected data sets in order for that data set to be sent as an attachment. This ensures that the user realizes that the read password and encryption attributes are not preserved when this data set is sent as a message attachment. If this property is not applied, then the SENDMESSAGE call fails when the user tries to send a read protected data set, and an error is returned.

Note: This property is supported in SAS 8.1 and later. The password and encryption attributes are not preserved in the intermediate message format when the attachment is on a message queue. Because of this exposure, take care when sending password-protected or encrypted data sets as message attachments. [cautionend]

APPLIDENTITYDATA

Character

Specifies the MQSeries application identity data.

APPLORIGINDATA

Character

Specifies the MQSeries application origin data.

ATTACHLIST

Character

Specifies that a list of attachments is included with message. The format of the list is as follows:

"type,qual1,qual2,options;
type,qual1,qual2,options;..."

where the parameters are defined as follows:

type

Is the attachment type, which can be one of the following:

EXTERNAL_TEXT: Is an external text file.
EXTERNAL_BIN: Is an external binary file.
DATASET: Is a SAS data set.

qual1

Is a qualifier. For EXTERNAL_TEXT and EXTERNAL_BIN attachment types, this qualifier specifies the file specification type which can be one of the following:

FILENAME
FILEREF

For the DATASET attachment type, this qualifier specifies the library name.

qual2

Is a qualifier. For EXTERNAL_TEXT and EXTERNAL_BIN attachment types, this qualifier specifies the actual filename or fileref. For the DATASET attachment type, this qualifier specifies the member name.

options

Specifies optional attachment specifications. Multiple options must be separated by spaces. The following options are valid for all attachment types:

DESC=attachment description
MINOR=user specified minor version
MAJOR=user specified major version

The following options are valid for the DATASET attachment type:

DATASET_OPTIONS=data set options
WHERE=WHERE clause
INDEX=yes|no (default is yes so that indexes are sent)
IC=yes|no (default is yes so that integrity constraints are sent)
ATTACH_VERSION=VERSION_8

If the ATTACH_VERSION option is specified and value=VERSION_8, then the data set is sent using the column types available in the data sets before SAS®9. Use this option if you might be sending data sets to another SAS session that is running SAS 8.2 or earlier.

If the ATTACH_VERSION option is omitted or if any other value is specified, then the full data set, including all new types, is sent.

AUTHENTICATE

Character

Specifies MSMQ authentication enablement. Possible authenticate types are as follows:

NO (default): Specifies that no authentication is necessary. The message is not signed.
YES: Specifies that the message is signed and authenticated by the destination queue manager.

CODEDCHARSETID

Numeric

Specifies the MQSeries coded character set.

CORRELATIONID

Binary string

Specifies the correlation identifier.

DESCRIPTION

Character

Specifies the Message description.

DISALLOWLISTENER

Character

Specifies one or more certified message names (CMNAMEs) of the listeners. This parameter is a character string with each CMNAME separated by a comma.

It cancels certified delivery to listeners with the specified CMNAME.

Note: If a listener is disallowed, this feature applies to all future messages within the session. [cautionend]

ENCODING

Numeric

Specifies MQSeries data encoding.

ENCRYPT

Character

Specifies MSMQ encryption enablement. Possible encryption types are as follows:

NO (Default): Specifies that the message is to be sent as clear-text.
YES: Specifies end-to-end encryption of the message body.

ENCRYPTALG

Character

Specifies the MSMQ encryption algorithms. The following choices are valid:

RC2 (default)
RC4

FEEDBACK

Numeric

Specifies MQSeries feedback code.

FORMAT

Character

Specifies MQSeries format name.

HASHALG

Character

Specifies MSMQ hash algorithms. Possible hash types are as follows:

MD2
MD4
MD5 (default)

JOURNAL

Character

Specifies MSMQ journaling. Possible journal types are as follows:

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

MAP

Character

Specifies the data map name.

MSGID

Binary string

Specifies the message identifier.

MSGTYPE

Numeric

Specifies the message type.

PERSIST

Character

Specifies message persistence. Possible persist types are as follows:

NO: Indicates that the message is not persistent (default).
YES: Indicates that the message is persistent.

PRIORITY

Numeric

Specifies message priority.

PUTAPPLNAME

Character

Specifies MQSeries application name.

PUTAPPLTYPE

Numeric

Specifies MQSeries application type.

PUTDATE

Character

Specifies MQSeries put date.

PUTTIME

Character

Specifies MQSeries put time.

RELAYAGENTACTION

Character

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

CONNECT: Indicates to connect to the relay agent before sending messages and attachments.
DISCONNECT: Indicates to disconnect from the relay agent after all messages associated with the call have been processed. The disconnect happens at the end of the call before the call returns to the DATA step.
BOTH: Indicates to connect to the relay agent, send all messages, and then disconnect from the relay agent. The disconnect happens at the end of the call before the call returns to the DATA step.

REPORT

Character

Specifies the MQSeries reporting types. Possible report types are as follows:

NONE: Specifies that no reports are required.
PASS_CORREL_ID: Specifies to pass a correlation identifier.
PASS_MSG_ID: Specifies to pass a message identifier.
COA: Specifies that confirmation-on-arrival reports are required.
COA_WITH_DATA: Specifies that confirmation-on-arrival reports with data are required.
COA_WITH_FULL_DATA: Specifies that confirmation-on-arrival reports with full data are required.
COD: Specifies that confirmation-on-delivery reports are required.
COD_WITH_DATA: Specifies that confirmation-on-delivery reports with data are required.
COD_WITH_FULL_DATA: Specifies that confirmation-on-delivery reports with full data are required.
EXPIRATION: Specifies that expiration reports are required.
EXPIRATION_WITH_DATA: Specifies that expiration reports with data are required.
EXPIRATION_WITH_FULL_DATA: Specifies that expiration reports with full data are required.
EXCEPTION: Specifies that exception reports are required.
EXCEPTION_WITH_DATA: Specifies that exception reports with data are required.
EXCEPTION_WITH_FULL_DATA: Specifies that exception reports with full data required.
DISCARD_MSG: Specifies to discard message if it is undeliverable.

RESPQUEUE

Character

Specifies the response queue name.

Note: If this attribute is specified with an empty string value ('') when using a Rendezvous or Rendezvous-CM queue that was opened using REQUESTX mode, the generated inbox name will be sent. If another name is specified, it will be used instead. [cautionend]

SENDERCERT

Character

Specifies the MSMQ certificate store name that is used in order to search for external certificates. "MY" is typically specified. This results in a search of the current user's certificates with their associated private keys. For example, if "MY" is used, the corresponding registry entry is

HKEY_CURRENT_USER\Software\Microsoft\SystemCertificates\MY

TIMEOUT

Numeric

Specifies the timeout value in seconds.

For Rendezvous-CM, specify this timeout as the length of time this message is to be sent using certified message delivery.

TRANSACTION

Numeric

Specifies the transaction object that is obtained from BEGINTRANSACTION.

USERID

Character

Specifies the MQSeries user identifier.

data

Character or numeric, input

Specifies the individual pieces of data that are sent with the message.

Details

If you intend to send attachments, use a queue that supports transactional processing. In this way, all messages associated with a failed attachment can be backed out if any part of the attachment processing fails. The IBM MQSeries queue manager supports the synchpoint function. An MSMQ queue is a transactional queue. For information about exception processing when using attachments, see Attachment Error Handling.

Before any messages are sent with the TIB/Rendezvous transport, the queues that receive the messages must be running and must have a listener (that is, the queues must be opened for FETCH, FETCHX, REQUEST, or REQUESTX). Otherwise, data will be lost. Queues that are opened for REQUEST and REQUESTX automatically have their receiving (response) queues open to listen for incoming messages.

Note: If you are sending certified messages by using Rendezvous-CM, and plan to close the sending queue immediately after sending the message, then you might want to put a sleep() call in to sleep for a couple of seconds. This delay allows the Certified Delivery Agreement to be established between the sending transport and the receiving transport. This delay can also occur when a listener is first opened to receive certified messages. [cautionend]

Example

The following example sends an employee name and ID with records attached:

length msg $ 200;
length qid rc 8;
length msgtype 8 corrid $ 48 alist $ 80;
length employee $ 20 id 8;

rc=0;

/* message properties */
msgtype=1;
corrid='0102030405060708090A0B0C0D0E0F';
alist='DATASET,EMPLOYEE,RECORDS,
   DESC=employee records for John Doe';

/*  message data */
employee='John Doe           ';
id=9999;

call sendmessage(qid, rc,
   'MSGTYPE,CORRELATIONID,ATTACHLIST',
  msgtype, corrid, alist, employee, id);
if rc ^= 0 then do;
   put 'SENDMESSAGE: failed';
   msg = sysmsg();
   put msg;
end;
else put 'SENDMESSAGE: succeeded';

Top of Page