Using the ATMI /Q Component

BEA Tuxedo /Q C Language Programming

This topic includes the following sections:

Introduction

This topic deals with the use of the ATMI C language functions for enqueuing and dequeuing messages: tpenqueue(3c) and tpdequeue(3c), plus some ancillary functions.

Prerequisite Knowledge

The BEA Tuxedo programmer coding client or server programs for the queued message facility should be familiar with the C language binding to the BEA Tuxedo ATMI. General guidance on BEA Tuxedo programming is available in Programming BEA Tuxedo ATMI Applications Using C. Detailed pages on all the ATMI functions are in the BEA Tuxedo ATMI C Function Reference.

Where Requests Can Originate

The calls used to place a message on a BEA Tuxedo /Q queue can originate from any client or server process associated with the application. The list includes:

Emphasis on the Default Case

The coverage of BEA Tuxedo /Q programming in this topic primarily reflects the left-hand portion of the figure Queued Service Invocation. In the figure, a client (or a process acting in the role of a client) queues a message by calling tpenqueue(3c) and specifying a queue space made available through a TMQUEUE(5) server. The client later retrieves a reply via a tpdequeue(3c) call to TMQUEUE.

The figure Queued Service Invocation shows the queued message being dequeued by the server TMQFORWARD(5) and sent to an application server for processing (via tpcall(3c)). When a reply to the tpcall() is received, TMQFORWARD enqueues the reply message. Because a major goal of TMQFORWARD is to provide an interface between the queue space and existing application services, it does not require further application coding. For that reason, this topic concentrates on the client-to-queue space side.

A brief example of the use of the queued message facility is distributed with the software and is described in A Sample Application.

Enqueuing Messages

The syntax for tpenqueue() is as follows:

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

When a tpenqueue() call is issued, it tells the system to store a message on the queue identified in qname in the space identified in qspace. The message is in the buffer pointed to by data and has a length of len. By the use of bit settings in flags, the system is informed how the call to tpenqueue() is to be handled. Further information about the handling of the enqueued message and replies is provided in the TMQCTL structure pointed to by ctl.

tpenqueue(3c) Arguments

There are some important arguments to control the operation of tpenqueue(3c). Let's look at some of them.

tpenqueue(): The qspace Argument

qspace identifies a queue space previously created by the administrator. When a server is defined in the SERVERS section of the configuration file, the service names it offers are aliases for the actual queue space name (which is specified as part of the OPENINFO parameter in the GROUPS section). For example, when your application uses the server TMQUEUE, the value pointed at by the qspace argument is the name of a service advertised by TMQUEUE. If no service aliases are defined, the default service is the same as the server name, TMQUEUE. In this case the configuration file might include:

TMQUEUE
        SRVGRP = QUE1  SRVID = 1
        GRACE = 0  RESTART = Y CONV = N
        CLOPT = "-A"

or

	CLOPT = "-s TMQUEUE"

The entry for server group QUE1 has an OPENINFO parameter that specifies the resource manager, the pathname of the device and the queue space name. The qspace argument in a client program then looks like this:

if (tpenqueue("TMQUEUE", "STRING", (TPQCTL *)&qctl,
        (char *)reqstr, 0,0) == -1) {
        Error checking
}

The example shown on the TMQUEUE(5) reference page shows how alias service names can be included when the server is built and specified in the configuration file. The sample program in A Sample Application, also specifies an alias service name.

tpenqueue(): The qname Argument

Within a queue space, when queues are being used to invoke services, message queues are named according to the application services available to process requests. qname is a pointer to such an application service. Otherwise, qname is simply the name of the location where the message is to be stored until it is dequeued by an application (either the same application that enqueued it or another one).

tpenqueue(): The data and len Arguments

data points to a buffer that contains the message to be processed. The buffer must be one that was allocated with a call to tpalloc(3c). len gives the length of the message. Some BEA Tuxedo buffer types (such as FML) do not require that the length of the message be specified; in such cases, the len argument is ignored. data can be NULL; when it is, len is ignored and the message is enqueued with no data portion.

tpenqueue(): The flags Arguments

flags values are used to tell the BEA Tuxedo system how the tpenqueue() call is handled; the following are valid flags:

TPNOTRAN

TPNOBLOCK

TPNOTIME

TPSIGRSTRT

TPQCTL Structure

The third argument to tpenqueue() is a pointer to a structure of type TPQCTL. The TPQCTL structure has members that are used by the application and by the BEA Tuxedo system to pass parameters in both directions between application programs and the queued message facility. The client that calls tpenqueue() sets flags to mark fields the application wants the system to fill in. The structure is also used by tpdequeue(); some of the fields do not come into play until the application calls that function. The complete structure is shown in the following listing.

#define TMQNAMELEN 15 
#define TMMSGIDLEN 32 
#define TMCORRIDLEN 32

struct tpqctl_t {            /* control parameters to queue primitives */ 
     long flags;             /* indicates which of the values are set */ 
     long deq_time;          /* absolute/relative time for dequeuing */ 
     long priority;          /* enqueue priority */ 
     long diagnostic;        /* indicates reason for failure */ 
     char msgid[TMMSGIDLEN];      /* ID of message before which to queue */ 
     char corrid[TMCORRIDLEN];    /* correlation ID used to identify message */ 
     char replyqueue[TMQNAMELEN+1];   /* queue name for reply message */ 
     char failurequeue[TMQNAMELEN+1]; /* queue name for failure message */ 
     CLIENTID cltid;         /* client identifier for originating client */ 
     long urcode;            /* application user-return code */ 
     long appkey;            /* application authentication client key */ 
     long delivery_qos;      /* delivery quality of service */ 
     long reply_qos;         /* reply message quality of service */ 
     long exp_time;          /* expiration time */ 
}; 
typedef struct tpqctl_t TPQCTL;

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

TPNOFLAGS

TPQTOP

TPQBEFOREMSGID

TPQTIME_ABS

TPQTIME_REL

TPQPRIORITY

TPQCORRID

TPQREPLYQ

TPQFAILUREQ

TPQDELIVERYQOS, TPQREPLYQOS

TPQEXPTIME_ABS

TPQEXPTIME_REL

TPQEXPTIME_NONE

Additionally, the urcode field of TPQCTL can be set with a user-return code. This value will be returned to the application that calls tpdequeue(3c) to dequeue the message.

On output from tpenqueue(), the following fields 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 following is a valid bit for the flags parameter controlling output information from tpenqueue(). If this flag is turned on when tpenqueue() is called, the /Q server TMQUEUE(5) populates the associated element in the structure with a message identifier. If this flag is turned off when tpenqueue() is called, TMQUEUE() does not populate the associated element in the structure with a message identifier.

TPQMSGID

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

If the call to tpenqueue() fails and tperrno(5) is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in ctl->diagnostic. The possible values are:

[QMEINVAL]

[QMEBADRMID]

[QMENOTOPEN]

[QMETRAN]

[QMEBADMSGID]

[QMESYSTEM]

[QMEOS]

[QMEABORTED]

[QMEPROTO]

[QMEBADQUEUE]

[QMENOSPACE]

[QMERELEASE]

[QMESHARE]

Overriding the Queue Order

If the administrator, in creating a queue, allows tpenqueue() calls to override the order of messages on the queue, you have two mutually exclusive ways to use that capability. You can specify that the message is to be placed at the top of the queue by setting flags to include TPQTOP or you can specify that it be placed ahead of a specific message by setting flags to include TPQBEFOREMSGID and setting ctl->msgid to the ID of the message you wish to precede. This assumes that you saved the message-ID from a previous call in order to be able to use it here. Your administrator must tell you what the queue supports; it can be created to allow either or both of these overrides, or to allow neither.

Overriding the Queue Priority

You can set a value in ctl->priority to specify the priority of the message. The value must be in the range 1 to 100; the higher the number the higher the priority. If priority was not one of the queue ordering parameters, setting a priority here has no effect on the dequeuing order, however the priority value is retained so that the value can be inspected when the message is dequeued.

Setting a Message Availability Time

You can specify in deq_time either an absolute time or a time relative to the completion of the enqueuing operation for the message to be made available. You set flags to include either TPQTIME_ABS or TPQTIME_REL to indicate how the value should be treated. A queue may be created with time as a queue ordering criterion, in which case the messages are ordered by the message availability time.

BEA Tuxedo /Q provides a function, gp_mktime(3c), that is used to convert a date and time provided in a tm structure to the number of seconds since January 1, 1970. The time(2) and mktime(3C) functions may also be used instead of gp_mktime(3c). The value is returned in time_t, a typedef'd long. To set an absolute time for the message to be dequeued (we are using 12:00 noon, December 9, 2001), do the following.

If you want to specify a relative time for dequeuing, for example, nnn seconds after the completion of the enqueuing operation, place the number of seconds in deq_time and set flags to include TPQTIME_REL.

tpenqueue() and Transactions

If a caller of tpenqueue() is in transaction mode and TPNOTRAN is not set, then the enqueuing is done within the caller's transaction. The caller knows for certain from the success or failure of tpenqueue() whether the message was enqueued or not. If the call succeeds, the message is guaranteed to be on the queue. If the call fails, the transaction is rolled back, including the part where the message was placed on the queue.

If a caller of tpenqueue() is not in transaction mode or if TPNOTRAN is set, the message is enqueued outside of the caller's transaction. If the call to tpenqueue() returns success, the message is guaranteed to be on the queue. If the call to tpenqueue() fails with a communication error or with a timeout, the caller is left in doubt about whether the failure occurred before or after the message was enqueued.

Note that specifying TPNOTRAN while the caller is not in transaction mode has no meaning.

Dequeuing Messages

The syntax for tpdequeue() is as follows:

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

When this call is issued it tells the system to dequeue a message from the qname queue in the queue space named qspace. The message is placed in a buffer (originally allocated by tpalloc(3c)) at the address pointed to by *data. len points to the length of the data. If len is 0 on return from tpdequeue(), the message had no data portion. By the use of bit settings in flags, the system is informed how the call to tpdequeue() is to be handled. The TPQCTL structure pointed to by ctl carries further information about how the call should be handled.

tpdequeue(3c) Arguments

There are some important arguments to control the operation of tpdequeue(3c). Let's look at some of them.

tpdequeue(): The qspace Argument

qspace identifies a queue space previously created by the administrator. When the TMQUEUE server is defined in the SERVERS section of the configuration file, the service names it offers are aliases for the actual queue space name (which is specified as part of the OPENINFO parameter in the GROUPS section). For example, when your application uses the server TMQUEUE, the value pointed at by the qspace argument is the name of a service advertised by TMQUEUE. If no service aliases are defined, the default service is the same as the server name, TMQUEUE. In this case the configuration file may include:

TMQUEUE
        SRVGRP = QUE1  SRVID = 1
        GRACE = 0  RESTART = Y CONV = N
        CLOPT = "-A"
or
        CLOPT = "-s TMQUEUE"

The entry for server group QUE1 has an OPENINFO parameter that specifies the resource manager, the pathname of the device and the queue space name. The qspace argument in a client program then looks like this:

if (tpdequeue("TMQUEUE", "REPLYQ", (TPQCTL *)&qctl,
        (char **)&reqstr, &len,TPNOTIME) == -1) {
        Error checking
}

The example shown on the TMQUEUE(5) reference page shows how alias service names can be included when the server is built and specified in the configuration file. The sample program in A Sample Application, also specifies an alias service/queue space name.

tpdequeue(): The qname Argument

Queue names in a queue space must be agreed upon by the applications that will access the queue space. This is especially important for reply queues. If qname refers to a reply queue, the administrator creates it (and often an error queue) in the same manner that he or she creates any other queue. qname is a pointer to the name of the queue from which to retrieve the message or reply.

tpdequeue(): The data and len Arguments

These arguments have slightly different meanings than their counterparts in tpenqueue(). *data points to the address of a buffer where the system is to place the message being dequeued. When tpdequeue() is called, it is an error for its value to be NULL.

When tpdequeue() returns, len points to a value of type long that carries information about the length of the data retrieved. If it is 0, it means that the reply had no data portion. This can be a legitimate and successful reply in some applications; receiving even a 0 length reply can be used to show successful processing of the enqueued request. If you wish to know whether the buffer has changed from before the call to tpdequeue(), save the length prior to the call to tpdequeue() and compare it to len after the call completes.

tpdequeue(): The flags Arguments

flags values are used to tell the BEA Tuxedo system how the tpdequeue() call is handled; the following are valid flags:

TPNOTRAN

TPNOBLOCK

TPNOTIME

TPNOCHANGE

TPSIGRSTRT

TPQCTL Structure

The third argument to tpdequeue() is a pointer to a structure of type TPQCTL. The TPQCTL structure has members that are used by the application and by the BEA Tuxedo system to pass parameters in both directions between application programs and the queued message facility. The client that calls tpdequeue() sets flags to mark fields for which the system should supply values. As described earlier, the structure is also used by tpenqueue(); some of the members apply only to that function. The entire structure is shown in The tpqctl_t Structure.

As input to tpdequeue(), the following fields 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 are valid flags on input to tpdequeue():

TPNOFLAGS

TPQGETBYMSGID

TPQGETBYCORRID

TPQWAIT

TPQPEEK

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 field in the structure (see The tpqctl_t 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.

TPQPRIORITY

TPQMSGID

TPQCORRID

TPQDELIVERYQOS

TPQREPLYQOS

TPQREPLYQ

TPQFAILUREQ

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(5) is set to TPEDIAGNOSTIC, a value indicating the reason for failure is returned in ctl->diagnostic. The valid codes for ctl->diagnostic include those for tpenqueue() described in TPQCTL Structure (except for QMENOSPACE and QMERELEASE) and the following additional codes.

[QMENOMSG]

[QMEINUSE]

Using TPQWAIT

When tpdequeue() is called with flags (of the TPQCTL structure) set to include TPQWAIT, if a message is not immediately available, the TMQUEUE server waits for the arrival, on the queue, of a message that matches the tpdequeue() request before tpdequeue() returns control to the caller. The TMQUEUE process sets the waiting request aside and processes requests from other processes while waiting to satisfy the first request. If TPQGETBYMSGID and/or TPQGETBYCORRID are also specified, the server waits until a message with the indicated message identifier and/or correlation identifier becomes available on the queue. If neither of these flags is set, the server waits until any message is put onto the queue. The amount of time it waits is controlled by the caller's transaction timeout, if the call is in transaction mode, or by the -t option in the CLOPT parameter of the TMQUEUE server, if the call is not in transaction mode.

The TMQUEUE server can handle a number of waiting tpdequeue() requests at the same time, as long as action resources are available to handle the request. If there are not enough action resources configured for the queue space, tpdequeue() fails. If this happens on your system, increase the number of action resources for the queue space.

Error Handling When Using TMQFORWARD Services

In considering how best to handle errors when dequeuing it is helpful to differentiate between two types of errors:

By default, if a message is dequeued within a transaction and the transaction is rolled back, then (if the retry parameter is greater than 0) the message ends up back on the queue and can be dequeued and executed again. It may be desirable to delay for a short period before retrying to dequeue and execute the message, allowing the transient problem to clear (for example, allowing for locks in a database to be released by another transaction). Normally, a limit on the number of retries is also useful to ensure that an application flaw doesn't cause significant waste of resources. When a queue is configured by the administrator, both a retry count and a delay period (in seconds) can be specified. A retry count of 0 implies that no retries are done. After the retry count is reached, the message is moved to an error queue that is configured by the administrator for the queue space. If the error queue is not configured, then messages that have reached the retry count are simply deleted. Messages on the error queue must be handled by the administrator who must work out a way of notifying the originator that meets the requirements of the application. The message handling method chosen should be mostly transparent to the originating program that put the message on the queue. There is a virtual guarantee that once a message is successfully enqueued it will be processed according to the parameters of tpenqueue() and the attributes of the queue. Notification that a message has been moved to the error queue should be a rare occurrence in a system that has properly tuned its queue parameters.

A failure queue (normally, different from the queue space error queue) may be associated with each queued message. This queue is specified on the enqueuing call as the place to put any failure messages. The failure message for a particular request can be identified by an application-generated correlation identifier that is associated with the message when it is enqueued.

The default behavior of retrying until success (or a predefined limit) is quite appropriate when the failure is caused by a transient problem that is later resolved, allowing the message to be handled appropriately.

There are cases where the problem is not transient. For example, the queued message may request operating on an account that does not exist (and the application is such that it won't come into existence within a reasonable time period if at all). In this case, it is desirable not to waste any resources by trying again. If the application programmer or administrator determines that failures for a particular operation are never transient, then it is simply a matter of setting the retry count to zero, although this will require a mechanism to constantly clear the queue space error queue of these messages (for example, a background client that reads the queue periodically). More likely, it is the case that some problems will be transient (for example, database lock contention) and some problems will be permanent (for example, the account doesn't exist) for the same service.

In the case that the message is processed (dequeued and passed to the application via a tpcall()) by TMQFORWARD, there is no mechanism in the information returned by tpcall() to indicate whether a TPESVCFAIL error is caused by a transient or permanent problem.

As in the case where the application is handling the dequeuing, a simple solution is to return success for the service, that is, tpreturn with TPSUCCESS, even though the operation failed. This allows the transaction to be committed and the message removed from the queue. If reply messages are being used, the information in the buffer returned from the service can indicate that the operation failed and the message will be enqueued on the reply queue. The rcode argument of tpreturn can also be used to return application specific information.

In the case where the service fails and the transaction must be rolled back, it is not clear whether or not TMQFORWARD should execute a second transaction to remove the message from the queue without further processing. By default, TMQFORWARD will not delete a message for a service that fails. TMQFORWARD's transaction is rolled back and the message is restored to the queue. A command-line option may be specified for TMQFORWARD that indicates that a message should be deleted from the queue if the service fails and a reply message is sent back with length greater than 0. The message is deleted in a second transaction. The queue must be configured with a delay time and retry count for this to work. If the message is associated with a failure queue, the reply data will be enqueued to the failure queue in the same transaction as the one in which the message is deleted from the queue.

Procedure for Dequeuing Replies from Services Invoked Through TMQFORWARD

If your application expects to receive replies to queued messages, the following is a procedure you may want to follow:

Sequential Processing of Messages

Sequential processing of messages can be achieved by having one service enqueue a message for the next service in the chain before its transaction is committed. The originating process can track the progress of the sequence with a series of tpdequeue() calls to the reply_queue, if each member uses the same correlation-ID and returns a 0 length reply.

Alternatively, word of the successful completion of the entire sequence can be returned to the originator by using unsolicited notification. To make sure that the last transaction in the sequence ended with a tpcommit, a job step can be added that calls tpnotify using the client identifier that is carried in the TPQCTL structure returned from tpdequeue() or in the TPSVCINFO structure passed to the service. The originating client must have called tpsetunsol to name the unsolicited message handler being used.

Using Queues for Peer-to-Peer Communication

In all of the foregoing discussion of enqueuing and dequeuing messages there has been an implicit assumption that queues were being used as an alternative form of request/response processing. A message does not have to be a service request. The queued message facility can transfer data from one process to another as effectively as a service request. This style of communication between applications or clients is called peer-to-peer communication.

If it suits your application to use BEA Tuxedo /Q for this purpose, have the administrator create a separate queue and code your own receiving program for dequeuing messages from that queue.