tpenqueue(3c)

Name

tpenqueue()—Routine to enqueue a message.

Synopsis

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

Description

tpenqueue() stores a message on the queue named by qname in the qspace queue space. A queue space is a collection of queues, one of which must be qname.

If data is non-NULL, it must point to a buffer previously allocated by tpalloc() and len should specify the amount of data in the buffer that should be queued. Note that if data points to a buffer of a type that does not require a length to be specified (for example, an FML fielded buffer), then len is ignored. If data is NULL, len is ignored and a message is queued with no data portion.

The message is queued at the priority defined for qspace unless overridden by a previous call to tpsprio().

If the caller is within a transaction and the TPNOTRAN flag is not set, the message is queued in transaction mode. This has the effect that if tpenqueue() returns successfully and the caller's transaction is committed successfully, then the message is guaranteed to be available subsequent to the transaction completing. 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 removed from the queue (that is, the placing of the message on the queue is also rolled back). It is not possible to enqueue then dequeue the same message within the same transaction.

The message is not queued in transaction mode if either the caller is not in transaction mode, or the TPNOTRAN flag is set. Once tpenqueue() returns successfully, the submitted message is guaranteed to be in the queue. 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 stored on the queue.

The order in which messages are placed on the queue is controlled by the application via ctl data structure as described below; the default queue ordering is set when the queue is created.

The following is a list of valid flags:

Additional information about queuing the message can be specified via ctl data structure. This information includes values to override the default queue ordering placing the message at the top of the queue or before an enqueued message; an absolute or relative time after which a queued message is made available; an absolute or relative time when a message expires and is removed from the queue; the quality of service for delivering the message; the quality of service that any replies to the message should use; a correlation identifier that aids in correlating a reply or failure message with the queued message; the name of a queue to which a reply should be enqueued; and the name of a queue to which any failure message should be enqueued.

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

Control Parameter

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

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

long flags;            /* indicates which of the values  
                        * are set */  
long deq_time;         /* absolute/relative for dequeuing */  
long priority;         /* enqueue priority */  
long exp_time          /* expiration time */  
long delivery_qos      /* delivery quality of service */  
long reply_qos         /* reply quality of service */  
long urcode;           /* user-return code */  
char msgid[32];        /* ID of message before which to queue  
                        * request */  
char corrid[32];       /* correlation identifier used to  
                        * identify the msg */  
char replyqueue[16];   /* queue name for reply message */  
char failurequeue[16]; /* queue name for failure message */

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

Additionally, the urcode element of TPQCTL can be set with a user-return code. This value will be returned to the application that dequeues the message.

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

long flags;         /* indicates which of the values  
                                * are set */  
char msgid[32];                /* ID of enqueued message */  
long diagnostic;               /* indicates reason for failure */

The remaining members of the control structure are not used on input to tpenqueue().

If the call to tpenqueue() 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.

If this 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, tpenqueue() returns -1 and sets tperrno() to indicate the error condition. Otherwise, the message has been successfully queued when tpenqueue() returns.

Errors

Upon failure, tpenqueue() 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 enqueuing of a message:

See Also