OPENQUEUE
Opens a message queue. You must use the CLOSEQUEUE
CALL routine to close the message queue.
| Supports: |
MQSeries, MQSeries C, MSMQ, Rendezvous, Rendezvous-CM |
| Note: |
For Rendezvous Certified Message Delivery (Rendezvous-CM),
you must define a model definition for certified message delivery.
Use the SETMODEL call to define a model definition.
|
Syntax
CALL OPENQUEUE(qid, tid, qname, mode, rc , attr1 , attr2>>);
Required Arguments
- qid
-
Numeric, output
Returns the queue handle
for the opened queue. This handle is used in subsequent calls to send,
receive, and parse messages and attachments, and close the queue.
- tid
-
Numeric, input
Specifies the transport
handle that is obtained from the INIT function. If transport handle
is set to 0, then
qname is
assumed to be a queue alias name that is defined in the information
repository, and the transport is initialized (and terminated at close) automatically.
- qname
-
Character, input
Specifies the name
of the queue to open.
The syntax for an MQSeries
transport is:
MQSeries:QMgr:Queue
The syntax for an MSMQ
transport is:
MSMQ:
PathName |
FormatName
The following PathName
representations are valid:
-
machineName\QueueName (public queue)
-
machineName\QueueName;Journal (public
queue's journal)
-
machineName\PRIVATE$\QueueName
(private queue)
-
machineName\PRIVATE$\QueueName;Journal
(private queue's journal)
-
machineName\Journal (machine journal
queue)
-
machineName\DeadLetter (machine deadletter
queue)
-
machineName\DeadXACT (machine transaction deadletter
queue)
Note: machineName can be substituted
with "." to designate the local machine.
The following FormatName
representations are valid:
-
PUBLIC=QueueGUID (public queue)
-
PUBLIC=QueueGUID;Journal (public
queue's journal)
-
PRIVATE=machineGUID\QueueNumber
(private queue)
-
PRIVATE=machineGUID\QueueNumber;Journal
(private queue's journal)
-
DIRECT=AddressSpecification\QueueName
(direct format for public queue)
-
DIRECT=AddressSpecification\PRIVATE$\QueueName
(direct format for private queue)
where AddressSpecification
is
protocol :
address (for example,
tcp:10.26.1.177).
You can use direct
format in certain situations. Consult MSMQ documentation for details.
You can also use a queue alias name that is defined in the information
repository as the
qname parameter.
The syntax for a Rendezvous
or Rendezvous-CM transport is:
SubjectName |
InboxName
- SubjectName
-
consists of one or
more elements separated by dot characters (periods). The elements
can represent a subject name hierarchy. For example:
RUN.HOME
RUN.for.Elected_office.President
- InboxName
-
is generated by the
Rendezvous software. The syntax is the same as SubjectName , but must begin with _INBOX as the
first element.
If an inbox name is
specified, the name must have already been created and returned by
another call. For example, a RECEIVEMESSAGE call might have returned
an inbox name in its
respq attribute.
When the queue is being opened for sending, wildcard characters ('*'
and '>') are not allowed.
- mode
-
Character, input
Identifies the operational
mode of the queue that is opened. You can use only one mode to open
a queue.
The following modes
for the MSMQ and MQSeries transports are valid:
- DELIVERY
-
Enables messages to
be sent to a queue
- FETCH
-
Enables messages to
be destructively retrieved
- FETCHX
-
The same as FETCH except
it ensures exclusive usage
- BROWSE
-
Enables messages to
be nondestructively retrieved.
The following modes
for the Rendezvous and Rendezvous-CM transport are valid:
- DELIVERY
-
enables messages to
be sent to a queue.
- FETCH
-
enables messages to
be retrieved.
- FETCHX
-
same as FETCH except
used for point-to-point or private messages (using inboxes) instead
of broadcast messages (using subject names). The qname property must be left blank ('') on the
open call. A private inbox name is generated and associated with the
qid . To access this queue,
retrieve the inbox name by using GETQUEUEPROPS. Use the value returned
as the response queue value on send message calls when notifying a
partner application of the private inbox name to send responses to.
For Rendezvous-CM, if persistent messaging is not required, then you
can use the FETCHX mode. The FETCHX mode should not be used with persistent
messaging because inbox names do not survive transport invalidation.
- REQUEST
-
enables request messages
to be sent to a subject (queue) that is being monitored by a remote
program that serves as an information supplier. The qname parameter should specify the name of the
queue to which the request message is to be sent. Any responses received
arrive on the queue that is specified in the respqueue parameter of the SENDMESSAGE call.
- REQUESTX
-
same as REQUEST except
used for point-to-point or private messages (using inboxes) instead
of broadcast messages (using subject names). The qname parameter should specify the name of the
queue on which the request message is to be sent. Any responses received
use the inbox name associated with the qid . This inbox name is created internally by Rendezvous when the respqueue parameter is initialized to null.
For Rendezvous-CM, if persistent messaging is not required, then you
can use the REQUESTX mode. The REQUESTX mode should not be used with
persistent messaging because inbox names do not survive transport
invalidation.
Note: Before any messages are sent
with the Rendezvous transport, the queues that receive the messages
must be running and must have a listener (that is, the queues must
be opened for FETCH, FETCHX, REQUEST, or REQUESTX). Otherwise, data
will be lost. Queues that are opened for REQUEST and REQUESTX automatically
have their receiving (response) queues open to listen for incoming
messages when the initial request is sent.
- rc
-
Numeric, output
Provides the return
code from the CALL routine. If an error occurs, then the return code
is nonzero. You can use the SAS function SYSMSG() in order to obtain
a textual description of the return code.
- attrs
-
Character, input
Specifies one or more
attributes to be associated with the queue. Each attribute constitutes
a separate parameter in the open call. The following attributes are
valid:
- POLL (Timeout=wait_period_in_seconds)
-
Enables you to specify
how message reception is handled for this queue. By default, the time-out
period is set to INFINITE and a receive is blocked until a message
arrives. To override the default, specify POLL and the time-out period.
- DYNAMIC (Model=model_name)
-
Signifies that the
queue is to be dynamically created, and specifies a model name that
is defined in the information repository, which specifies how to create
the queue. For the MQSeries transport, the model is defined in the
MQSeries configuration, not in the SAS information repository.
- CLUSTER (CLUSTER=BIND(bind_type))
-
Allows for setting
of open options that enables MQSeries to connect to clusters. This
attribute is valid only for MQSeries. Values for bind_type can be:
- OPEN
-
translates to MQOO_BIND_ON_OPEN
- NOT_FIXED
-
translates to MQOO_BIND_NOT_FIXED
- AS_Q_DEF
-
translates to MQOO_
BIND_AS_Q_DEF
Example
The following example
opens a queue for delivery by using an alias name:
length msg $ 200;
length qid tid rc 8;
/* MYQUEUE exists as a queue alias definition
in the SAS information repository. */
rc=0;
qid=0;
tid=0;
call openqueue(qid, tid, 'MYQUEUE',
'DELIVERY', rc, "POLL(Timeout=5)");
if rc ^= 0 then do;
put 'OPENQUEUE: failed';
msg = sysmsg();
put msg;
end;
else put 'OPENQUEUE:
succeeded';