Open message queue instance.
CALL
SEND(queueInst, '_open', stationInst, queue_name, mode, rc <,
attrib1...attribn>);
|
Where... |
Is type... |
And represents... |
stationInst |
N |
successfully opened station instance |
queue_name |
C |
name of message queue to open |
mode |
C |
open mode |
rc |
N |
return code |
attrib1... attribn |
C |
zero or more optional attributes |
When invoked on a Queue
instance, _open opens a message
queue. The user is responsible for obtaining an instance of the Queue class,
and then sending the _open method to it. After it is opened, the Queue instance
can be used to send or receive messages to the message queue (depending on
the open mode).
A station interface instance should already have been
opened and should be passed in as the stationInst.
queue_name is the name of the message queue
to open.
mode indicates the open mode. It should
be set to one of the following:
- FETCH
- enables messages to be retrieved from the
queue by using the _recv or _recvlist methods. The message is removed from
the queue after it is retrieved by using the _query method.
- FETCHX
- is exactly like FETCH mode except that it
ensures that this open instance has exclusive fetching privileges. The queue
can still be opened for browsing and delivering messages as described later.
- BROWSE
- enables the message to be retrieved from
the queue instance 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
- enables messages to be sent to the queue.
If an error or warning condition is encountered during
the open, a non-zero return code is returned in the rc parameter.
The return codes that follow are a defined set of error conditions that can
be checked by using the SYSRC macro, which is provided in the autocall library
that is supplied by SAS Institute.
If the rc is not one of the messages shown here, use SYSMSG()
to determine the exact error message.
- _SEINVMO
- indicates that the mode that is specified
on the open is invalid. Valid modes are FETCH, FETCHX, BROWSE or DELIVERY.
- _SEINVAT
- indicates that one of the (optional) attributes
is invalid. Valid attributes are listed below.
- _SEQEXST
- indicates an error occurred because of a
contention failure; the queue already exists.
- _SEQDPD
- indicates delivery permission was denied;
user does not have permission to deliver messages to the queue.
- _SEQFPD
- indicates fetch permission was denied; user
does not have permission to fetch messages from the queue.
- _SEQBPD
- indicates browse permission was denied;
user does not have permission to browse messages from the queue.
Here are a number of optional attributes
that may be specified in the attribs parameter(s).
- 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
- There are two ways to dynamically create
a queue at open time. 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 pre-defining a queue before it is opened.
You can create an administrator predefined queue by either defining it during
PROC DOMAIN start-up using registration syntax or by defining it through a
remote procedural command interface (The ADMIN Procedure)
that communicates directives to an executing DOMAIN server.
- DYN_MSGPSIST
- 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
- 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, _recv is required to receive the message into SAS variables.
The DYN_NOTICE 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, and not the message, is retrieved, a _recv is
not required to receive the message. See the _query method for more information
about how to query a NOTICE message delivery mode queue.
- DYN_MAXDEPTH=n
- allows you to specify a maximum queue depth
restriction to be placed on this queue.
- DYN_MAXMSGL=n
- 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.
- DYN_REQUIRED
- specifies that this open is required to
be successful. 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 will get a contention error. With this attribute
specified, a same name queue will be opened successfully without any 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 the queue at the beginning. To override the default, specify
this attribute so that the queue is positioned at the end. 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. This means that an application can dynamically
create a temporary queue when the DYNTEMP and SURVIVE attributes are set and
then exit. This leaves the queue to "survive" so that others can use it. If
SURVIVE was not specified, the temporary queue is deleted automatically when
the queue is closed.
This example opens two Queue instances. The first open
specifies the DYNTEMP attribute, which indicates that this queue should not
already exist, but it will be dynamically created. It will be 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 will be opened with the DELIVERY attribute so that messages
can be sent to the queue that is named "inventory".
After the queues are opened, FETCHQ and DELIVQ can be
used to send and receive messages.
stationid = loadclass('sashelp.connect.station');
stationInst = instance(stationid);
collectionName = "DMMAPPL";
call send(stationInst, "_open", collectionName, rc);
queueid = loadclass('sashelp.connect.queue');
fetchq = instance(queueid);
call send(fetchq, '_open', stationInst, "inventory",
"FETCH", rc, "DYNTEMP");
delivq = instance(queueid);
call send(delivq, '_open', stationInst, "inventory",
"DELIVERY", rc, "POLL");
Copyright 1999 by SAS Institute Inc., Cary, NC, USA. All rights reserved.