MSMQ Call Routines

MSMQLOCATE

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

Syntax
Arguments
Example

Syntax

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

Arguments

criteria

Character, input

Identifies the criteria to use for locating the queue or queues. The criteria are 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

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.

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 two propids and wanted to retrieve these properties for the first three queues that meet the specified criteria, you must specify six (3x2) value parameters in order to retrieve these property values for all of the queues. [cautionend]

The following propids and values are valid:

AUTHENTICATE

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

NONE: Specifies the queue accepts either authenticated or non-authenticated messages.
ALWAYS: Specifies the queue always requires authenticated messages.

BASEPRIORITY

Retrieves the base priority for all messages that are 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 that represents the number of seconds elapsed since midnight (00:00:00), January 1, 1970 (Coordinated Universal time).

INSTANCE

Retrieves the queue's identifier (UUID). The value is a character string that represents 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 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 (clear-text) 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 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 that are sent to the queue must always be done through an MSMQ transaction.

TYPE

Retrieves the type of service that is provided by the queue. The value of the TYPE property is a universal unique identifier (UUID) 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 three 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;

Top of Page