![]() |
![]() |
|
|
TPDEQUEUE(3cbl)
Name
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() 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 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.
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).
The following is a list of valid settings in TPQUEDEF-REC controlling input information for TPDEQUEUE().
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.
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.
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):
Diagnostics
The following diagnostic values are returned during the dequeuing of a message.
See Also
qmadmin(1), TPENQUEUE(3cbl), TMQUEUE(5)
![]() |
![]() |
![]() |
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|