Chapter Contents




Open message queue.



CALL QUEUE_OPEN(queueId, stationId, queueName, mode, rc, <, attribs>);

Where... Is type... And represents...
queueId N queue identifier is returned
stationId N station identifier
queueName C name of message queue to open
mode C open mode
rc N return code
attribs C optional open attributes

When invoked, QUEUE_OPEN opens a message queue that is associated with a specific collection.

Upon successful open of the queue, the queueId is updated and returned. The queueId parameter will be used by subsequent calls to identify which queue to act upon. After opening, use the queue identifier to send or receive messages on that message queue (depending on the open mode).

stationId identifies the "collection" that the queue will be associated with. The stationId parameter should have been obtained from a call to the STATION_OPEN routine.

The queueName parameter is the name of the message queue to open. This name must be unique within its associated collection; however, the same queue name may be used within another collection.

The mode parameter indicates the open mode. It should be set to one of the following:

FETCH mode enables messages to be retrieved from the queue using the QUEUE_RECV CALL routine. The message is removed from the queue once it is retrieved using the QUEUE_QUERY CALL routine.

This mode exactly like FETCH mode except that it ensures that this open instance has exclusive fetching privileges. Anyone can still open the queue for browsing or delivering messages.

This mode enables the message to be retrieved from the queue without removing it from other instances of the queue. That is, the message still exists on other instances of the queue after browsing it.

This mode enables messages to be sent to the queue.

If an error or a warning condition is encountered during the open, a non-zero return code is returned in the rc parameter. Use the SYSMSG() function to print the message that is associated with the non-zero rc.

The following optional attributes may be specified in the attribs parameter(s):

Optional Attributes

dynamic creation attributes:



additional dynamic attributes





non-dynamic, instance based attributes:

Using one of these attributes causes a queue to be dynamically created. If the queue already exists, a queue contention error is reported. There are two ways to dynamically create a queue. Specify DYNPERM to create a permanent queue that will continue to exist after the queue is closed, or specify DYNTEMP to create a temporary queue that will be deleted automatically when closed. In contrast to dynamic creation is the idea of predefining a queue before it is opened. You can create an administrator pre-defined queue by defining it during PROC DOMAIN start-up using registration syntax or by defining it through a remote procedural command interface that communicates directives to an executing DOMAIN server. See The ADMIN Procedure for more information.

Dynamic creation attribute that enables message persistence. That is, all messages delivered to this queue will persist on the queue indefinitely or until they are explicitly fetched from the queue. By default, messages do not persist.

Dynamic creation attribute that enables NOTICE message delivery mode. By default, when a query on a queue executes, it not only retrieves the message header information, but it also retrieves the actual message itself from the queue. At this point, QUEUE_RECV is required to receive the message into SAS variables. This attribute can be specified to override the default behavior so that only message header information is returned from the query. Because only the header information (not the message) is retrieved, a QUEUE_RECV is not required to receive the message. See the QUEUE_QUERY method for more information about how to query a NOTICE message delivery mode queue.

Dynamic creation attribute that allows you to specify a maximum queue depth restriction to be placed on this queue. The n parameter is an integer value. The default value for n is -1, which indicates the depth is unlimited.

Dynamic creation attribute that allows you to specify a maximum message length restriction to be placed on all messages delivered to this queue. This maximum length must account for additional internal bytes needed to represent the data within each message. Attachment lengths are not taken into consideration, only the length of the actual message itself. The n parameter is an integer value. The default value for n is -1, which indicates the length is unlimited.

Dynamic creation attribute that specifies that, to be successful, this open is required. If a queue already exists, it is used; otherwise, the queue is dynamically created as specified. It is important to point out that this attribute overrides default dynamic creation behavior. By default if a same name queue already exists, you get a contention error. With this attribute specified, a same name queue is opened successfully without error. Also, if a same name queue already exists, it will be opened with existing attribute information (dynamic attributes specified on the open call are ignored).

The default behavior when querying a queue is to block. This means that the query will not return until a message is received. Therefore, the querying application is blocked until a message is received. To override this default behavior, specify this attribute so that a query will return immediately even if there is no message (non-blocking). This is a valid option for FETCH, FETCHX, and BROWSE open modes.

When opening a queue, the default behavior is to position it at the beginning. To override the default, specify this attribute so that it will be positioned at the end of the queue. This means that any messages on the queue prior to the open will not be seen by this queue instance.

Specify this attribute to ensure that the queue outlives the application. That is, an application can dynamically create a temporary queue that has the DYNTEMP and SURVIVE attributes set, and then exit, leaving the queue to "survive" so that others can use it. If SURVIVE was not specified, the queue would be automatically deleted when it is closed.


This example opens two Queue instances. The first open specifies the DYNTEMP attribute, which indicates that this queue should not already exist and will, therefore, be dynamically created. It is opened in FETCH mode so that messages can be received from the queue named "inventory". In addition, the POLL attribute is set so that the queries will be non-blocking.

The second open does not specify any dynamic attributes. Therefore, the default action will be used to open the queue. The default means that the queue already exists out there with the same name. This second queue instance is opened with the DELIVERY attribute so that messages can be sent to the queue named "inventory".

f_qid and d_qid are returned from the open and can then be used to send and receive messages.

   /* open station instance             */
stname = "DMMAPPL";
stid = 0;
rc = 0;
call station_open(stid, stname, rc);

   /* open fetch queue                  */
f_qid = 0; 
qname = "inventory";
mode = "FETCH";
attrib1 = "DYNTEMP";
attrib2 = "POLL";
call queue_open(f_qid, stid, qname, mode,
                rc, attrib1, attrib2);

   /* open delivery queue               */
mode = "DELIVERY";
call queue_open(d_qid, stid, qname, 
                mode, rc);

Chapter Contents



Top of Page

Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.