Section 3c - C Functions

ATMI C Function Reference

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:

TPNOTRAN

If the caller is in transaction mode and this flag is set, the message is not dequeued within the caller's transaction. 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. If this flag is set and a blocking condition exists such as the internal buffers into which the message is transferred are full, the call fails and tperrno is set to TPEBLOCK. If this flag is set and a blocking condition exists because the target queue is opened exclusively by another application, the call fails, tperrno is set to TPEDIAGNOSTIC, and the diagnostic field of the TPQCTL structure is set to QMESHARE. In the latter case, the other application, which is based on a BEA product other than the BEA Tuxedo ATMI system, opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI).

When TPNOBLOCK is not 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 option in flags (of the TPQCTL structure) is specified.

TPNOTIME

Setting 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 subtype of the dequeued message must match the type and subtype of the buffer pointed to by *data.

TPSIGRSTRT

Setting this flag indicates that any underlying system calls that are interrupted by a signal should be reissued. When this flag is not set and a signal interrupts a system call, the call fails and sets tperrno to TPGOTSIG.

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

TPNOFLAGS

No flags are set. No information is taken from the control structure.

TPQGETBYMSGID

Setting this flag requests that the message with the message identifier specified by ctl—>msgid be dequeued. The message identifier may be acquired by a prior call to tpenqueue(3c). Note that a 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 specified by ctl—>msgid must be completely initialized (for example, padded with NULL characters).

TPQGETBYCORRID

Setting this flag requests that the message with the correlation identifier specified by ctl—>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 specified by ctl—>corrid must be completely initialized (for example, padded with NULL characters).

TPQWAIT

Setting this flag indicates that an error should not be returned if the queue is empty. Instead, the process should 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 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 returns -1, tperrno is set to TPEDIAGNOSTIC, and the diagnostic field of the TPQCTL structure 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 an action object 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 this flag is set, the specified message is read but is not removed from the queue. This flag implies the TPNOTRAN flag has been set for the tpdequeue() operation. That is, non-destructive dequeuing is non-transactional. Note that 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 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 or the bit is not set when tpdequeue() is called, tpdequeue() completes with the flag turned off.

TPQPRIORITY

If this flag is set, the call to tpdequeue() is successful, and the message was queued with an explicit priority, then the priority 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). For queues not ordered by priority, the value is informational.

If no priority was explicitly specified when the message was queued and the call to tpdequeue() is successful, the priority for the message is 50.

TPQMSGID

If this flag is set and the call to tpdequeue() is successful, the message identifier is stored in ctl—>msgid. The entire 32 bytes of the message identifier value are significant.

TPQCORRID

If this flag is set, the call to tpdequeue() is successful, and the message was queued with a correlation identifier, then the correlation identifier is stored in ctl—>corrid. The entire 32 bytes of the correlation identifier value are significant. Any BEA Tuxedo ATMI /Q provided reply to a message has the correlation identifier of the original request message.

TPQDELIVERYQOS

If this flag is set, the call to tpdequeue() is successful, and the message was queued with a delivery quality of service, then the flag—TPQQOSDEFAULTPERSIST, TPQQOSPERSISTENT, or TPQQOSNONPERSISTENT—is stored in ctl->delivery_qos. 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 flag is set, the call to tpdequeue() is successful, and the message was queued with a reply quality of service, then the flag—TPQQOSDEFAULTPERSIST, TPQQOSPERSISTENT, or TPQQOSNONPERSISTENT—is stored in ctl->reply_qos. If no reply quality of service was explicitly specified when the message was queued, the default delivery policy of the ctl->replyqueue queue dictates the delivery quality of service for any reply.

Note that 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 flag 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 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 this flag 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 ctl—>failurequeue. Any failure message should go to the named failure queue within the same queue space as the request message.

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

[TPEINVAL]

Invalid arguments were given (for example, qname is NULL, data does not point to space allocated with tpalloc() or flags are invalid).

[TPENOENT]

Cannot access the qspace 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 type and subtype of the dequeued message are not known to the caller; or, TPNOCHANGE was set in flags and the type and subtype of *data do not match the type and subtype of the dequeued message. In either case, *data, its contents, and *len are not 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.

[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 cannot occur if TPNOBLOCK and/or TPNOTIME is specified.) In either case, no changes are made to *data, its contents, or *len.

If a transaction timeout has occurred, then, with one exception, any attempts to perform further conversational work, 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.

[TPEBLOCK]

A blocking condition exists and TPNOBLOCK was specified.

[TPGOTSIG]

A signal was received and TPSIGRSTRT was not specified.

[TPEPROTO]

tpdequeue() was called improperly. There is no effect on the queue or the transaction.

[TPESYSTEM]

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.

[TPEOS]

An operating system error has occurred. There is no effect on the queue.

[TPEDIAGNOSTIC]

Dequeuing a message from the specified queue failed. The reason for failure can be determined by the diagnostic value returned via ctl structure.

Diagnostic

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

[QMEINVAL]

An invalid flag value was specified.

[QMEBADRMID]

An invalid resource manager identifier was specified.

[QMENOTOPEN]

The resource manager is not currently open.

[QMETRAN]

The call was not in transaction mode or was made with the TPNOTRAN flag set and an error occurred trying to start a transaction in which to dequeue the message. This diagnostic is not returned by queue managers from BEA Tuxedo release 7.1 or later.

[QMEBADMSGID]

An invalid message identifier was specified for dequeuing.

[QMESYSTEM]

A system error has occurred. The exact nature of the error is written to a log file.

[QMEOS]

An operating system error has occurred.

[QMEABORTED]

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.

[QMEPROTO]

A dequeue was done when the transaction state was not active.

[QMEBADQUEUE]

An invalid or deleted queue name was specified.

[QMENOMSG]

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.

[QMEINUSE]

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 queue managers from BEA Tuxedo release 7.1 or later.

[QMESHARE]

When dequeuing a message from a specified queue, the specified queue is opened exclusively by another application. The other application is one based on a BEA product other than the BEA Tuxedo system that opened the queue for exclusive read and/or write using the Queuing Services API (QSAPI).