Chapter Contents

Previous

Next

_open

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.

Optional Attributes

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.

Example

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");

Chapter Contents

Previous

Next

Top of Page

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