ATMI COBOL Function Reference
TPDEQUEUE()
- routine to dequeue a message from a queue
01
TPQUEDEF-REC
.
COPY TPQUEDEF.
01TPTYPE-REC
.
COPY TPTYPE.
01DATA-REC
.
COPY User data.
01TPSTATUS-REC
.
COPY STATDEF.
CALL "TPDEQUEUE" USINGTPQUEDEF-REC
TPTYPE-REC
DATA-REC
TPSTATUS-REC
.
TPDEQUEUE()
takes 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 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
or correlation identifier using CORRID
. TPQUEDEF-REC
settings can also be used to indicate that the application wants to wait for a message, in the case when a message is not currently available. It is possible to use the TPQUEDEF-REC
structure to look at a message without removing it from the queue or changing its relative position on the queue. See the section below describing this record.
DATA-REC
specifies where a dequeued message is to be 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 subtype 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 removed 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 removal of the message from the queue is also rolled back). 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. When not in transaction mode, if a communication error or a timeout occurs, the application will not know whether or not the message was successfully dequeued and the message may be lost.
The following is a list of valid settings in TPQUEDEF-REC
.
If the caller is in transaction mode and this setting is used, the message is not dequeued within the caller's transaction. 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.
If the caller is in transaction mode and this setting is used, 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.
The message is not dequeued if a blocking condition exists. If TPNOBLOCK
is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and TP-STATUS
is set to TPEBLOCK
. If TPNOBLOCK
is set and a blocking condition exists because the target queue is opened exclusively by another application, the call fails, TP-STATUS
is set to TPEDIAGNOSTIC
, and the DIAGNOSTIC
field of the TPQUEDEF
record is set to QMESHARE
. In the latter case, the other application, which is based on a BEA product other than the BEA Tuxedo system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI). Either TPNOBLOCK
or TPBLOCK
must be set.
When TPBLOCK
is set and a blocking condition exists, the caller blocks until the condition subsides or a timeout occurs (either transaction or blocking timeout). This blocking condition does not include blocking on the queue itself if the TPQWAIT
setting is specified. Either TPNOBLOCK
or TPBLOCK
must be set.
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.
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.
When this setting is used, the type of DATA-REC
is not allowed to change. That is, the type and subtype 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.
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.
If a signal interrupts any underlying system calls, the interrupted system call is reissued. Either TPNOSIGRSTRT
or TPSIGRSTRT
must be set.
If TPDEQUEUE()
returns successfully, the application can retrieve additional information about the message using the TPQUEDEF-REC
structure. 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 quality of service the message was delivered with; the quality of service any replies to the message should be delivered with; 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. These are described below.
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).
The following is a list of valid settings in TPQUEDEF-REC
controlling input information for TPDEQUEUE()
.
Setting this value requests that the next message on the queue be dequeued, using the default queue order. One of the following must be set: TPQGETNEXT
, TPQGETBYMSGID
, or TPQGETBYCORRID
.
Setting this value requests that the message identified by MSGID
be dequeued. The message identifier may be acquired by a prior call to TPENQUEUE()
. Note that the message identifier changes if the message has moved from one queue to another. Note also that the entire 32 bytes of the message identifier value are significant, so the value identified by MSGID
must be completely initialized (for example, padded with spaces).
One of the following must be set: TPQGETNEXT
, TPQGETBYMSGID
, or TPQGETBYCORRID
.
Setting this value requests that the message identified by CORRID
be dequeued. The correlation identifier is specified by the application when enqueuing the message with TPENQUEUE()
. Note that the entire 32 bytes of the correlation identifier value are significant, so the value identified by CORRID
must be completely initialized (for example, padded with spaces).
One of the following must be set: TPQGETNEXT
, TPQGETBYMSGID
, or TPQGETBYCORRID
.
Setting this value indicates that an error should not be returned if the queue is empty. Instead, the process should wait until a message is available. Set TPQNOWAIT
to not wait until a message is available. If TPQWAIT
is set in conjunction with TPQGETBYMSGID
or TPQGETBYCORRID
, it indicates that an error should not be returned if no message with the specified message identifier or correlation identifier is present in the queue. Instead, the process should wait until a message meeting the criteria is available. The process is still subject to the caller's transaction timeout, or, when not in transaction mode, the process is still subject to the timeout specified on the TMQUEUE
process by the -t
option.
If a message matching the desired criteria is not immediately available and the configured action resources are exhausted, TPDEQUEUE
fails, TP-STATUS
is set to TPEDIAGNOSTIC
, and DIAGNOSTIC
is set to QMESYSTEM
.
Note that each TPDEQUEUE()
request specifying the TPQWAIT
control parameter requires that a queue manager (TMQUEUE
) action object be available if a message satisfying the condition is not immediately available. If one is not available, the TPDEQUEUE()
request fails. The number of available queue manager actions are specified when a queue space is created or modified. When a waiting dequeue request completes, the associated action object associated is made available for another request.
If TPQPEEK
is set, the specified message is read but not removed from the queue. The TPNOTRAN
flag must be set. It is not possible to read messages enqueued or dequeued within a transaction before the transaction completes.
When a thread is non-destructively dequeuing a message using TPQPEEK
, the message may not be seen by other non-blocking dequeuers for the brief time the system is processing the non-destructive dequeue request. This includes dequeuers using specific selection criteria (such as message identifier and correlation identifier) that are looking for the message currently being non-destructively dequeued.
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 TPQUEQOS-DELIVERY-FLAG PIC S9(9) COMP-5.
05 TPQUEQOS-REPLY-FLAG PIC S9(9) COMP-5.
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.
The following is a list of valid settings in TPQUEDEF-REC
controlling output information from TPDEQUEUE()
. For any of these settings, if the setting is true when TPDEQUEUE()
is called, the associated element in the record is populated with the value provided when the message was queued, and the setting remains true. If the value is not available (that is, no value was provided when the message was queued) or the setting is not true
when TPDEQUEUE()
is called, TPDEQUEUE()
completes with the setting not true
.
If this value is set, the call to TPDEQUEUE()
is successful, and the message was queued with an explicit priority, then the priority 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.
Note that if no priority was explicitly specified when the message was queued, the priority for the message is 50.
If this value is set and the call to TPDEQUEUE()
is successful, the message identifier is stored in MSGID
. The entire 32 bytes of the message identifier value are significant. If TPQNOMSGID
is set, the message identifier is not available.
If this value is set, the call to TPDEQUEUE()
is successful, and the message was queued with a correlation identifier, then the correlation identifier is stored in CORRID
. The entire 32 bytes of the correlation identifier value are significant. Any BEA Tuxedo /Q provided reply to a message has the correlation identifier of the original message. If TPQNOCORRID
is set, the correlation identifier is not available.
If this value is set, the call to TPDEQUEUE()
is successful, and the message was queued with a delivery quality of service, then the flag—TPQQOSDELIVERYDEFAULTPERSIST
, TPQQOSDELIVERYPERSISTENT
, or TPQQOSDELIVERYNONPERSISTENT
—specified by TPQUEQOS-DELIVERY-FLAG
indicates the delivery quality of service. If TPQNODELIVERYQOS
is set, the delivery quality of service is not available.
Note that if no delivery quality of service was explicitly specified when the message was queued, the default delivery policy of the target queue dictates the delivery quality of service for the message.
If this value is set, the call to TPDEQUEUE()
is successful, and the message was queued with a reply quality of service, then the flag—TPQQOSREPLYDEFAULTPERSIST
, TPQQOSREPLYPERSISTENT
, or TPQQOSREPLYNONPERSISTENT
—specified by TPQUEQOS-REPLY-FLAG
indicates the reply quality of service. If TPQNOREPLYQOS
is set, the reply quality of service is not available.
Note that if no reply quality of service was explicitly specified when the message was queued, the default delivery policy of the REPLYQUEUE
queue dictates the delivery quality of service for any reply. The default delivery policy is determined when the reply to a message is enqueued. That is, if the default delivery policy of the reply queue is modified between the time that the original message is enqueued and the reply to the message is enqueued, the policy used is the one in effect when the reply is finally enqueued.
If this value is set, the call to TPDEQUEUE()
is successful, and the message was queued with a reply queue, then the name of the reply queue is 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.
If this value is set, the call to TPDEQUEUE()
is successful, and the message was queued with a failure queue, then the name of the failure queue is 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.
The remaining settings in TPQUEDEF-REC
are set to the following values when TPDEQUEUE()
is called: TPQNOTOP
, TPQNOBEFOREMSGID
, TPQNOTIME_ABS
, TPQNOTIME_REL
, TPQNOEXPTIME_ABS
, TPQNOEXPTIME_REL
, and TPQNOEXPTIME_NONE
.
If the call to TPDEQUEUE()
fails 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, if the call to TPDEQUEUE()
is successful, APPKEY
is set to the 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.
Upon successful completion, TPDEQUEUE()
sets TP-STATUS
to [TPOK
].
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):
Invalid arguments were given (for example, QSPACE-NAME
is SPACES
or settings in TPQUEDEF-REC
are invalid).
Cannot access the QSPACE-NAME
because it is not available (that is, the associated TMQUEUE(5) server is not available), or cannot start a global transaction due to the lack of entries in the Global Transaction Table (GTT).
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 subtype of the dequeued message. Neither DATA-REC
nor TPTYPE-REC
are changed. When the call is made in transaction mode and this error occurs, the transaction is marked abort-only, and the message remains on the queue.
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.
This error code indicates that either a timeout has occurred or TPDEQUEUE()
has been attempted, in spite of the fact that the current transaction is already marked rollback only.
If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout can occur only if both TPBLOCK
and TPTIME
are specified.) In either case, no changes are made to DATA-REC
or TPTYPE-REC
.
If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME
until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, TPACALL()
with TPNOTRAN
, TPNOBLOCK
, and TPNOREPLY
set).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY
state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME
.
A BEA Tuxedo system error has occurred. The exact nature of the error is written to a log file. There is no effect on the queue.
The following diagnostic values are returned during the dequeuing of a message.
The call was not in transaction mode or was made with TPNOTRAN
set and an error occurred trying to start a transaction in which to dequeue the message. This diagnostic is not returned by a queue manager from BEA Tuxedo release 7.1 or later.
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.
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.
When dequeuing a message by message identifier or correlation identifier, the specified message is in use by another transaction. Otherwise all messages currently on the queue are in use by other transactions. This diagnostic is not returned by a queue manager from BEA Tuxedo release 7.1 or later.