tpdequeue(3c)

Name

tpdequeue()—Routine to dequeue a message from a queue.

Synopsis

#include <atmi.h> 
int tpdequeue(char *qspace, char *qname, TPQCTL *ctl, char **data, long *len, long flags)

Description

tpdequeue() takes a message for processing from the queue named by qname in the qspace 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 or correlation identifier using the ctl parameter. ctl flags 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 ctl parameter 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 parameter.

data is the address of a pointer to the buffer into which a message is read, and len points to the length of that message. *data must point to a buffer originally allocated by tpalloc(). If a message is larger than the buffer passed to tpdequeue, the buffer is increased in size to accommodate the message. To determine whether a message buffer changed in size, compare its (total) size before tpdequeue() was issued with *len. If *len is larger, then the buffer has grown; otherwise, the buffer has not changed size. Note that *data may change for reasons other than the buffer's size increased. If *len is 0 upon return, then the message dequeued has no data portion and neither *data nor the buffer it points to were modified. It is an error for *data or len to be NULL.

The message is dequeued in transaction mode if the caller is in transaction mode and the TPNOTRAN flag is not 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 the TPNOTRAN flag 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 flags:

If tpdequeue() returns successfully, the application can retrieve additional information about the message using the ctl data 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.

In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpdequeue().

Control Parameter

The TPQCTL structure is used by the application program to pass and retrieve parameters associated with dequeuing the message. The flags element of TPQCTL is used to indicate what other elements in the structure are valid.

On input to tpdequeue(), the following elements may be set in the TPQCTL structure:

long flags;            /* indicates which of the values
                        * are set */
char msgid[32];        /* ID of message to dequeue */
char corrid[32];       /* correlation identifier of
                        * message to dequeue */

The following is a list of valid bits for the flags parameter controlling input information for tpdequeue():

On output from tpdequeue(), the following elements may be set in the TPQCTL structure:

long flags;            /* indicates which of the values 
                        * should be set */
 
long priority;         /* enqueue priority */ 
char msgid[32];        /* ID of message dequeued */ 
char corrid[32];       /* correlation identifier used to
                        * identify the message */
long delivery_qos;     /* delivery quality of service */
long reply_qos;        /* reply message quality of service */
char replyqueue[16];   /* queue name for reply */ 
char failurequeue[16]; /* queue name for failure */ 
long diagnostic;       /* reason for failure */ 
long appkey;           /* application authentication client 
                        * key */ 
long urcode;           /* user-return code */ 
CLIENTID cltid;        /* client identifier for originating 
                        * client */

The following is a list of valid bits for the flags parameter controlling output information from tpdequeue(). For any of these bits, if the flag bit is turned on when tpdequeue() is called, the associated element in the structure is populated with the value provided when the message was queued, and the bit remains set. If a value is not available (that is, no value was provided when the message was queued) or the bit is not set when tpdequeue() is called, tpdequeue() completes with the flag turned off.

The following remaining bits for the flags parameter are cleared (set to zero) when tpdequeue() is called: TPQTOP, TPQBEFOREMSGID, TPQTIME_ABS, TPQTIME_REL, TPQEXPTIME_ABS, TPQEXPTIME_REL, and TPQEXPTIME_NONE. These bits are valid bits for the flags parameter controlling input information for tpenqueue().

If the call to tpdequeue() failed and tperrno() is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in ctl—>diagnostic. The possible values are defined below in the Diagnostics section.

Additionally on output, if the call to tpdequeue() is successful, ctl—>appkey is set to the application authentication key, ctl—>cltid is set to the identifier for the client originating the request, and ctl—>urcode is set to the user-return code value that was set when the message was enqueued.

If the ctl parameter is NULL, the input flags are considered to be TPNOFLAGS, and no output information is made available to the application program.

Return Values

Upon failure, tpdequeue() returns -1 and sets tperrno() to indicate the error condition.

Errors

Upon failure, tpdequeue() sets tperrno() to one of the following values. (Unless otherwise noted, failure does not affect the caller's transaction, if one exists.)

Diagnostic

The following diagnostic values are returned during the dequeuing of a message:

See Also