PURPOSE
TPDEQUEUE - routine to dequeue a message from a
queue
SYNOPSIS
01 TPQUEDEF-REC.
COPY TPQUEDEF.
01 TPTYPE-REC.
COPY TPTYPE.
01 DATA-REC.
COPY User data.
01 TPSTATUS-REC.
COPY STATDEF.
CALL "TPDEQUEUE" USING TPQUEDEF-REC TPTYPE-REC DATA-REC TPSTATUS-REC.
DESCRIPTION
TPDEQUEUE dequeues a message for processing from
the queue named by QNAME in the QSPACE-NAME
queue space.
By default, the message at the top of the queue is dequeued.
The default order of messages on the queue is defined when the
queue is created. The application can request a particular
message for dequeuing by specifying its message identifier using MSGID.
TPQUEDEF-REC settings can also be used to indicate that
the application wants to wait for a message, in the case where a
message is not currently available. See the section below
describing this record.
DATA-REC specifies where a dequeued message is read
into, and, on input LEN indicates the maximum number
of bytes that should be moved into DATA-REC. Upon
successful return, LEN contains the actual number of
bytes moved into DATA-REC. REC-TYPE and SUB-TYPE
contain the replies type and sub-type respectively. If the reply
is larger than DATA-REC, then DATA-REC will contain
only as many bytes as will fit in the record. The remainder of
the reply is discarded and TPDEQUEUE fails returning [TPTRUNCATE].
If LEN is 0 upon successful return, then
the reply has no data portion and DATA-REC was not
modified. It is an error for LEN to be 0 on
input.
The message is dequeued in transaction mode if the caller is
in transaction mode and TPTRAN is set. This has the
effect that if TPDEQUEUE returns successfully and the
caller's transaction is committed successfully, then the message
is deleted from the queue. If the caller's transaction is rolled
back either explicitly or as the result of a transaction timeout
or some communication error, then the message will be left on the
queue (that is, the deletion of the message from the queue is
also rolled back). This can be exploited to "peek" at a
message on the queue, rolling back the transaction to leave the
message on the queue (note that this cannot be done if TPNOTRAN
is set as described below). It is not possible to enqueue and
dequeue the same message within the same transaction.
The message is not dequeued in transaction mode if either the
caller is not in transaction mode, or TPNOTRAN is set.
The message is dequeued in a separate transaction. If a
communication error or a timeout occurs (either transaction or
blocking timeout), the application will not know whether or not
the message was successfully dequeued and the message may be
lost.
F:Following is a list of valid settings in TPQUEDEF-REC.
- TPNOTRAN
If the caller is in transaction mode and this setting is
used, then the message is not dequeued within the same
transaction as the caller. A caller in transaction mode
that sets this to true is still subject to the
transaction timeout (and no other). If message dequeuing
fails that was invoked with this setting, the caller's
transaction is not affected. Either TPNOTRAN
or TPTRAN must be set. - TPTRAN
If the caller is in transaction mode and this setting is
used, then the message is dequeued within the same
transaction as the caller. The setting is ignored if the
caller is not in transaction mode. Either TPNOTRAN
or TPTRAN must be set. - TPNOCHANGE
When this setting is used, the type of DATA-REC is
not allowed to change. That is, the type and sub-type of
the dequeued message must match REC-TYPE IN TPTYPE-REC
and SUB-TYPE IN TPTYPE-REC,
respectively, so long as the receiver recognizes the
incoming record type. Either TPNOCHANGE or TPCHANGE
must be set. - TPCHANGE
The type and/or subtype of the dequeued message is
allowed to differ from those specified in REC-TYPE
IN TPTYPE-REC and SUB-TYPE IN TPTYPE-REC,
respectively, so long as the receiver recognizes the
incoming record type. Either TPNOCHANGE or TPCHANGE
must be set. - TPNOBLOCK
The message is not dequeued if a blocking condition
exists (for example, the internal buffers into which the
message is transferred are full). This blocking condition
does not include blocking on the queue itself if the TPQWAIT
option is specified. Either TPNOBLOCK or TPBLOCK
must be set. - TPBLOCK
When TPBLOCK is specified and a blocking
condition exists, the caller blocks until the condition
subsides or a timeout occurs (either transaction or
blocking timeout). Either TPNOBLOCK or TPBLOCK
must be set. - TPNOTIME
This setting signifies that the caller is willing to
block indefinitely and wants to be immune to blocking
timeouts. Transaction timeouts may still occur. Either TPNOTIME
or TPTIME must be set. - TPTIME
This setting signifies that the caller will receive
blocking timeouts if a blocking condition exists and the
blocking time is reached. Either TPNOTIME or TPTIME
must be set. - TPSIGRSTRT
If a signal interrupts any underlying system calls, then
the interrupted system call is re-issued. Either TPNOSIGRSTRT
or TPSIGRSTRT must be set. - TPNOSIGRSTRT
If a signal interrupts any underlying system calls, then
the interrupted system call is not restarted and the
routine fails. Either TPNOSIGRSTRT or TPSIGRSTRT
must be set.
If TPDEQUEUE returns successfully, the application
can retrieve additional information about the message using TPQUEDEF-REC.
The information may include the message identifier for the
dequeued message, a correlation identifier that should accompany
any reply or failure message so that the originator can correlate
the message with the original request, the name of a reply queue
if a reply is desired, and the name of the failure queue on which
the application can queue information regarding failure to
dequeue the message. This is described below.
Control Structure
TPQUEDEF-REC is used by the application program to pass
and retrieve information associated with dequeuing the message.
The settings in TPQUEDEF-REC are used to indicate what
other elements in the structure are valid.
On input to TPDEQUEUE, the following elements may
be set in the TPQUEDEF-REC: 05 MSGID PIC X(32). 05
CORRID PIC X(32).
F:Following is a list of valid settings in TPQUEDEF-REC
controlling input information for TPDEQUEUE.
- TPQGETNEXT
If set, it requests that the next message on the queue be
dequeued, using the default queue order. Either TPQGETNEXT,
TPQGETBYMSGID or TPQGETBYCORRID
must be set. - TPQGETBYMSGID
If set, it requests that the message identified by MSGID
be dequeued. The message identifier would be one that was
returned by a prior call to TPENQUEUE(3cbl). Note that
the message identifier is not valid if the message has
moved from one queue to another; in this case, use the
correlation identifier. Either TPQGETNEXT, TPQGETBYMSGID
or TPQGETBYCORRID must be set. - TPQGETBYCORRID
If set, it requests that the message identified by CORRID
be dequeued. The correlation identifier would be one that
the application specified when enqueuing the message with
TPENQUEUE. Either TPQGETNEXT, TPQGETBYMSGID
or TPQGETBYCORRID must be set. - TPQWAIT
This setting indicates that an error should not be
returned if the queue is empty. Instead, the process
should block until a message is available. Set TPQNOWAIT
to not wait until a message is available. TPQWAIT
cannot be set if either TPQGETBYMSGID or TPQGETBYCORRID
is set.
On output from TPDEQUEUE, the following elements
may be set in TPQUEDEF-REC:
05 PRIORITY PIC S9(9) COMP-5.
05 MSGID PIC X(32).
05 CORRID PIC X(32).
05 REPLYQUEUE PIC X(15).
05 FAILUREQUEUE PIC X(15).
05 DIAGNOSTIC PIC S9(9) COMP-5.
05 CLIENTID OCCURS 4 TIMES PIC S9(9) COMP-5
05 APPL-RETURN-CODE PIC S9(9) COMP-5.
05 APPKEY PIC S9(9) COMP-5.
Following is a list of valid settings controlling output
information from TPDEQUEUE. If the setting is true
when TPDEQUEUE is called, the associated element in
the record is populated if available and the setting remains
true. If the value is not available, the setting will not be true
after TPDEQUEUE completes.
- TPQPRIORITY
If set and the value is available, the priority at which
the message was queued is stored in PRIORITY.
The priority is in the range 1 to 100, inclusive, and the
higher the number, the higher the priority (that is, a
message with a higher number is dequeued before a message
with a lower number). If TPQNOPRIORITY is set,
the priority is not available. - TPQMSGID
If set and the call to TPDEQUEUE was
successful, the message identifier will be stored in MSGID.
If TPQNOMSGID is set, the message identifier
is not available. - TPQCORRID
If set and the call to TPDEQUEUE was
successful and the message was queued with a correlation
identifier, the value will be stored in CORRID.
Any reply to a queue must have this correlation
identifier. If TPQNOCORRID is set, the
correlation identifier is not available. - TPQREPLYQ
If set and the message is associated with a reply queue,
the value will be stored in REPLYQUEUE. Any
reply to the message should go to the named reply queue
within the same queue space as the request message. If TPQNOREPLYQ
is set, the reply queue is not available. - TPQFAILUREQ
If set and the message is associated with a failure
queue, the value will be stored in FAILUREQUEUE.
Any failure message should go to the named failure queue
within the same queue space as the request message. If TPQNOFAILUREQ
is set, the failure queue is not available.
If the call to TPDEQUEUE failed and TP-STATUS
is set to TPEDIAGNOSTIC, a value indicating the reason
for failure is returned in DIAGNOSTIC. The possible
values are defined below in the DIAGNOSTICS section.
Additionally on output, APPKEY is set to
application authentication key, CLIENTID is set to the
identifier for the client originating the request, and APPL-RETURN-CODE
is set to the user-return code value that was set when the
message was enqueued.
RETURN VALUES
Upon successful completion, TPDEQUEUE sets TP-STATUS
to [TPOK].
ERRORS
Under the following conditions, TPDEQUEUE fails and
sets TP-STATUS to the following values (unless
otherwise noted, failure does not affect the caller's
transaction, if one exists):
- [TPEINVAL]
Invalid arguments were given (for example, QSPACE-NAME
is SPACES or settings in TPQUEDEF-REC
are invalid). - [TPENOENT]
Cannot access the QSPACE-NAME because it is
not available (the associated TMQUEUE(1) server is not
available). - [TPEOTYPE]
Either the REC-TYPE and SUB-TYPE of
the dequeued message are not known to the caller; or, TPNOCHANGE
was set and the REC-TYPE and SUB-TYPE
do not match the type and sub-type of the dequeued
message. Neither DATA-REC nor TPTYPE-REC
are changed. If the call was made on behalf of the
caller's current transaction, then the transaction is
marked abort-only and the message will remain on the
queue. - [TPTRUNCATE]
The size of the incoming message is larger than the size
specified in LEN. Only LEN amount
of data was moved to DATA-REC, the remaining data
is discarded. - [TPETIME]
A timeout occurred. If the caller is in transaction mode,
then a transaction timeout occurred and the transaction
is marked abort-only; otherwise, a blocking timeout
occurred and both TPBLOCK and TPTIME
were specified. In either case, neither DATA-REC
nor TPTYPE-REC are changed. If a transaction
timeout occurred, then any attempts to call TPDEQUEUE
or TPENQUEUE will fail with TPETIME
until the transaction has been aborted. - [TPEBLOCK]
A blocking condition exists and TPBLOCK was
set. - [TPGOTSIG]
A signal was received and TPNOSIGRSTRT was
set. - [TPEPROTO]
TPDEQUEUE was called in an improper context.
There is no effect on the queue or the transaction. - [TPESYSTEM]
A System/T error has occurred. The exact nature of the
error is written to a log file. There is no effect on the
queue. - [TPEOS]
An operating system error has occurred. There is no
effect on the queue. - [TPEDIAGNOSTIC]
Dequeuing a message from the specified queue failed. The
reason for failure can be determined by the diagnostic
value returned via TPQUEDEF-REC.
DIAGNOSTIC
The following diagnostic values are returned during the
dequeuing of a message.
- [QMEINVAL]
An invalid setting was specified. - [QMEBADRMID]
An invalid resource manager identifier was specified. - [QMENOTOPEN]
The resource manager is not currently open. - [QMETRAN]
The call was made with TPNOTRAN set and an
error occurred trying to start a transaction in which to
dequeue the message. - [QMEBADMSGID]
An invalid message identifier was specified for
dequeuing. - [QMEINUSE]
When dequeuing a message by correlation or message
identifier, the specified message is in-use by another
transaction. Otherwise, all messages currently on the
queue are in-use by other transactions. - [QMESYSTEM]
A system error has occurred. The exact nature of the
error is written to a log file. - [QMEOS]
An operating system error has occurred. - [QMEABORTED]
The operation was aborted. When executed within a global
transaction, the global transaction has been marked
rollback-only. Otherwise, the queue manager aborted the
operation. - [QMEPROTO]
A dequeue was done when the transaction state was not
active. - [QMEBADQUEUE]
An invalid or deleted queue name was specified. - [QMENOMSG]
No message was available for dequeuing. Note that it is
possible that the message exists on the queue and another
application process has read the message from the queue.
In this case, the message may be put back on the queue if
that other process rolls back the transaction.
SEE ALSO
TPENQUEUE(3cbl)