Section 3(cbl) - COBOL Functions

e-docs > Tuxedo > ATMI COBOL Function Reference > Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

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.

TPNOTRAN

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.

TPTRAN

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.

TPNOBLOCK

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.

TPBLOCK

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.

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.

TPNOCHANGE

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.

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.

TPSIGRSTRT

If a signal interrupts any underlying system calls, the interrupted system call is reissued. Either TPNOSIGRSTRT or TPSIGRSTRT must be set.

TPNOSIGRSTRT

If a signal interrupts any underlying system calls, 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 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().

TPQGETNEXT

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.

TPQGETBYMSGID

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.

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.

TPQWAIT

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.

TPQPEEK

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.

TPQPRIORITY

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.

TPQMSGID

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.

TPQCORRID

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.

TPQDELIVERYQOS

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.

TPQREPLYQOS

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.

TPQREPLYQ

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.

TPQFAILUREQ

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.

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 (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).

[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 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.

[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]

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).