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, ...>);
Required 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:
-
-
-
-
-
GE (Greater than or equal)
-
- 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:
-
-
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.
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.
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.
Example: 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;