Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Programming   |   Topic List   |   Previous   |   Next   |   Contents

   Using the BEA Tuxedo System /Q Component

Three servers are provided with the BEA Tuxedo /Q component. One is the TMS server, TMS_QM, that is the transaction manager server for the BEA Tuxedo /Q resource manager. That is, it manages global transactions for the queued message facility. It must be defined in the GROUPS section of the configuration file.

The other two, TMQUEUE(5) and TMQFORWARD(5), provide services to users. They must be defined in the SERVERS section of the configuration file.

The application can also create its own queue servers, if the functionality of TMQFORWARD does not fully meet the needs of the application. For example, the administrator might want to have a special server to dequeue messages moved to the error queue.

The application can also choose peer-to-peer communication. In this case, the application communicates with other applications, or a client communicates with other clients, by not using any forwarding server.

There must be a server group defined for each queue space the application will use. In addition to the standard requirements of a group name tag and a value for GRPNO (see UBBCONFIG(5) for details). The TMSNAME and OPENINFO parameters need to be set. Here are examples:

TMSNAME=TMS_QM

and

OPENINFO="TUXEDO/QM:<device_name:<queue_space_name>"

TMS_QM is the name for the transaction manager server for BEA Tuxedo /Q. In the OPENINFO parameter, TUXEDO/QM is the literal name for the resource manager as it appears in $TUXDIR/udataobj/RM. The values for <device_name> and <queue_space_name> are instance-specific and must be set to the pathname for the universal device list and the name associated with the queue space, respectively. These values are specified by the BEA Tuxedo administrator using qmadmin(1).

Note: The chronological order of these specifications is not critical. The configuration file can be created either before or after the queue space is defined. The important thing is that the configuration must be defined and queue space and queues created before the facility can be used.

There can be only one queue space per GROUPS section entry. The CLOSEINFO parameter is not used.

The following example is taken from the reference page for TMQUEUE(5).

*GROUPS
TMQUEUEGRP1 GRPNO=1 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device1:myqueuespace"
TMQUEUEGRP2 GRPNO=2 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device2:myqueuespace"

The TMQUEUE(5) reference page gives a full description of the SERVERS section of the configuration file, but there are some points worth additional emphasis here.

TMQUEUE recognizes a -t timeout option when specified after the double dash (- -) in the CLOPT parameter. This timeout value affects only operations begun within the server if it finds that a transaction is not in effect, in other words, either the client called tpenqueue(3c) or tpdequeue(3c) without first calling tpbegin(3c) or it began a transaction and called tpenqueue() or tpdequeue() with the TPNOTRAN flag set to exclude the queue request from the client's transaction. The default for timeout is 30 seconds. If a tpdequeue request is received with the flags set to TPQWAIT, a TPETIME error will be returned if the wait exceeds -t timeout seconds.

Note: ctl is a structure of type TPQCTL used by tpenqueue(3c) and tpdequeue(3c) to pass parameters between the calling process and the system. TPQWAIT is a flag setting available in tpdequeue to indicate that the process wishes to wait for a reply message. The structure is explained in detail in TPQCTL Structure and TPQUEDEF-REC Structure. The COBOL equivalent is the TPQUEDEF-REC record.

There is potential confusion among queue space names, queue names, and service names. The first place you are apt to encounter the confusion is in the specification of the message queue server: TMQUEUE. When specifying this server in the configuration file you can use the -s flag of the CLOPT parameter to name the queue space served by a given instance of the server, which is the same as saying it is a service advertised by the function: TMQUEUE. In an application that uses only one queue space, it is not necessary to specify the CLOPT -s option; it will default to -s TMQUEUE:TMQUEUE. If the application requires more than a single queue space, the names of the queue spaces are included as arguments to the -s option in the SERVERS section entry for the queued message server.

An alternative way of making this specification is to rebuild the message queue server, using buildserver(1), and name the queue spaces with the similar sounding -s option. This has the result of fixing, or hardcoding, the service names in the server executable.

# The following two specifications are equivalent:
 
*SERVERS
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-s myqueuespace:TMQUEUE"
and
 
buildserver -o TMQUEUE -s myqueuespace:TMQUEUE -r TUXEDO/QM \
        -f ${TUXDIR}/lib/TMQUEUE.o
followed by
 ..
 ..
 ..
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-A"

The preceding discussion described the specification of services (that is, queue space names) in the message queue server. This capability can be used to bring about data-dependent routing of queued messages such that the message is queued for processing by a service within a specific group depending on a value in a field of the message buffer. To do this the same queue space name is specified in two different groups and a routing specification is made part of the configuration file to govern the group where the message is queued. Here is an example taken from the TMQUEUE(5) reference page (the queue space name has been changed).

*GROUPS
TMQUEUEGRP1 GRPNO=1 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device1:myqueuespace"
TMQUEUEGRP2 GRPNO=2 TMSNAME=TMS_QM
        OPENINFO="TUXEDO/QM:/dev/device2:myqueuespace"
*SERVERS
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-s ACCOUNTING:TMQUEUE"
TMQUEUE SRVGRP="TMQUEUEGRP2" SRVID=1000 RESTART=Y GRACE=0 \
        CLOPT="-s ACCOUNTING:TMQUEUE"
*SERVICES
ACCOUNTING  ROUTING="MYROUTING"
*ROUTING
MYROUTING  FIELD=ACCOUNT BUFTYPE="FML" \
        RANGES="MIN-60000:TMQUEUEGRP1,60001-MAX:TMQUEUEGRP2"

TMQUEUE supports all of the standard BEA Tuxedo buffer types. If your application needs to add other types, it can be done by copying $TUXDIR/tuxedo/tuxlib/types/tmsypesw.c, adding an entry for your special buffer types, making sure to leave the final line null, and using the revised file as input to a buildserver(1) command. An example of the buildserver command is shown on the TMQUEUE(5) reference page.

You can also use the -s option of the buildserver command to associate additional service names with TMQUEUE as an alternative to specifying them in the server CLOPT parameter (see above).

You can assign a subtype to a buffer using the tpalloc(3c) subtype parameter and later extract the subtype using the tptypes(3c) function. This gives you the ability to assign a type to data without having to create an entirely new user-defined BEA Tuxedo buffer type. This is especially useful for buffers containing character arrays (CARRAY) or strings (STRING).

The third system-supplied server included with the BEA Tuxedo /Q component is TMQFORWARD(5). This is the server that takes messages from specified queues, passes them along to BEA Tuxedo servers via tpcall(3c), and handles associated reply messages. The full description of how the server is defined in the configuration file can be found on the TMQFORWARD(5) reference page, but the topics that follow bring out some points that are worth additional emphasis.

TMQFORWARD is referred to as a server and each instance used by an application must be defined in the SERVERS section of the configuration file, but it has characteristics that set it apart from ordinary servers. For example:

• It is incorrect to specify services for TMQFORWARD.

• A client process cannot post a message for TMQFORWARD as you would expect in a normal request/response relationship.

• TMQFORWARD should not be defined as a member of an MSSQ set.

• TMQFORWARD should never have a reply queue.

An instance of TMQFORWARD is tied to a queue space through the server group with which it is associated, specifically through the third field in the OPENINFO statement for the group. In the topics that follow we will examine other key parameters, especially CLOPT parameters that come after the double dash.

A required parameter is -q queuename,queuename. . . This parameter specifies the queue(s) to be checked by this instance of the server. queuename is a NULL-terminated string of up to 15 characters; it is the same as the name of the application service that will process the message once it has been taken off the queue by TMQFORWARD. It is also the name that a programmer specifies as the second argument of tpenqueue(3c) or tpdequeue(3c) when preparing to call the message queue server, TMQUEUE.

TMQFORWARD does its work within a transaction that it begins and ends. The -t trantime option is available to specify the length of time in seconds before the transaction is timed out. The transaction is begun when TMQFORWARD finds a message on the queue it is checking; it is committed after a reply has been enqueued either to the reply queue or the failure queue, so the transaction encompasses calling the service that processes the message and receiving a reply. The default is 60 seconds.

Once TMQFORWARD is booted it periodically checks the queue to which it is assigned. If it finds the queue empty, it pauses for -i idletime seconds before checking again. If a value is not specified, the default is 30 seconds; a value of 0 says to keep checking the queue constantly, which can be wasteful of CPU resources if the queue is frequently empty.

If the -e option is specified, the server will shut itself down gracefully (and will create a userlog message) when it finds the queue empty. This behavior may be used to your advantage in connection with the threshold command that you can specify for a queue. There is a more complete discussion about the -e option and the threshold command in Creating Queue Spaces and Queues.

When a service request fails after being called by TMQFORWARD, the transaction is rolled back, and the message is put back on the queue for a later retry (up to a limit of retries specified for the queue). The -d option adds the following refinement: if the failed service returns a non-NULL reply, the reply (and its associated tpurcode) are put on a failure queue (if one is associated with the message and the queue exists) and the original request message is deleted. Also with the -d option, if the original request message is to be deleted at the same time as the retry limit configured for the queue is reached, the original request message is put into the error queue.

The rationale behind this option is that rather than blindly retrying, the originating client can be coded to examine the failure message and determine whether further attempts are reasonable. It provides a way of handling a failure that is due to some inherently reasonable condition (for example, a record is not found because the account does not exist).

Customized application buffer types can be added to the type switch and incorporated into TMQFORWARD with the buildserver(1) command. It should be noted, however, that when you customize TMQFORWARD it is an error to specify service names with a -s option.

We have described configuration parameters in terms of UBBCONFIG parameters. However, it should be noted that the specifications in the GROUPS and SERVERS sections can also be added to the TUXCONFIG file of a running application by using tmconfig(1) (see tmconfig, wtmconfig(1)). Of course, the group and the servers will have to be booted once they have been defined.