tpenqueue(3)

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.

When the message is intended for a BEA TUXEDO system server, the qname matches the name of a service provided by a server. The system provided server, TMQFORWARD(5), provides a default mechanism for dequeuing messages from the queue and forwarding them to servers that provide a service matching the queue name. If the originator expected a reply, then the reply to the forwarded service request is stored on the originator's (stable) queue. The originator will dequeue the reply message at a subsequent time. Queues can also be used for a reliable message transfer mechanism between any pair of BEA TUXEDO system processes (clients and/or servers). In this case, the queue name does not match a service name but some agreed upon title for transferring the message.

If data is non-NULL, it must point to a buffer previously allocated by tpalloc(3) 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(3).

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 deleted 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. In this case, the queued message is stored on the queue in a separate transaction. Once tpenqueue() returns successfully, the submitted message is guaranteed to be available. 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 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.

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 queued 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 queuing the message. If message queuing fails, the caller's transaction is not affected.
TPNOBLOCK: The message is not enqueued 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).
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.
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 tpenqueue() fails and tperrno is set to TPGOTSIG.

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

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

TPNOFLAGS: No flags or values are set. No information is taken from the control structure.
TPQTOP: Setting this flag bit indicates that the queue ordering be overridden and the message placed at the top of the queue. This request may not be granted depending on whether or not the queue was configured to allow overriding the queue ordering. TPQTOP and TPQBEFOREMSGID are mutually exclusive flags.
TPQBEFOREMSGID: Setting this flag bit indicates that the queue ordering be overridden and the message placed in the queue before the message identified by ctl->msgid. This request may not be granted depending on whether or not the queue was configured to allow overriding the queue ordering. TPQTOP and TPQBEFOREMSGID are mutually exclusive flags.
TPQTIME_ABS: If set, the message is made available after the time specified by ctl->deq_time. The deq_time is an absolute time value as generated by time() or mktime() (the number of seconds since 00:00:00 UTC, January 1, 1970). TPQTIME_ABS and TPQTIME_REL are mutually exclusive flags.
TPQTIME_REL: If set, the message is made available after a time relative to the completion of the queuing transaction. ctl->deq_time specifies the number of seconds to delay after the transaction completes before the submitted message should be available. TPQTIME_ABS and TPQTIME_REL are mutually exclusive flags.
TPQPRIORITY: If set, the priority at which the message should be enqueued is stored in ctl->priority. The priority must be in the range 1 to 100, inclusive. 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).
TPQCORRID: If set, the correlation identifier value specified in \%ctl->corrid is available when a message is dequeued with tpdequeue(3). This identifier accompanies any reply or failure message that is queued such that an application can correlate a reply with a particular request. The entire value should be initialized (e.g., padded with null characters) such that the value can be matched at a later time.

TPQREPLYQ

If set, a reply queue named in ctl->replyqueue is associated with the queued message. Any reply to the message will be queued to the named queue within the same queue space as the request message. This string must be NULL terminated (maximum 15 characters in length).

TPQFAILUREQ

If set, a failure queue named in ctl->failurequeue is associated with the queued message. If a failure occurs when the enqueued message is subsequently dequeued, a failure message will go to the named queue within the same queue space as the original request message. This string must be NULL terminated (maximum 15 characters in length).

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

Following is a list of valid bits for the flags parameter controlling output information from tpenqueue(). If the flag bit is turned on when tpenqueue() 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 tpenqueue() completes.

TPQMSGID: If set and the call to tpenqueue() was successful, the message identifier will be stored in ctl->msgid.

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.

tpenqueue(3)

Name

Synopsis

Description

Control Parameter

Return Values

Errors

Diagnostic

See Also