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
- 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.
- FETCHX
- 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.
- BROWSE
- 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.
- DELIVERY
- 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:
-
- DYNPERM
- DYNTEMP
-
- additional dynamic attributes
-
- DYN_MSGPSIST
- DYN_NOTICE
- DYN_MAXDEPTH=n
- DYN_MAXMSGL=n
- DYN_REQUIRED.
- non-dynamic,
instance based attributes:
-
| POLL |
| ENDPOSITIONING |
| SURVIVE. |
- DYNPERM,
DYNTEMP
- 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.
- DYN_MSGPSIST
- 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.
- DYN_NOTICE
- 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.
- DYN_MAXDEPTH=n
- 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.
- DYN_MAXMSGL=n
- 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.
- DYN_REQUIRED
- 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).
- POLL
- 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.
- ENDPOSITIONING
- 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.
- SURVIVE
- 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);
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.
