SAS/CONNECT User's Guide

Queue Management

The queue manager is responsible for allocating the queues, maintaining access information for each of the queues, and administering the messages that belong to each queue.

Queues can be designated as permanent or temporary. Permanent queues remain until they are explicitly deleted. Temporary queues are implicitly deleted when they are closed.

Messages within permanent queues may be persistent or non-persistent. Persistent messages remain indefinitely until they are fetched, even if the DOMAIN server process is shutdown. Non-persistent messages are purged when a queue is closed.

The queue manager is solely responsible for maintaining the queues and for ensuring that the messages in the queues reach their destination when requested and are not lost. The queue manager is also responsible for establishing the information that is needed by the network protocols that are being used to transmit the messages to and from the queues.

Example

The COLLECTION option must be specified in the PROC DOMAIN statement, in order to use indirect messaging. An example follows:

libname domain ".";
proc domain collection id=/shr9;
run;

After it is started, the collection manager continues to run until the PROC ADMIN statement is used to terminate it.

DOMAIN Registry

Administrator capabilities are an important part of message queueing functionality. Allowing an administrator to register queues provides centralized control of queue definition (how the queue functions as well as who can access it).

All queues are registered or defined, either dynamically or explicitly, through a registration process. A queue that is explicitly registered is known as an administrator pre-defined queue. This type of queue is a permanent queue. It can only be deleted by an administrator who uses the Administrator Procedure Interface. This section discusses how to define such a queue. Refer to either SAS Component Language (SCL) Interface to Indirect Messaging or CALL Routine Interface to Indirect Messaging for information about how to dynamically create a queue.

An administrator pre-defined queue can be registered during the PROC DOMAIN collection initialization if proper steps are taken. If a registration file has been created and a fileref of REGISTRY exists that references this file, the DOMAIN server will parse, interpret, and process this registry information.

Registry Syntax

Comments (/* ... */) can be included anywhere within the file. Queue definition as well as administrator privilege registration can be accomplished from four types of directives: USER, GROUP, QUEUE, and ADMIN.

USER Directive - defines users and their identifiers.

Syntax Notes:

username: is a descriptive name for the userid. This name may be a maximum of 32 characters in length. It is only significant to the administrator of this file.
userid: identifies connecting users and may be a maximum of 20 characters in length.

USER username userid;
USER username userid;
USER username userid;

GROUP Directive - defines a group of users.

Syntax Notes:

groupname

identifies a group of users and may be a maximum of 32 characters in length.

username

identifies a previously defined user name from a USER directive.

GROUP groupname
   username
   username
   username;

QUEUE Directive - defines message queue and its attributes.

Syntax Notes:

queue_name: identifies the name of the queue and may be a maximum of 32 characters in length.
collection_name: identifies the collection that the queue belongs to. It can be a maximum of 32 characters in length.
msgpsist: identifies whether messages on this queue are persistent. Persistent messages remain on the queue across queue open-and-close boundaries as well as DOMAIN server start-and-stop boundaries. Valid values for this attribute are yes or no. The default is no, which means that messages do not persist.
msgdlvmode: identifies the type of delivery mode operation that is used to fetch or to browse messages from this queue. Valid values for this attribute are default (fetch-mode operation) or notice (notice-mode operation). The default is default, which specifies the fetch-mode operation.
maxdepth: identifies the maximum depth restriction imposed on this queue. Valid queue depth values are in the range -1<=maxdepth<=maxint. The default is -1, which indicates unlimited depth.
maxmsgl: identifies the maximum message length for messages that are delivered to this queue. This maximum length must account for additional internal bytes that are needed to represent the data within each message. Attachment lengths are not taken into consideration, only the length of the actual message itself. Valid values are in the range -1<=maxmsgl<=maxint. The default is -1, which indicates unlimited message length.

username_or_groupname

identifies a previously defined user name from a USER directive, a previously defined group name from a GROUP directive, or the special name ANONYMOUS, which can be used to grant privileges to all users.

permissions

are specified by using the following values (an abbreviated form of these values is also acceptable):

DELIVER | D: Deliver privileges.
FETCH | F: Fetch privileges.
BROWSE | B: Browse privileges.
GETPROP | GP: Get property privileges.
SETPROP | SP: Set property privileges.
GETSEC | GS: Get security privileges.
SETSEC | SS: Set security privileges.
ALL: Full privileges.

Combinations of the above are also acceptable by separating values with either a plus sign ( +) or a comma ( ,). For example, you could give DELIVER and BROWSE privileges to a user by specifying one of the following:

DELIVER,BROWSE
D+B (abbreviated form).

replace

identifies the action to take if queue already exists. Valid values for this action are:

no: indicates to continue without replacement (definition is ignored). This is the default.
yes: indicates to replace queue with new definition and refresh the queue by deleting any old messages.
prompt: specifies that you are prompted for the action to take.

QUEUE queue_name COLLECTION|C(collection_name)
   MSGPSIST(msgpsist)
   MSGDLVMODE(msgdlvmode)
   MAXDEPTH(maxdepth)
   MAXMSGL(maxmsgl)
   PRIVILEGES(username_or_groupname=permissions
              username_or_groupname=permissions
              username_or_groupname=permissions)
   REPLACE(replace)
;

ADMIN Directive - defines queue administrative privileges for a specific user or a group.

Syntax Notes:

username_or_groupname

permissions

are specified with the following values (an abbreviated form of these values is also acceptable):

UNLIMITED | U: unlimited privileges; user can issue any administrator command.
DISPLAY | D: display privileges; user can only issue the display command. They cannot issue any destructive commands.

replace

identifies the action to take if administrator privileges already exist. Valid values for this action are:

no: indicates to continue without replacement (new privileges are ignored). This is the default.
yes: indicates you should replace existing privileges with new ones.
prompt: specifies that you are prompted for the action to take.

ADMIN
   PRIVILEGES(username_or_groupname=permissions
              username_or_groupname=permissions
              username_or_groupname=permissions)
   REPLACE(replace)
;

Chapter Contents
Previous
Next
Top of Page