Programming Guide

Places a message on a reliable queue

enqueue QSPACE queueSpace NAME queueName message 
	[enqueueOption]... [ MSGID msgId]

QSPACE queueSpace

Specifies queueName's queue space.

NAME queueName

The name of the queue as defined in the JIF.

message

The message data to enqueue, as defined by the queue data type description in the JIF. For more information on message data types, refer to "Service Messages and Data Types" in JetNet/Oracle Tuxedo Guide.

enqueueOption

One or more of the following options:

CORRID corrID

Associates the message with a queue-independent identifier of up to 32 characters. Because this identifier can be maintained across all queues, the dequeue command can use it to identify a message. Other related messages can also be enqueued with it, such as reply or failure messages that are associated with message.

DQTIME dequeueTime

Specifies when to make the message available for dequeuing. If you omit this option, the message can be dequeued immediately. This option is valid only if the queue has been configured for time-based ordering; that is, queue order is set to time. For more information, refer to the Oracle Tuxedo /Q Guide of the Oracle Tuxedo SDK in your Oracle Tuxedo documentation.

The server dequeues the message and calls the appropriate service if it is monitoring the queue. dequeueTime can be a relative time (time elapsed after the message is enqueued) or an absolute time. An absolute time must be greater than January 1 1970 00:00:00 UTC. In either case, Panther can dequeue the command only after the specified amount of time has elapsed.

A relative dequeueTime can be specified in this format:

	"[ +days hours::minutes::]seconds"

Seconds are required; minutes, hours, or days (space delimiter between days and hours) can also be specified. If more than seconds is specified, the + symbol and the quotation marks are mandatory. If only seconds are specified, both are optional.

Note: JPL's colon preprocessor expands colon-prefixed variables. To prevent expansion of variables that contain colons, you must prefix literal colons with another colon (::) or a backslash (\:).

An absolute dequeueTime can be specified in one of these ways:

• The value from a Panther date/time field.

• A date/time string in this format: "mm/dd/yy HH::MM"

FAILUREQ queue | NOFAILUREQ

Specify a failure queue for failure responses, or use NOFAILUREQ if no failure message is expected. If neither option is specified, the JIF is checked for the default failure queue.

FRONT | BEFORE_MSGID msgId

Place the message in the queue:

• FRONT—Put the message at the head of the queue.

• BEFORE_MSGID msgId—Put the message ahead of the message with Oracle Tuxedo message identifier msgId.

NOTIMEOUT

Specifies that the enqueue operation is unaffected by the blocking timeout. This option has no effect on transaction timeouts. If you omit this option, Panther use the setting in the tp_timeout property.

OUTSIDE_TRANSACTION

Specifies to perform the enqueuing operation outside the current transaction. If message enqueuing fails, the current transaction is unaffected. If you specify this option, transaction-level exception and unload handlers are not executed when their corresponding events are generated.

PRIORITY priority

An integer between 1 and 100, inclusive, that establishes the message's priority, where 100 specifies the highest priority. This option is valid only if the queue's queue order parameter includes a priority setting. An out-of-range priority value generates the exception TP_INVALID_OPTION_VALUE. For further information on priority enqueuing, refer to the Oracle Tuxedo /Q Guide of the Oracle Tuxedo SDK in your Oracle Tuxedo documentation.

RCODE returnCode

An integer that specifies the return status to be made available to the dequeuing agent. The return code is handed to the reply queue from the service that replies to the message.

REPLYQ queue NOREPLYQ

Specifies a reply queue for replies to the message, or that no reply message is wanted (NOREPLYQ). If neither option is specified, the JIF is checked for a reply queue.

MSGID msgId

On return, msgId contains the unique Oracle Tuxedo message identifier that is generated after enqueue executes successfully. You can use this identifier to reference the enqueued message as long as it remains on the original queue.

JetNet, Oracle Tuxedo

Client, Server

The enqueue command puts a message in the specified queue. You identify the queue by specifying its queue name and queue space. This queue must be defined in the JIF; otherwise, the command fails and generates the exception TP_IN VALID_QUEUE. The enqueued message must conform to the data type defined in the JIF for the designated queue.

An enqueued message can only be removed from its queue by the dequeue command, and only after the DQTIME time delay (if any) elapses. The reply to this message is put in the REPLYQ-specified reply queue or, if this option is omitted, in the reply queue specified in queueName's JIF definition. enqueue can also specify a failure queue to supersede the one specified by the JIF. You can prevent reply and failure queueing with the NOREPLYQ and NOFAILUREQ options, respectively.

By default, messages are enqueued in first-in/first-out (FIFO) order. You can rely on this ordering when dequeuing messages, or you can use specific identifiers. Two kinds of identifiers are available:

• The Oracle Tuxedo-assigned message identifier that is returned with a successful enqueue command; you obtain this identifier through the MSGID option.

• A correlation ID that you explicitly assign to the enqueued message. This identifier is independent of the queue in which the message is placed; you should assign a correlation ID in order to identify the reply or failure messages that are generated in response to a dequeued message.

enqueue sets the tp_return property to NULL.

For more information on queueing and Oracle Tuxedo System /Q, refer to "Reliable Queues" in JetNet/Oracle Tuxedo Guide and refer to your Oracle Tuxedo documentation.

enqueue can generate the following exceptions:

Exception	Severity	Cause
TP_INVALID_COMMAND_SYNTAX	TP_COMMAND	Command syntax is invalid.
TP_INVALID_VARIABLE_REF	TP_COMMAND or TP_WARNING	Unable to resolve reference to Panther variable.
TP_INVALID_OPTION_VALUE	TP_COMMAND	An invalid time value is specified in the DQTIME option or PRIORITY value is out-of-range.
TP_INVALID_QUEUE	TP_COMMAND	Queue is not defined in the JIF.
TP_QUEUE_SPACE_NOT_IN_JIF	TP_COMMAND	Queuespace not found in the JIF.
TP_NO_OUTSIDE_TRANSACTION	TP_WARNING	There is no current transaction.

dequeue

---

---