Oracle Tuxedo Message Queue UBB Server Reference

 

Table 1 Oracle Tuxedo Message Queue UBB Servers

Name	Description
TuxMsgQLD	OTMQ Link Driver Server.
TuxMsgQ	Message Queue Manager.
TuxMQFWD	Message Queue Off-line trade driver.
TMQ_NA	Message Queue Naming Server.
TMS_TMQM	TMS server for OTMQ resource manager.
TMQEVT	TMQ event reporting process.
TMQFORWARDPLUS	Message Forwarding server.

TuxMsgQLD

TuxMsgQLD—OTMQ Link Driver Server

Synopsis

TuxMsgQLD SRVGRP="identifier" SRVID="number"
[CLOPT="[-A] [servopts options]
[-g grp_id][ -l //hostname:port][ -f config_filename]"]

Description

The TuxMsgQLD (Link Driver Server) of OTMQ is ported from traditional OMQ Link Driver to achieve message level compatibilities between OTMQ and OMQ applications.

Also the OTMQ Link Driver Server provides the routing functionality like traditional OMQ but with limitations.

Configuration File

To configure this Link Driver Server, a new configuration file should be created. This configuration file should be under APPDIR. The configuration file is ported from %XGROUP and %ROUTE section of traditional OMQ configuration file. .

Listing 3‑1 an example of the Link Driver Server configuration file:

Listing 3‑1 Link Driver Server Configuration File:

# Define cross-group connections with remote OMQ,

# only the remove OMQ group info should be listed here

%XGROUP

# Group   Group   Node/   Init-   Thresh   Buffer   Recon-   Window   Trans-   End-

# Name     Number  Host      iate     old     Pool      nect     Delay  Size (Kb)  port  point

GRP_11      11  host1.abc.com  Y       -       -         30       10      250     TCPIP   10001

GRP_12      12   host2.abc.com Y       -       -         30       10      250     TCPIP   10002

 

%EOS

%ROUTE

#----------------------------------

# Target Route-through

# Group Group

#----------------------------------

2 11

3 12

%EOS

%END

 

%XGROUP Section

Following configuration attributes are mandatory for OTMQ to setup XGROUP connection to the remote OMQ group:

•	"Group Name -- Remote OMQ group name by which the remote OMQ group is known to the local OTMQ group

•	"Group Number -- Remote OMQ group number

•	"Node/Host -- Network address of remote OMQ group

•	"Endpoint -- The internet port number of the remote OMQ link listener process

Following attributes are optional. If not set, default values will be used:

•	"Initiate -- "Y", "N" or "D". indicating whether connections to this node should be initiated (connect when local group startup) or whether connections to this node is enabled. Default is "N".

•	"Reconnect -- Interval, in seconds, between reconnect attempts when this cross-group link is not connected. Default is 60.

•	"Window Delay -- Delay, in seconds, that a sender must wait before using a new window when the receiver is congested. Default is 10.

•	"Windows Size -- Maximum number of messages a group can send to another group before requesting permission to send more. Default is 250.

•	"Transport: Network protocol stack used. Only "TCPIP" is supported.

Following attributes are not supported by OTMQ Link Driver Server, but to keep align with traditional OMQ XGROUP settings, just keep them here:

•	"Buffer Pool -- Not supported by OTMQ for now.

•	"Threshold -- Not supported by OTMQ for now.

%ROUTE

Following configuration attributes are mandatory for OTMQ to setup ROUTE info for the remote OMQ/OTMQ groups that can't be connected directly:

•	"Target Group -- OMQ/OTMQ group for which traffic is being routed to.

•	"Route-through Group -- OMQ group to which traffic for the target group will be routed through.

Note:

Route-through Groups should be the OMQ groups that this OTMQ group has direct connection to (i.e. defined in the %XGROUP section). Cannot define multiple routing entry for the same Target Group.

Limitations

Direct Connection

•	Only support DISC and RTS UMA.

Routing

•	Only support AK and NN modes.

•	Only support DISC UMA.

•	Only support MEM, DEQ and ACK DIPs when protocol exchange is involved more than once, such as sending message from OMQ to OMQ through OTMQ or from OTMQ to OTMQ through OMQ.

TuxMsgQ

TuxMsgQ—Message Queue Manager.

Synopsis

TuxMsgQ

SRVGRP="identifier"

SRVID="number" CLOPT=" [-A][servopts options] -- [-t timeout][-i interval]"

Description

The message queue manager is an Oracle Tuxedo system-supplied server that enqueues and dequeues messages on behalf of programs calling tpenqplus() and tpdeqplus(), respectively. The application administrator enables message enqueuing and dequeuing for the application by specifying this server as an application server in the *SERVERS section.

To configure default attach timeout for a Qspace, set BLOCKTIME property in the *SERVICES section for the service named TuxMQATH[qspace], where [qspace] is the service name that TuxMsgQ advertised with routine TuxMsgQ.

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 additional command-line option is available for customization.

It takes the following options:

-t timeout

Used to indicate the timeout to be used for queuing operations when not in transaction mode (for example, tpenqueue() /tpenqplus() or tpdequeue()/tpdeqplus() 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 operation 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 TuxMsgQ 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 TuxMsgQ from enqueuing or dequeuing messages will cause the TuxMsgQ 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.

-i interval

To configure the sanity check interval in TuxMsgQ server, set "-i [interval]" in CLOPT. The "interval" number means the TuxMsgQ server will do sanity check per receiving this number of messages.

Example(s)

Listing 3‑2 TuxMsgQ Example

*SERVERS

TuxMsgQ SRVGRP="TUXMSGQGRP" SRVID=1000 RESTART=Y GRACE=0

CLOPT="-s myqueue:TuxMsgQ"

 

See Also

tpdeqplus(), tpenqplus(), servopts(5), TMQFORWARDPLUS, UBBCONFIG(5)

Setting Up an Oracle Tuxedo Application

Administering an Oracle Tuxedo Application at Run Time

Programming an Oracle Tuxedo ATMI Application Using C

TuxMQFWD

Name

TuxMQFWD—Message Queue Off-line trade driver.

Synopsis

TuxMQFWD
SRVGRP="identifier"
SRVID="number" CLOPT=" [-A][servopts options] -- [-f delay time][-t timeout][-i idle time]"

Description

The message queue off-line trade driver is an Oracle Tuxedo system-supplied server.

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. It takes the following options:

-f delay time

Parameter used to indicate the amount of time (in seconds) when off-line trade driver try again after the last time failure

-i idletime

Parameter used to indicate the amount of time (in seconds) that the server remains idle after draining the queue(s) that it is reading. A negative value indicates an amount of time in milliseconds. For example if you specify -i -10, the idle time will be 10 milliseconds.

If a value of zero is specified,a 1 second value is used, the server reads the queue(s) continually, which can be inefficient if the queues do not continually have messages.If a value of zero is specified, a 1 second value is used.

-t timeout

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

Any configuration condition that prevents TuxMQFWD 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_TMQM.

•	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 server must not advertise any services (TuxMQFWD is built out without any service, so -s option will be ignored).You cannot configure more than one TuxMQFWD process in a group.

Example(s)

TuxMQFWD
SRVGRP=QGRP1 SRVID=51 GRACE=0 RESTART=Y CONV=N MAXGEN=10
CLOPT="-- -i 1"

TMQ_NA

Name

TMQ_NA—Message Queue Naming Server

Synopsis

TMQ_NA
SRVGRP="identifier"
SRVID="number" CLOPT=" [-A][servopts options] -- [-g OTMQ group] [-r OMQ group]"

Description

TMQ_NA is an OTMQ system server. It can provide naming and runtime binding of queue aliases to queue names. It supports the following options:

-g xxx

Parameter used to indicate this naming service is provided by OTMQ group xxx.

-r yyy

Parameter used to indicate this naming service is provided by OMQ group yyy

Note:

the sequence of parameters determines which Naming server is primary and which one is backup,

Example(s)

TMQ_NA
SRVGRP=QGRP1 SRVID=51 GRACE=0 RESTART=Y CONV=N MAXGEN=10
CLOPT=" -- -g 1 "

TMS_TMQM

Name

TMS_TMQM—TMS server for OTMQ resource manager.

Synopsis

 

Description

OTMQ also provides a separate Tuxedo Transaction Management Server (TMS). TMS_TMQM should be configured in the TuxMsgQ and/or TuxMQFWD group.

Example(s)

*GROUPS
QGRP1
    LMID=L1 GRPNO=1 TMSNAME=TMS_TMQM TMSCOUNT=2
    OPENINFO="TUXEDO/TMQM:/dev/device2:myqueue"

TMQEVT

Name

TMQEVT—OTMQ event reporting process.

Synopsis

TMQEVT SRVGRP="identifier" SRVID="number"
  [CLOPT="[-A] [servopts options]
  [-- [-S] [-p poll-seconds] [-f control-file]]"]

Description

TMQEVT is an Oracle Tuxedo system provided server that processes event report message buffers from tpqpublish, and acts as an EventBroker to filter and distribute them.

Filtering and notification rules are stored in control-file, which defaults to ${APPDIR}/tmqevt.dat. Control file syntax is defined in EVENT_MIB(5); specifically, the attributes of the classes in EVENT_MIB can be set to activate subscriptions under the full range of notification rules.

It is possible to boot one or more secondary TMQEVT processes for increased availability. Additional servers must be booted with the -S command-line option, which indicates a "secondary" server.

When the EVENT_MIB(5) configuration is updated, the primary TMQEVT server writes to its control file. Secondary servers poll the primary server for changes and update their local control file if necessary. The polling interval is controlled by the -p option, and is 30 seconds by default.

Notes:

If you are setting up an MP configuration that includes more than one release of the Oracle Tuxedo system and you want to run the TMQEVT server, you must run these servers on the node with the highest available release of the system.

TMQEVT must not delopoy with the same group of TMS_TMQM.

TMQEVT must run on an Oracle Tuxedo release 6.0 or later machine.

To migrate the primary TMQEVT server to another machine, the system administrator must provide a current copy of control-file. Each secondary TMQEVT server automatically maintains a recent copy.

If tpqupublis() is called in transaction mode, all TMQEVT server groups must have transactional capability (a TMS process).

The TMQEVT server environment variables must be set so that FML field tables and viewfiles needed for message filtering and formatting are available. They could be set in the machine's or server's environment file.

Example(s)

*SERVERS
TMQEVT SRVGRP=ADMIN1 SRVID=100 RESTART=Y MAXGEN=5 GRACE=3600
CLOPT="-A --"
TMQEVT SRVGRP=ADMIN2 SRVID=100 RESTART=Y MAXGEN=5 GRACE=3600
CLOPT="-A -- -S -p 120"

See Also

tpqpublish(), tpqsubscribe(), EVENTS(5), EVENT_MIB(5),

TMQFORWARDPLUS

Name

TMQFORWARDPLUS—Message Forwarding server.

Synopsis

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

Description

The message forwarding server is an Oracle Tuxedo system-supplied server that forwards messages that have been stored using tpenqplus() 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. It supports the following options:

-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 amount of time (in seconds) that the server remains idle after draining the queue(s) that it is reading. A negative value indicates an amount of time in milliseconds. For example if you specify -i -10, the idle time will be 10 milliseconds.

If a value of zero is specified, the server will read the queue(s) continually, which can be inefficient if the queues do not continually have messages. If no value is specified, the default is 30 seconds.

-b timeout

Used to limit nontransaction block waiting time, in seconds, for a forwarded service to complete. The -b option can only be used with the -f option.

-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 TMQFORWARDPLUS 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 TMQFORWARDPLUS 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 TMQFORWARDPLUS 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, 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, 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, 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 TMQFORWARDPLUS 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_TMQM.

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

Example(s)

Listing 3‑3 TMQFORWARDPLUS Example

*GROUPS # For Windows, :myqueue becomes ;myqueue
TUXMSGQGRP LMID=lmid GRPNO=1 TMSNAME=TMS_TMQM
OPENINFO="TUXEDO/TMQM:/dev/device:myqueue"
# no CLOSEINFO is required

*SERVERS # recommended values RESTART=Y GRACE=0
TMQFORWARDPLUS SRVGRP="TUXMSGQGRP" SRVID=1001 RESTART=Y GRACE=0
CLOPT=" -- -qservice1,service2" REPLYQ=N

 

See Also

tpenqplus(), servopts(5), UBBCONFIG(5)