tpdequeue(3)

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() dequeues 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 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 the ctl parameter. ctl flags 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 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(3). 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 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 in TPNOTRAN mode 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 the TPNOTRAN flag 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.

Following is a list of valid flags.

TPNOTRAN: If the caller is in transaction mode and this flag is set, then the message is not dequeued within the same transaction as the caller. A caller in transaction mode that sets this flag is still subject to the transaction timeout (and no other) when dequeuing the message. If message dequeuing fails, the caller's transaction is not affected.
TPNOBLOCK: The message is not dequeued if a blocking condition exists (for example, the internal buffers into which the message is transferred are full). If such a condition occurs, the call fails and tperrno is set to TPEBLOCK. When TPNOBLOCK is not specified 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 option is specified.
TPNOTIME: This flag signifies that the caller is willing to block indefinitely and wants to be immune to blocking timeouts. Transaction timeouts may still occur.
TPNOCHANGE: When this flag is set, the type of the buffer pointed to by *data is not allowed to change. By default, if a buffer is received that differs in type from the buffer pointed to by *data, then *data's buffer type changes to the received buffer's type so long as the receiver recognizes the incoming buffer type. That is, the type and sub-type of the dequeued message must match the type and sub-type of the buffer pointed to by *data.
TPSIGRSTRT: If a signal interrupts any underlying system calls, then the interrupted system call is re-issued. When TPSIGRSTRT is not specified and a signal interrupts a system call, then tpdequeue() fails and tperrno is set to TPGOTSIG.

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

Following is a list of valid bits for the flags parameter controlling input information for tpdequeue().

TPNOFLAGS: No flags are set. No information is taken from the control structure.
TPQGETBYMSGID: If set, it requests that the message identified by ctl->msgid be dequeued. The message identifier would be one that was returned by a prior call to tpenqueue(3). 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. This option cannot be used with the TPQWAIT option.
TPQGETBYCORRID: If set, it requests that the message with the correlation identifier specified by ctl->corrid be dequeued. The correlation identifier would be one that the application specified when enqueuing the message with tpenqueue(). This option cannot be used with the TPQWAIT option.
TPQWAIT: If set, it indicates that an error should not be returned if the queue is empty. Instead, the process should block until a message is available.

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 */
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 */

Following is a list of valid bits for the flags parameter controlling output information from tpdequeue(). If the flag bit is turned on when tpdequeue() is called, then the associated element in the structure is populated if available and the bit remains set. If the value is not available, the flag bit will be turned off after tpdequeue() completes.

TPQPRIORITY: If set and the value is available, the priority at which the message was queued is stored in ctl->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).
TPQMSGID: If set and the call to tpdequeue() was successful, the message identifier will be stored in ctl->msgid.
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 ctl->corrid. Any reply to a queue must have this correlation identifier.
TPQREPLYQ: If set and the message is associated with a reply queue, the value will be stored in ctl->replyqueue. Any reply to the message should go to the named reply queue within the same queue space as the request message.
TPQFAILUREQ: If set and the message is associated with a failure queue, the value will be stored in ctl->failurequeue. Any failure message should go to the named failure queue within the same queue space as the request message.

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, ctl->appkey is set to 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.

tpdequeue(3)

Name

Synopsis

Description

Control Parameter

Return Values

Errors

Diagnostic

See Also