SAS 9.1.3 Integration Technologies » Developer's Guide

MSMQ Functional Interface

Writing MSMQ Applications

MSMQ Code Samples

MSMQ CALL Routines

	MSMQCREATEQUEUE
	MSMQDELETEQUEUE
	MSMQOPENQUEUE
	MSMQCLOSEQUEUE
	MSMQPATHTOFORMAT
	MSMQINSTTOFORMAT
	MSMQHNDLTOFORMAT
	MSMQSENDMSG
	MSMQRECEIVEMSG
	MSMQCREATECURSOR
	MSMQCLOSECURSOR
	MSMQBEGINTRANS
	MSMQCOMMITTRANS
	MSMQABORTTRANS
	MSMQRELEASETRANS
	MSMQLOCATE
	MSMQGETQPROP
	MSMQSETQPROP
	MSMQGETQSEC
	MSMQSETQSEC
	MSMQGETSCONTEXT
	MSMQFREESCONTEXT
	MSMQMAP
	MSMQSETPARMS
	MSMQGETPARMS
	MSMQFREE

Prev | Next | Contents

Application Messaging

MSMQ CALL Routines

MSMQCREATEQUEUE

Creates a queue at a specified MSMQ pathname.

Syntax

CALL MSMQCREATEQUEUE(qid, rc, propids, value1 <,value2, ...>);

qid

Numeric, output
Returns the queue identifier that represents the format name of the queue that is created. The format name of the queue is a unique name generated by MSMQ.

rc

Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

propids

Character, input
Specifies one or more properties that the queue will exhibit once created. This parameter is a character string with each applicable property separated by a comma. PATHNAME is the only required property.

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 following creation properties are valid:

AUTHENTICATE

Specifies whether or not the queue only accepts authenticated messages. The following values are valid:

"NONE" (default): Specifies the queue will except either authenticated or non-authenticated messages.
"ALWAYS": Specifies the queue always requires authenticated messages.

BASEPRIORITY

Specifies a single base priority for all messages sent to a public queue. Values range from -32768 to 32767, where 32767 is the highest priority and 0 is the default priority.

JOURNAL

Determines whether messages retrieved from the queue are also copied to its journal queue. The following values are valid:

"NONE" (default): Specifies that messages removed from the queue are discarded.
"ALWAYS": Specifies that messages removed from the queue are always stored in its journal queue.

JOURNAL_QUOTA

Specifies the maximum size (in kilobytes) of the journal queue. The default size is infinite.

LABEL

Describes the queue. The default is a blank label ("").

PATHNAME

Specifies the MSMQ pathname of the queue. The format of a public queue is:

MachineName\QueueName

The format of a private queue is

MachineName\PRIVATE$\QueueName

PRIV_LEVEL

Specifies the privacy level that is required by the queue. The following values are valid:

"NONE": Specifies that the queue accepts only non-private (clear) messages.
"BODY": Specifies that the queue accepts only private (encrypted) messages.
"OPTIONAL" (default): Specifies that the queue accepts both private and non-private messages.

QUOTA

Specifies the maximum size (in kilobytes) of the queue. The default size is infinite.

TRANSACTION

Specifies whether the queue is a transaction queue or a non-transaction queue. The following values are valid:

"NONE" (default): Specifies that the queue does not accept transaction operations.
"ALWAYS": Specifies that all messages sent to the queue must always be done through an MSMQ transaction.

TYPE

Specifies the type of service provided by the queue. The value of the TYPE property is a globally unique identifier (GUID) in the form of a character string that represents the binary data.

Note: Security of the queue defaults as follows:

Owner: process user
Group: process group
DACL: queue creator - has full control
Queue users
- get queue properties
- get queue security
- send messages

These defaults can either be changed programmatically using the MSMQSETQSEC routine or via the MSMQ Explorer interface.

Details

The routine also registers the queue in the MSMQ Information Store (MQIS) for public queues or registers it on the local computer for private queues.

Example

This example creates a public queue.


   length msg $ 200;

   qid=0;
   rc=0;
   CALL MSMQCREATEQUEUE(qid, rc, "PATHNAME,LABEL", "pcpad\testq", "Test Queue");
   if rc ^= 0 then do;
    put 'MSMQCreateQueue: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQCreateQueue: succeeded';

MSMQDELETEQUEUE

Deletes a queue from the MQIS in the case of public queues, or from the local computer in the case of private queues.

Syntax

CALL MSMQDELETEQUEUE(qid, rc);

qid: Numeric, input
Specifies the queue identifier that represents the format name of the queue to be deleted.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example deletes a queue.


   length msg $ 200;

   rc=0;
   CALL MSMQDELETEQUEUE(qid, rc);
   if rc ^= 0 then do;
    put 'MSMQDeleteQueue: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQDeleteQueue: succeeded';

MSMQOPENQUEUE

Opens a queue for sending message to the queue or for reading its messages.

Syntax

CALL MSMQOPENQUEUE(qid, access, shareMode, hQueue, rc);

qid

Numeric, input
Specifies the queue identifier that represents the format name of the queue to be opened.

access

Character, input
Indicates the level of access users have to the messages in the queue being opened. The following values are valid:

"PEEK": Specifies that messages can only be looked at.
"SEND": Specifies that messages can only be sent to the queue.
"RECEIVE": Specifies that messages can be looked at and removed from the queue.

shareMode

Character, input
Specifies how the queue will be shared. The following values are valid:

"SHARE": Specifies that the queue is available to everyone.
"DENY_SHARE": Specifies that the process making this function call is the only one that can receive messages from this queue. If the queue is already opened for receiving messages by another process, this call will fail.

hQueue

Numeric, output
Returns the MSMQ handle of the opened queue. This handle is used by subsequent CALL routines to identify and access the queue.

rc

Example

This example opens a queue for sending messages.


   length msg $ 200;

   hQueue=0;
   rc=0;
   CALL MSMQOPENQUEUE(qid, "SEND", "SHARE", hQueue, rc);
   if rc ^= 0 then do;
    put 'MSMQOpenQueue: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQOpenQueue: succeeded';

MSMQCLOSEQUEUE

Closes a given queue.

Syntax

CALL MSMQCLOSEQUEUE(hQueue, rc);

hQueue: Numeric, input
Specifies the MSMQ handle to an open queue. This parameter was obtained from a previous MSMQOPENQUEUE function call.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example closes a queue.


   length msg $ 200;

   rc=0;
   CALL MSMQCLOSEQUEUE(hQueue, rc);
   if rc ^= 0 then do;
    put 'MSMQCloseQueue: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQCloseQueue: succeeded';

MSMQPATHTOFORMAT

Returns a qid (queue identifier) handle that represents the format name of the desired queue.

Syntax

CALL MSMQPATHTOFORMAT(pathName, qid, rc);

pathName

Character, input
Represents the queue's pathname or actual format name of the queue, if known.

If a MSMQ pathname is used to represent the queue, it will be converted to a MSMQ format name. Possible pathName representations are as follows:

Public queue: machineName\QueueName
Public queue's journal: machineName\QueueName;Journal
Private queue: machineName\PRIVATE$\QueueName
Private queue's journal: machineName\PRIVATE$\QueueName;Journal
Machine journal queue: machineName\JOURNAL
Machine deadletter queue: machineName\DEADLETTER
Machine transaction deadletter queue: machineName\DEADXACT

Note: machineName can be substituted with '.' to designate the local machine.

If the actual format name of the queue is known, this call may be used to transform it into the expected unicode string. Possible format name representations are as follows:

Public queue: public=QueueGUID
Public queue's journal: public=QueueGUID;JOURNAL
Private queue: private=machineGUID\QueueNumber
Private queue's journal: private=machineGUID\QueueNumber;JOURNAL
Direct public queue: direct=AddressSpec\QueueName
Direct private queue: direct=AddressSpec\PRIVATE$\QueueName
where AddressSpec is of the form protocol:address (For example, tcp:10.26.1.177)
Machine journal queue: machine=machineGUID;JOURNAL
Machine deadletter queue: machine=machineGUID;DEADLETTER
Machine transaction deadletter queue: machine=machineGUID;DEADXACT
Foreign queue: connector=ForeignCNGUID
Foreign transaction queue: connector=ForeignCNGUID:XACTONLY

qid

Numeric, output
Returns the queue identifier that represents the format name of the queue.

rc

Example

This example obtains the format name of a queue from the pathname.


   length msg $ 200;

   qid=0;
   rc=0;
   CALL MSMQPATHTOFORMAT("pcpad\testq", qid, rc);
   if rc ^= 0 then do;
    put 'MSMQPathToFormat: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQPathToFormat: succeeded';

MSMQINSTTOFORMAT

Returns a queue identifier that represents a format name based on the instance identifier provided.

Syntax

CALL MSMQINSTTOFORMAT(instance, qid, rc);

instance: Character representing binary data, input
Specifies the globally unique identifier (GUID) instance of the queue.
qid: Numeric, output
Returns the queue identifier that represents the format name of the queue.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example obtains the format name of a queue from an instance GUID.


   length msg $ 200;

   qid=0;
   rc=0;
   CALL MSMQINSTTOFORMAT(guid, qid, rc);
   if rc ^= 0 then do;
    put 'MSMQInstToFormat: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQInstToFormat: succeeded';

MSMQHNDLTOFORMAT

Returns a queue identifier that represents a format name based on its open handle.

Syntax

CALL MSMQHNDLTOFORMAT(hQueue, qid, rc);

hQueue: Numeric, input
Specifies the MSMQ handle to an open queue. This parameter was obtained from a previous MSMQOPENQUEUE function call.
qid: Numeric, output
Returns the queue identifier that represents the format name of the queue.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example obtains the format name of a queue from a queue handle.


   length msg $ 200;

   qid=0;
   rc=0;
   CALL MSMQHDNLTOFORMAT(hQueue, qid, rc);
   if rc ^= 0 then do;
    put 'MSMQHndlToFormat: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQHndlToFormat: succeeded';

MSMQSENDMSG

Sends a message to the specified queue.

Syntax

CALL MSMQSENDMSG(hQueue, hData, transObj, rc, propids, value1 <,value2, ...>);

hQueue

Numeric, input
Specifies the MSMQ handle to an open queue. This parameter was obtained from a previous MSMQOPENQUEUE function call.

hData

Numeric, input
Specifies the SAS internal data descriptor handle obtained from a previous MSMQSETPARMS function call. If set to zero, 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 set to zero, it is assumed that this operation will not be part of a transaction.

rc

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 acknowledgement indicates the message sent was received successfully. A negative acknowledgement 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/negative acknowledgments are posted indicating whether or not the message reaches the queue.
"FULL_RECEIVE": Specifies that positive/negative acknowledgments are posted indicating whether or not 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 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 representing 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 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 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 may 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 representing 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 GUID 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 returned from MSMQGETCONTEXT.

SENDER_CERT

Specifies the name of the system certificate store to use 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) 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 will be 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 specified by the source queue manager.

Note: The BODY message property is set internally based on whether or not data is present.

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

MSMQRECEIVEMSG

Reads a message from the queue.

Syntax

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

hQueue

Numeric, input
Specifies the MSMQ handle to an open queue. This parameter was 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 timeout parameter equal to -1.

action

Character, input
Determines how and where the message will be read from the queue. This parameter is also used to determine if the message is removed after reading. Possible values are valid:

"RECEIVE": Read message at current cursor location and remove 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, the queue's cursor can only point 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 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 was obtained from a previous MSMQBEGINTRANS function call. If set to zero, it is assumed that this operation will not be part of a transaction.

rc

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/negative acknowledgments are posted indicating whether or not the message reaches the queue.
"FULL_RECEIVE": Specifies that positive/negative acknowledgments are posted depending on whether or not 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 representing the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

AUTHENTICATED

Retrieves whether or not the message was authenticated. The following values are valid:

0 : Message is NOT authenticated.
1 : Message is authenticated.

BODY

Specifies whether or not 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 representing binary data. Initialize the variable to a size of at lease 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 may 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 representing 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 GUID 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 representing the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

SRC_MACHINE_ID

Retrieves the GUID of the computer where the message was sent. This value is a GUID 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) 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 will be 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 specified by the source queue manager.

VERSION

Retrieves the version of MSMQ 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 (parms) to that data.

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;

MSMQCREATECURSOR

Creates a cursor used to maintain a specific location in a queue when reading its messages.

Syntax

CALL MSMQCREATECURSOR(hQueue, hCursor, rc);

hQueue: Numeric, input
Specifies the MSMQ handle to an open queue. This parameter was obtained from a previous MSMQOPENQUEUE function call.
hCursor: Numeric, output
Returns the handle of the cursor used for looking at messages in the queue. The MSMQCREATECURSOR routine is used to create a cursor and obtain its handle.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example creates a cursor.


   length msg $ 200;

   hCursor=0;
   rc=0;
   CALL MSMQCREATECURSOR(hQueue, hCursor, rc);
   if rc ^= 0 then do;
    put 'MSMQCreateCursor: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQCreateCursor: succeeded';

MSMQCLOSECURSOR

Closes a given cursor thereby allowing MSMQ to release the associated resources.

Syntax

CALL MSMQCLOSECURSOR(hCursor, rc);

hCursor: Numeric, input
Specifies the handle to a cursor used for looking at messages in the queue. The MSMQCREATECURSOR routine is used to create a cursor and obtain its handle.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example closes a cursor.


   length msg $ 200;

   rc=0;
   CALL MSMQCLOSECURSOR(hCursor, rc);
   if rc ^= 0 then do;
    put 'MSMQCloseCursor: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQCloseCursor: succeeded';

MSMQBEGINTRANS

Creates an internal MSMQ transaction object that can be used to send messages to a queue or read messages from a queue.

Syntax

CALL MSMQBEGINTRANS(transObj, rc);

transObj: Numeric, output
Returns the transaction object.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example creates a transaction object.


   length msg $ 200;

   transobj=0;
   rc=0;
   CALL MSMQBEGINTRANS(transobj, rc);
   if rc ^= 0 then do;
    put 'MSMQBeginTrans: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQBeginTrans: succeeded';

MSMQCOMMITTRANS

Commits a unit of work from an MSMQ transaction.

Syntax

CALL MSMQCOMMITTRANS(transObj, rc);

transObj: Numeric, input
Specifies the transaction object that was obtained from a previous MSMQBEGINTRANS function call.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example commits a unit of work from an MSMQ transaction.


   length msg $ 200;

   rc=0;
   CALL MSMQCOMMITTRANS(transobj, rc);
   if rc ^= 0 then do;
    put 'MSMQCommitTrans: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQCommitTrans: succeeded';

MSMQABORTTRANS

Aborts a unit of work from an MSMQ transaction.

Syntax

CALL MSMQABORTTRANS(transObj, rc);

transObj: Numeric, input
Specifies the transaction object that was obtained from a previous MSMQBEGINTRANS function call.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example aborts a unit of work from an MSMQ transaction.


   length msg $ 200;

   rc=0;
   CALL MSMQABORTTRANS(transobj, rc);
   if rc ^= 0 then do;
    put 'MSMQAbortTrans: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQAbortTrans: succeeded';

MSMQRELEASETRANS

Releases an internal MSMQ transaction object thereby allowing MSMQ to release the associated resources.

Syntax

CALL MSMQRELEASETRANS(transObj, rc);

transObj: Numeric, input
Specifies the transaction object that was obtained from a previous MSMQBEGINTRANS function call.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example releases a transaction unit of work.


   length msg $ 200;

   rc=0;
   CALL MSMQRELEASETRANS(transobj, rc);
   if rc ^= 0 then do;
    put 'MSMQReleaseTrans: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQReleaseTrans: succeeded';

MSMQLOCATE

Provides a means of locating a single public queue (or set of public queues) based on a set of criteria.

Syntax

CALL MSMQLOCATE(criteria, sortpref, rc, cProps, propids, value1 <,value2, ...>);

criteria

Character, input
Identifies the criteria to use for locating the queue(s). The criteria is based on a queue's properties and each property's value. The criteria parameter uses the following format:

"propid:op:value, ..."

where propid is a queue property, value is the propid value, and op is an operator used as the selection criteria. The op parameter can be:

LT (Less than)
LE (Less than or equal)
EQ (Equal)
NE (Not equal)
GE (Greater than or equal)
GT (Greater than)

sortpref

Character, input
Specifies the queue sorting preference. This parameter uses the following format:

"propid:order, ..."

where propid is a queue property, and order is the order preference. The order parameter can be specified as:

ASCEND (Ascending order)
DESCEND (Descending order)

rc

cProps

Numeric, output
Returns the number of property values that resulted from the criteria search.

propids

Character, input
Identifies one or more properties that you want to retrieve. This parameter is a character string with each applicable property separated by a comma.

Note: The number of values specified should be a multiple of propids specified. For example, if you specified 2 propids and wanted to retrieve these properties for the first 3 queues that meet the specified criteria, you must specify 6 (3x2) value parameters in order to retrieve these property values for all of the queues.

The following propids and values are valid:

AUTHENTICATE

Retrieves whether or not the queue only accepts authenticated messages. Initialize the variable appropriately to prevent truncation of the returned value from occurring. The following values are valid:

"NONE": Specifies the queue will accept either authenticated or non-authenticated messages.
"ALWAYS": Specifies the queue always requires authenticated messages.

BASEPRIORITY

Retrieves the base priority for all messages sent to a public queue. The value is a numeric that ranges from -32768 to 32767, where 32767 is the highest priority and 0 is the default priority.

CREATE_TIME

Retrieves the time and date when the queue was created. The value is a numeric representing the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

INSTANCE

Retrieves the queue's identifier (GUID). The value is a character string representing binary data. Initialize the variable to a size of at least 32 to guarantee that truncation of the returned value does not occur.

JOURNAL

Queries whether or not messages are also copied to its journal queue. Initialize the variable to a size of at least 32 to guarantee that truncation of the returned value does not occur. The following values are valid:

"NONE": Specifies that messages removed from the queue are discarded.
"ALWAYS": Specifies that messages removed from the queue are always stored in its journal queue.

JOURNAL_QUOTA

Retrieves the maximum size (in kilobytes) of the journal queue.

LABEL

Retrieves a description of the queue. The value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

PATHNAME

Retrieves the MSMQ pathname of the queue. The value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

PRIV_LEVEL

Retrieves the privacy level that is required by the queue. The value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring. The following values are valid:

"NONE": Specifies that the queue accepts only non-private (cleartext) messages.
"BODY": Specifies that the queue accepts only private (encrypted) messages.
"OPTIONAL": Specifies that the queue accepts both private and non-private messages.

QUOTA

Retrieves the maximum size (in kilobytes) of the queue.

TRANSACTION

Retrieves whether or not the queue uses MSMQ transactions. The value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring. The following values are valid:

"NONE": Specifies that the queue does not accept transaction operations.
"ALWAYS": Specifies that all messages sent to the queue must always be done through an MSMQ transaction.

TYPE

Retrieves the type of service provided by the queue. The value of the TYPE property is a globally unique identifier (GUID) 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.

Example

This example locates the first 3 queues with a label "Test Queue" and returns AUTHENTICATE, PRIV_LEVEL, and PATHNAME properties.


   length msg $ 200;
   length cProps 8;
   length auth1 auth2 auth3 priv1 priv2 priv3 $ 10;
   length path1 path2 path3 $ 80;

   rc=0;
   cProps=0;
   CALL MSMQLOCATE("LABEL:EQ:Test Queue", "", rc, cProps,
                   "AUTHENTICATE,PRIV_LEVEL,PATHNAME",
                   auth1, priv1, path1, auth2, priv2, path2, auth3, priv3, path3);
   if rc ^= 0 then do;
    put 'MSMQLocate: failed';
    msg = sysmsg();
    put msg;
   end;
   else do;
    put 'MSMQLocate: succeeded';
    if cProps = 0 then put 'no queues were found';
    else do;
     cProps = cProps/3; /* # queues */

     if cProps GE 1 then do;
      put 'queue 1 - authenticate is ' auth1;
      put 'queue 1 - privacy is ' priv1;
      put 'queue 1 - pathname is ' path1;
     end;

     if cProps GE 2 then do;
      put 'queue 2 - authenticate is ' auth2;
      put 'queue 2 - privacy is ' priv2;
      put 'queue 2 - pathname is ' path2;
     end;

     if cProps EQ 3 then do;
      put 'queue 3 - authenticate is ' auth3;
      put 'queue 3 - privacy is ' priv3;
      put 'queue 3 - pathname is ' path3;
     end;
   end;

MSMQGETQPROP

Retrieves properties for a specific queue.

Syntax

CALL MSMQGETQPROP(qid, rc, propids, value1 <,value2, ...>);

qid

Numeric, input
Specifies the queue identifier that represents the format name of the queue.

rc

propids

Character, input
Identifies one or more properties that you want to retrieve. This parameter is a character string with each applicable property separated by a comma.

For each property identified by propids, you must provide a value parameter that specifies a variable name to use to hold the returned property value.

The following propids and values are valid:

AUTHENTICATE

"NONE": Specifies the queue will accept either authenticated or non-authenticated messages.
"ALWAYS": Specifies the queue always requires authenticated messages.

BASEPRIORITY

Retrieves the base priority for all messages sent to a public queue. The value is a numeric that ranges from -32768 to 32767, where 32767 is the highest priority and 0 is the default priority.

CREATE_TIME

Retrieves the time and date when the queue was created. The value is a numeric representing the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

INSTANCE

Retrieves the queue's identifier (GUID). The value is a character string representing binary data. Initialize the variable appropriately to guarantee that truncation of the returned value does not occur.

JOURNAL

Retrieves if messages are also copied to its journal queue. Initialize the variable to a size of at least 32 to guarantee that truncation of the returned value does not occur. The following values are valid:

"NONE": Specifies that messages removed from the queue are discarded.
"ALWAYS": Specifies that messages removed from the queue are always stored in its journal queue.

JOURNAL_QUOTA

Retrieves the maximum size (in kilobytes) of the journal queue.

LABEL

Retrieves a description of the queue. The value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

MODIFY_TIME

Retrieves the last time the queue's properties were modified. The value is a numeric representing the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

PATHNAME

Retrieves the MSMQ pathname of the queue. The value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring.

PRIV_LEVEL

"NONE": Specifies that the queue accepts only non-private (cleartext) messages.
"BODY": Specifies that the queue accepts only private (encrypted) messages.
"OPTIONAL": Specifies that the queue accepts both private and non-private messages.

QUOTA

Retrieves the maximum size (in kilobytes) of the queue.

TRANSACTION

Retrieves whether or not the queue uses MQMQ transactions. The value is a character string. Initialize the variable appropriately to prevent truncation of the returned value from occurring. The following values are valid:

"NONE": Specifies that the queue does not accept transaction operations.
"ALWAYS": Specifies that all messages sent to the queue must always be done through an MSMQ transaction.

TYPE

Example

This example gets the queue properties and displays them.


   length msg $ 200;
   length base createt jquota modifyt quota 8;
   length auth journal priv trans $ 10;
   length inst type $ 32;
   length label path $ 80;

   rc=0;
   CALL MSMQGETQPROP(qid, rc, "AUTHENTICATE,BASEPRIORITY,CREATE_TIME,INSTANCE,JOURNAL,
                               JOURNAL_QUOTA,LABEL,MODIFY_TIME,PATHNAME,PRIV_LEVEL,
                               QUOTA,TRANSACTION,TYPE",
                               auth, base, createt, inst, journal, jquota, label,
                               modifyt, path, priv, quota, trans, type);
   if rc ^= 0 then do;
    put 'MSMQGetQProp: failed';
    msg = sysmsg();
    put msg;
   end;
   else do;
    put 'MSMQGetQProp: succeeded';

    put 'authenticate is ' auth;
    put 'base priority is ' base;
    /* convert MSMQ create time to SAS datetime format */
    createt = createt + 10*365*24*3600 + 3*24*3600 - 5*3600;
    put 'create time was ' createt datetime.;
    put 'instance identifier is ' inst;
    put 'journal enablement is ' journal;
    put 'journal quota is ' jquota;
    put 'label is ' label;
    /* convert MSMQ modify time to SAS datetime format */
    modifyt = modifyt + 10*365*24*3600 + 3*24*3600 - 5*3600;
    put 'last modification time was ' modifyt datetime.;
    put 'pathname is ' path;
    put 'privacy level is ' priv;
    put 'quota is ' quota;
    put 'transaction requirement is ' trans;
    put 'type of service is ' type;
   end;

MSMQSETQPROP

Sets the properties of a specific queue.

Syntax

CALL MSMQSETQPROP(qid, rc, propids, value1 <,value2, ...>);

qid

Numeric, input
Specifies the queue identifier that represents the format name of the queue.

rc

propids

Character, input
Identifies one or more properties that you want to set. This parameter is a character string with each applicable property separated by a comma.

For each property identified by propids, you must provide a value parameter that specifies the value to use to set the property.

The following propids and values are valid:

AUTHENTICATE

Specifies whether or not the queue only accepts authenticated messages. The following values are valid:

"NONE": Specifies the queue will accept either authenticated or non-authenticated messages.
"ALWAYS": Specifies the queue always requires authenticated messages.

BASEPRIORITY

Specifies the base priority for all messages sent to a public queue. The value is a numeric that ranges from -32768 to 32767, where 32767 is the highest priority and 0 is the default priority.

JOURNAL

Specifies if messages are also copied to its journal queue. The following values are valid:

"NONE": Specifies that messages removed from the queue are discarded.
"ALWAYS": Specifies that messages removed from the queue are always stored in its journal queue.

JOURNAL_QUOTA

Specifies the maximum size (in kilobytes) of the journal queue.

LABEL

Specifies a description of the queue. The value is a character string.

PRIV_LEVEL

Specifies the privacy level that is required by the queue. The value is a character string. The following values are valid:

"NONE": Specifies that the queue accepts only non-private (cleartext) messages.
"BODY": Specifies that the queue accepts only private (encrypted) messages.
"OPTIONAL": Specifies that the queue accepts both private and non-private messages.

QUOTA

Specifies the maximum size (in kilobytes) of the queue.

TYPE

Specifies the type of service provided by the queue. The value of the TYPE property is a globally unique identifier (GUID) in the form of a character string that represents the binary data.

Example

This example sets the queue properties.


   length msg $ 200;

   rc=0;
   CALL MSMQSETQPROP(qid, rc, "AUTHENTICATE,BASEPRIORITY,JOURNAL,JOURNAL_QUOTA,
                               LABEL,PRIV_LEVEL,QUOTA,TYPE",
                              "ALWAYS", 1, "ALWAYS", 32767, "New Label",
                              "BODY", 32767, "0A0B0C0D0E0F0102030405060708090A");
   if rc ^= 0 then do;
    put 'MSMQSetQProp: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQSetQProp: succeeded';

MSMQGETQSEC

Retrieves the access control security information for the specified queue.

Syntax

CALL MSMQGETQSEC(qid, rc, owner, dacl);

qid

Numeric, input
Specifies the queue identifier that represents the format name of the queue.

rc

owner

Character, output
Returns the owner of the queue. Initialize this variable appropriately to guarantee that truncation of the returned value does not occur.

dacl

Character, output
Returns the discretionary access control list for the queue. Initialize this variable appropriately to guarantee that truncation of the returned value does not occur. This parameter will be returned in the form of

"Domain\Account:accessType:Permissions,..."

where accessType is one of the following:

"ALLOW" (Permissions allowed)
"DENY" (Permissions denied)

Permissions is one or more of the following separated by '+':

Rj (Receive Journal)
Rq (Receive Message)
Pq (Peek Message)
Sq (Send Message)
Sp (Set Properties)
Gp (Get Properties)
D (Delete Queue)
Pg (Get Permissions)
Ps (Set Permissions)
O (Take Ownership)

Example

This example gets the queue security properties and displays them.


   length msg $ 200;
   length owner $ 60;
   length dacl $ 200;

   rc=0;
   CALL MSMQGETQSEC(qid, rc, owner, dacl);
   if rc ^= 0 then do;
     put 'MSMQGetQSec: failed';
     msg = sysmsg();
     put msg;
   end;
   else do;
     put 'MSMQGetQSec: succeeded';
     put 'owner is ' owner;
     put 'dacl is ' dacl;
   end;

MSMQSETQSEC

Sets the access control information for a specified queue.

Syntax

CALL MSMQSETQSEC(qid, rc <,owner, dacl>);

qid

Numeric, input
Specifies the queue identifier that represents the format name of the queue.

rc

owner

Character, input (Optional)
Identifies the owner of the queue. This parameter must be specified as "Domain\Account".

dacl

Character, input (Optional)
Specifies the discretionary access control list for the queue. This parameter must be specified in the form of

"Domain\Account:accessType:Permissions,..."

where accessType is one of the following:

"ALLOW": Permissions allowed
"DENY" (see note below): Permissions denied

Note: Windows NT 4.0 supports DENY access control entries but cannot edit security information which uses them. Therefore, this access type is not recommended until Windows NT 5.0 or later.

Permissions is one or more of the following separated by '+':

Rj (Receive Journal)
Rq (Receive Message)
Pq (Peek Message)
Sq (Send Message)
Sp (Set Properties)
Gp (Get Properties)
D (Delete Queue)
Pg (Get Permissions)
Ps (Set Permissions)
O (Take Ownership)

Example

This example sets the queue security properties to allow NTDOMAIN\User6 to Receive Messages (Rq), Get Properties (Gp), and Get Permissions (Pg).


   length msg $ 200;

   rc=0;
   CALL MSMQSETQSEC(qid, rc, "", "NTDOMAIN\User6:ALLOW:Rq+Gp+Pg");
   if rc ^= 0 then do;
     put 'MSMQSetQSec: failed';
     msg = sysmsg();
     put msg;
   end;
   else put 'MSMQSetQSec: succeeded';

MSMQGETSCONTEXT

Retrieves security information needed to authenticate messages.

Syntax

CALL MSMQGETSCONTEXT(certStor, hContext, rc);

certStor

Character, input
Specifies the name of the system certificate store to use to locate the desired external certificate. If NULL, the internal security certificate provided by MSMQ is used.

Generally, "MY" is used. The corresponding registry entry is:

HKEY_CURRENTUSER\Software\Microsoft\SystemCertificates\MY\Certificates

hContext

Numeric, output
Returns a handle to the security context buffer allocated by MSMQ.

rc

Example

This example gets the security context from internal MSMQ certificate.


   length msg $ 200;

   hContext=0;
   rc=0;
   CALL MSMQGETSCONTEXT("", hContext, rc);
   if rc ^= 0 then do;
     put 'MSMQGetSContext: failed';
     msg = sysmsg();
     put msg;
   end;
   else put 'MSMQGetSContext: succeeded';

MSMQFREESCONTEXT

Frees the memory allocated by MSMQGETSCONTEXT.

Syntax

CALL MSMQFREESCONTEXT(hContext, rc);

hContext: Numeric, input
Specifies the handle to the security context buffer allocated by MSMQ.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. A return code of -1 reflects a SAS internal error. Otherwise it represents an MSMQ error code. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

Example

This example frees the security context buffer.


   length msg $ 200;

   rc=0;
   CALL MSMQFREESCONTEXT(hContext, rc);
   if rc ^= 0 then do;
    put 'MSMQFreeSContext: failed';
    msg = sysmsg();
    put msg;
   end;
   else put 'MSMQFreeSContext: succeeded';

MSMQMAP

Defines a data map that can be subsequently used on a MSMQSETPARMS or MSMQGETPARMS call.

Syntax

CALL MSMQMAP(hMap, rc, desc1 <,desc2, desc3, ...>);

hMap

Numeric, output
Returns the SAS internally-generated map descriptor handle.

rc

Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.

descs

Character, input
Specifies descriptor parameters that are used to describe the different data types in a map. Each description (desc1, desc2, ...) defines the data type, an offset from the beginning of the message, and the length of the data. A descriptor has the following format:

"TYPE<,OFFSET,LENGTH>"

where:

TYPE is one of the following:

CHAR (Character data)
SHORT (Short binary)
LONG (Long binary)
DOUBLE (Floating point double)

OFFSET

The offset from the beginning of the message. This property is optional, so by default the data is not aligned (data starts at next available position in message).

LENGTH

The length of the data being represented. This property is optional in most cases. The only time length is required is when setting up to receive character data. Specifying length for numeric data is ignored since length is implicitly defined.

Note: Type coercion is performed transparently when you put SAS variables into a MSMQ message (MSMQSETPARMS) and also when you get SAS variables from a MSMQ message (MSMQGETPARMS). That is, if the data that you are sending or receiving is a different type than the SAS variable itself, the data will be coerced into the appropriate data type.

Example

This example defines a map to use to send and receive a message with a short, a long, a double and a character string. No alignment is specified for any data type, and strings will always be 200 characters in length (blank padded).


   hMap=0;
   rc=0;
   desc1="SHORT";
   desc2="LONG";
   desc3="DOUBLE";
   desc4="CHAR,,200"
   CALL MSMQMAP(hMap, rc, desc1, desc2, desc3, desc4);

MSMQSETPARMS

Creates a data descriptor that describes the actual SAS variables along with an associated data mapping. This data descriptor can then be used on a subsequent MSMQSENDMSG call.

Syntax

CALL MSMQQSETPARMS(hData, hMap, rc, parm1 <,parm2, parm3, ...>);

hData: Numeric, output
Returns the SAS internal data descriptor handle that is generated.
hMap: Numeric, input
Specifies the SAS internal map descriptor handle obtained from a previous MSMQMAP function call. If set to zero, no external defined mapping is assumed and therefore, all data will be mapped according to SAS internal representations. That is, all numerics will be mapped as doubles and all strings will be mapped as character data of the current string length.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.
parms: Numeric/character, input
Specifies one or more parameters used to define the values of SAS variables in a message.

Example

This example sets values of SAS variables into a message.


   hData=0;
   rc=0;
   parm1=100;
   parm2=9999;
   parm3=9999.9999;
   parm4="This is a test."
   CALL MSMQSETPARMS(hData, hMap, rc, parm1, parm2, parm3, parm4);

MSMQGETPARMS

Retrieves values of SAS variables from a previous MSMQ message that was received by a MSMQRECEIVEMSG call.

Syntax

CALL MSMQGETPARMS(hMap, rc, parm1 <,parm2, parm3, ...>);

hMap: Numeric, input
Specifies the SAS internal map descriptor handle obtained from a previous MSMQMAP function call.
rc: Numeric, output
Provides the return code from the CALL routine. If an error occurred, the return code will be non-zero. The SAS function SYSMSG() can be used to obtain a textual description of the return code.
parms: Numeric/character, input
Specifies one or more parameters used to define the values of SAS variables in a message. Initialize the variables appropriately to guarantee that truncation of the returned values does not occur.

Details

This message is available until the next MSMQRECEIVEMSG call is performed.

Example

This example gets values of SAS variables from a received message.


   length parm1 parm2 parm3;
   length parm4 $ 200;

   rc=0;
   CALL MSMQGETPARMS(hMap, rc, parm1, parm2, parm3, parm4);

MSMQFREE

Frees a SAS internal handle, thereby, releasing its resources.

Syntax

CALL MSMQFREE(handle);

handle

Numeric, input
Specifies a SAS internal handle obtained from a previous CALL routine. The following CALL routines return handles that may be used as input to this routine (the type of handle is also shown after the CALL routine name):

MSMQCREATEQUEUE - qid (format name representation)
MSMQPATHTOFORMAT - qid
MSMQINSTTOFORMAT - qid
MSMQHNDLTOFORMAT - qid
MSMQMAP - hMap
MSMQSETPARMS - hData

Example

This example frees a handle and its resources.


   CALL MSMQFREE(Handle);