Common Messaging Interface Call Routines

OPENQUEUE

Opens a message queue. You must use the CLOSEQUEUE CALL routine to close the message queue.

Transports supported:	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
Arguments
Example

Syntax

CALL OPENQUEUE(qid, tid, qname, mode, rc <, attr1 <, attr2>>);

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.

Note: 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. [cautionend]

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).

Note: 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. [cautionend]

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.

Note: 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. [cautionend]

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. [cautionend]

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)

Allows you to specify how message reception is handled for this queue. By default, the timeout period is set to INFINITE and a receive is blocked until a message arrives. To override the default, specify POLL and the timeout 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';

Top of Page