TMQFORWARD(5)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| File Formats and Data Descriptions Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

TMQFORWARD(5)

Name

TMQFORWARD—Message Forwarding server

Synopsis

TMQFORWARD SRVGRP="identifier" SRVID="number" REPLYQ=N CLOPT=" 
[-A] [servopts options] -- -q queuename[,queuename...] 
[-t trantime ] [-i idletime] [-e] [-d] [-n] [-f delay] "

Description

The message forwarding server is a BEA Tuxedo system-supplied server that forwards messages that have been stored using tpenqueue() for later processing. The application administrator enables automated message processing for the application servers 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.

-q queuename[,queuename...]

Used to specify the names of one or more queues/services for which this server forwards messages. Queue and service names are strings limited to 15 characters. This option is required.

-t trantime

Used to indicate the transaction timeout value used on tpbegin() for transactions that dequeue messages and forward them to application servers. If not specified, the default is 60 seconds.

-i idletime

Used to indicate the time that the server is idle after draining the queue(s) that it is reading. A value of zero indicates that the server will continually read the queue(s), which can be inefficient if the queues do not continually have messages. If not specified, the default is 30 seconds.

-e

Used to cause the server to exit if it finds no messages on the queue(s). This, combined with the threshold command associated with the queue(s), can be used to start and stop the TMQFORWARD server in response to fluctuations of messages that are enqueued.

-d

Used to cause messages that result in service failure and have a reply message (non-zero in length) to be deleted from the queue after the transaction is rolled back. That is, the original request message is deleted from the queue—not put back on the queue—if the service fails and a reply message (non-zero in length) is received from the server.

The reply message is enqueued to the failure queue, if one is associated with the message and the queue exists. If the 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.

-n

Used to cause messages to be sent using the TPNOTRAN flag. This flag allows for forwarding to server groups that are not associated with a resource manager.

-f delay

Used to cause the server to forward the message to the service instead of using tpcall. The message is sent such that a reply is not expected from the service. The TMQFORWARD server does not block waiting for the reply from the service and can continue processing the next message from the queue. To throttle the system such that TMQFORWARD does not flood the system with requests, the delay numeric value can be used to indicate a delay, in seconds, between processing requests; use zero for no delay.

Messages are sent to a server providing a service whose name matches the queue name from which the message is read. The message priority is the priority specified when the message is enqueued, if set. Otherwise, the priority is the priority for the service, as defined in the configuration file, or the default (50).

Messages are dequeued and sent to the server within a transaction. If the service succeeds, the transaction is committed and the message is deleted from the queue. If the message is associated with a reply queue, then any reply from the service is enqueued to the reply queue, along with the returned tpurcode. If the reply queue does not exist, the reply is dropped.

An application may be able to specify the quality of service for a reply to a message when the original message is enqueued. If a reply quality of service is not specified, then the default delivery policy specified for the reply queue is used. Note that the default delivery policy is determined when the reply to a message is enqueued. That is, if the default delivery policy of the reply queue is modified between the time that the original message is enqueued and the reply to the message is enqueued, the policy used is the one in effect when the reply is finally enqueued.

If the service fails, then the transaction is rolled back and the message is put back on the queue, up to the number of times specified by the retry limit configured for the queue. When a message is put back on the queue, the rules for ordering and dequeuing that applied when it was first put on the queue are (in effect) suspended for delay seconds; this opens up the possibility, for example, that a message of a lower priority may be dequeued ahead of the restored message on a queue ordered by priority.

If the -d option is specified, the message is deleted from the queue if the service fails and a reply message is received from the server, and the reply message (and associated tpurcode) are enqueued to the failure queue, if one is associated with the message and the queue exists. If the message is to be deleted at the same time as the retry limit for the queue is reached, the original request message is put into the error queue.

Any configuration condition that prevents TMQFORWARD from dequeuing or forwarding messages will cause the server to fail to boot. These conditions include the following:

The SRVGRP must have TMSNAME set to TMS_QM.
OPENINFO must be set to indicate the associated device and queue name.
The SERVER entry must not be part of an MSSQ set.
REPLYQ must be set to N.
The -q option must be specified in the command-line options.
The server must not advertise any services (that is, the -s option must not be specified).

Handling Application Buffer Types

As delivered, TMQFORWARD handles the standard buffer types provided with the BEA Tuxedo system. If additional application buffer types are needed, then a customized version of TMQFORWARD needs to be built using buildserver(1) with a customized type switch. See the description in Using the ATMI /Q Component.

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/TMQFORWARD.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 TMQFORWARD -r TUXEDO/QM -f ${TUXDIR}/lib/TMQFORWARD.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 filename 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 the name TMQFORWARD be used for consistency. The application specific version of the command can be installed in $APPDIR it is booted instead of the version in $TUXDIR/bin.

-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/TMQFORWARD.o

Specifies the object file that contains the TMQFORWARD 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 TMQFORWARD.o object file. If more than one file is specified, filenames must be separated by white space (space or tab) and the entire list must be enclosed in quotation marks. This option can be specified multiple times.

The -s option must not be specified to advertise services.

Portability

TMQFORWARD is supported as a BEA Tuxedo system-supplied server on all supported server platforms.

Interoperability

TMQFORWARD may be run in an interoperating application, but it must run on a BEA Tuxedo release 4.2 or later node.

Examples

*GROUPS # For Windows, :myqueue becomes ;myqueue 
TMQUEUEGRP LMID=lmid GRPNO=1 TMSNAME=TMS_QM 
   OPENINFO="TUXEDO/QM:/dev/device:myqueue" 
# no CLOSEINFO is required 
 
*SERVERS # recommended values RESTART=Y GRACE=0 
TMQFORWARD SRVGRP="TMQUEUEGRP" SRVID=1001 RESTART=Y GRACE=0
   CLOPT=" -- -qservice1,service2" REPLYQ=N 
TMQUEUE SRVGRP="TMQUEUEGRP" SRVID=1000 RESTART=Y GRACE=0 
   CLOPT="-s ACCOUNTING:TMQUEUE"