---

TMQUEUE(5)

Name

TMQUEUE-BEA TUXEDO system Message Queue Manager

Synopsis

TMQUEUE 
SRVGRP="identifier" 
SRVID="number" CLOPT=" [ -A ][servopts options ] -- [-t trantime]"

Description

The message queue manager is a BEA TUXEDO system-supplied server that enqueues and dequeues messages on behalf of programs calling tpenqueue(3) and tpdequeue(3), respectively. The application administrator enables message enqueuing and dequeuing for the application by specifying this server as an application server in the SERVERS section.

The location, server group, server identifier and other generic server related parameters are associated with the server using the already defined configuration file mechanisms for servers. The following is a list of additional command line options that are available for customization.

-t trantime

is used to indicate the transaction timeout value used on tpbegin(3) for enqueue and dequeue requests not in transaction mode (e.g., tpenqueue(3) or tpdequeue(3) are called when the caller is not in transaction mode or with the TPNOTRAN flag). This value also has an impact on dequeue requests with the TPQWAIT option since the transaction will timeout and an error will be sent back to the requester based on this value. If not specified, the default is 30 seconds.

A TMQUEUE server is booted as part of an application to facilitate application access to its associated queue space; a queue space is a collection of queues.

Any configuration condition that prevents the TMQUEUE from enqueuing or dequeuing messages will cause the TMQUEUE to fail at boot time. The SRVGRP must have TMSNAME set to TMS_QM, and must have OPENINFO set to indicate the associated device and queue space name.

Queue Name for Message Submission

The tpenqueue() and tpdequeue() functions take a queue space name as their first argument. This name must be the name of a service advertised by TMQUEUE. By default, TMQUEUE only offers the service "TMQUEUE". While this may be sufficient for applications with only a single queue space, applications with multiple queue spaces may need to have different queue space names. Additionally, applications may wish to provide more descriptive service names that match the queue space names. Advertising additional service names can be done using the standard server command line option, -s, as shown below in EXAMPLES. An alternative is to hard-code the service when generating a custom TMQUEUE program, as discussed in the following section.

While these methods (the server command line option or a customized server) may be used for static routing of messages to a queue space, dynamic routing may be accomplished using data dependent routing. In this case, each TMQUEUE server would advertise the same service name(s) but a ROUTING field in the configuration file would be used to specify routing criteria based on the application data in the queued message. The routing function returns a GROUP based on the service name and application typed buffer data, which is used to direct the message to the service at the specified group (note that there can be only one queue space per GROUP, based on the OPENINFO string).

Handling Application Buffer Types

As delivered, TMQUEUE handles the standard buffer types provided with BEA TUXEDO system. If additional application buffer types are needed, then a customized version of TMQUEUE needs to be built using buildserver(1).

If your application uses shared libraries, it is not necessary to go through this compile and link process. See the description in the Buffers chapter of the BEA TUXEDO Administrator's Guide.

The customization described in buildserver can also be used to hard-code service names for the server.

The files included by the caller should include only the application buffer type switch and any required supporting routines. buildserver is used to combine the server object file, $TUXDIR/lib/TMQUEUE.o, with the application type switch file(s), and link it with the needed BEA TUXEDO system libraries. The following example provides a sample for further discussion.

buildserver -v -o TMQUEUE -s qspacename:TMQUEUE -r TUXEDO/QM \e -f ${TUXDIR}/lib/TMQUEUE.o -f apptypsw.o

The buildserver options are as follows:

-v

specifies that buildserver should work in verbose mode. In particular, it writes the cc command to its standard output.

-o name

specifies the file name of the output load module. The name specified here must also be specified in the SERVERS section of the configuration file. It is recommended that TMQUEUE be used for consistency.

-s qspacename,qspacename :TMQUEUE

specifies the names of services that can be advertised when the server is booted (see servopts(5)). For this server, they will be used as the aliases for the queue space name to which requests may be submitted. Spaces are not allowed between commas. The function name, TMQUEUE, is preceded by a colon. The -s option may appear several times.

-r TUXEDO/QM

specifies the resource manager associated with this server. The value TUXEDO/QM appears in the resource manager table located in $TUXDIR/udataobj/RM and includes the library for the BEA TUXEDO system queue manager.

-f $TUXDIR/lib/TMQUEUE.o

specifies the object file that contains the TMQUEUE service and should be specified as the first argument to the -f option.

-f firstfiles

specifies one or more user files to be included in the compilation and/or link edit phases of buildserver. Source files are compiled using the either the cc command or the compilation command specified through the CC environment variable. These files must be specified after including the TMQUEUE.o object file. If more than one file is specified, file names must be separated by white space and the entire list must be enclosed in quotation marks. This option can be specified multiple times.

Portability

TMQUEUE is supported as a BEA TUXEDO system-supplied server on UNIX operating systems.

Interoperability

TMQUEUE may be run in an interoperating application, but it must run on a Release 4.2 or later node.

Examples

*GROUPS 
# For NT/Netware, :myqueue becomes ;myqueue 
TMQUEUEGRP1 GRPNO=1 TMSNAME=TMS_QM
   OPENINFO="TUXEDO/QM:/dev/device1:myqueue" 
# For NT/Netware, :myqueue becomes ;myqueue 
TMQUEUEGRP2 GRPNO=2 TMSNAME=TMS_QM
   OPENINFO="TUXEDO/QM:/dev/device2:myqueue"
 
*SERVERS 
# The queue space name, myqueue, is aliased as ACCOUNTING in this example 
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" 
TMQFORWARD SRVGRP="TMQUEUEGRP1" SRVID=1001 RESTART=Y GRACE=0 REPLYQ=N 
    CLOPT=" -- -qservice1" 
TMQFORWARD SRVGRP="TMQUEUEGRP2" SRVID=1001 RESTART=Y GRACE=0 REPLYQ=N 
    CLOPT=" -- -qservice1" 
*SERVICES 
ACCOUNTING ROUTING="MYROUTING" 
*ROUTING 
MYROUTING FIELD=ACCOUNT BUFTYPE="FML" 
RANGES="MIN - 60000:TMQUEUEGRP1,60001-MAX:TMQUEUEGRP2"

In this example, two queues spaces are available. Both TMQUEUE servers offer the same services and routing is done via the ACCOUNT field in the application typed buffer.

See Also

ubbconfig(5), servopts(5), buildserver(1), tpenqueue(3), tpdequeue(3), TMQFORWARD(5), Administering the BEA TUXEDO System, BEA TUXEDO Programmer's Guide

---

---