Running the Tuxedo MQ Adapter

This chapter contains the following topics:

•	Booting the Servers

•	Initiating a TUXEDO-to-WebSphere MQ Requestt

•	Initiating a WebSphere MQ-to-TUXEDO Request

•	Sending and Receiving Queued Messages to and from WebSphere MQ

Booting the Servers

The MQ Adapter servers boot as part of the TUXEDO application using standard TUXEDO utilities, such as tmboot. The MQ Adapter reads the server configuration files and attempts to connect to the specified queue manager. Once the MQ Adapter establishes a connection with the queue manager, the Tuxedo to WebSphere MQ server (TM_MQO) advertises the services associated with that queue manager.

Initiating a TUXEDO-to-WebSphere MQ Request

TUXEDO clients can call services advertised by the Tuxedo to MQ server (TM_MQO). A TUXEDO-to-WebSphere MQ request consists of the following actions.

1.	The TUXEDO client initiates a request for a service advertised by TM_MQO.

2.	The MQ Adapter uses the WebSphere MQ Message Queue Interface (MQI) to forward these requests to the appropriate WebSphere MQ queue.

3.	The MQ Adapter retrieves response data (if any) from the designated reply queue and returns this data to the TUXEDO client.

Initiating a WebSphere MQ-to-TUXEDO Request

WebSphere MQ applications can request TUXEDO services via the WebSphere MQ to Tuxedo server TM_MQI. An WebSphere MQ-to-TUXEDO request consists of the following actions.

1.	The WebSphere MQ application queues a message requesting the service to a designated queue.

2.	The MQ Adapter retrieves the message from the incoming queue.

3.	The MQ Adapter forwards the message data to the appropriate service.

4.	The MQ Adapter places response data (if any) on the specified reply queue.

Sending and Receiving Queued Messages to and from WebSphere MQ

The TMQUEUE_MQM server processes tpenqueue and tpdequeue requests from TUXEDO client and server processes.

Processing a tpenqueue Request

The syntax for a tpenqueue request is as follows:

tpenqueue (qspace, qname, qctl, data, len, flags)

A tpenqueue request requires all parameters shown previously. Following are brief descriptions of these parameters. For more information, refer to the Oracle TUXEDO Programmer's Guide.

QSPACE

The name of the service advertised by TMQUEUE_MQM. This value can be overwritten in the TUXEDO UBBCONFIG file using the - s option. For example:

-s myname :MQMQUEUE

Default is MQMQUEUE.

QNAME

The name of the queue where you want the adapter to place or retrieve messages. Can contain up to 127 characters. Corresponds to a WebSphere MQ queue mapped from the TUXNAME parameter in the QUEUE section of the TMQUEUE_MQM configuration file.

QCTL

Provides additional information about the message. The supported options you can define for tpenqueue requests are as follows:

TPNOFLAGS

No options apply to this message

TPQPRIORITY

Message priority. TUXEDO values for this field can be from 1-100. The MQ values can be 0-9 and are mapped to TUXEDO values as follows: 0=TUXEDO 1-10, 1=TUXEDO 11-20, etc.

TPQCORRID

Correlation ID. Identifies the response to a request. TUXEDO supports up to 32 bytes. The MQ Adapter supports up to 24 bytes, so TUXEDO values are truncated on tpenqueue requests.

TPQREPLYQ

Name of the queue where you want to place reply messages. Can contain up to 127 characters.

TPQMSGID

Return the message ID generated when the message is placed on the queue. TUXEDO supports up to 32 bytes. The MQ Adapter supports up to 24 bytes and pads the ID with nulls.

TPQDELIVERYQOS

Specifies the delivery quality of service. If a value of TPQQOSPERSISTENT is specified, the MQ persistence is set to MQPER_PERSISTENT. If a value of TPQQOSNONPERSISTENT is specified, the MQ persistence is set to MQPER_NOT_PERSISTENT. If a value of TPQQOSDEFAULTPERSIST is specified or if TPQDELIVERYQOS is not specified, then MQ persistence is set to MQPER_PERSISTENT if the request was made in a transaction and is set to MQPER_PERSISTENCE_AS_Q_DEF otherwise.

TPQEXPTIME_NONE

Specifies that the queued message should not expire. This corresponds to a value of MQEI_UNLIMITED in the MQMD structure passed to WebSphere MQ.

TPQEXPTIME_ABS

Specifies an absolute expiration time for the queued message. This value is converted to a format understood by WebSphere MQ and passed to MQ via the Expiry field of the WebSphere MQ MQMD structure.

TPQEXPTIME_REL

Specifies a relative expiration time for the queued message. This value is converted to a format understood by WebSphere MQ and passed to MQ via the Expiry field of the WebSphere MQ MQMD structure.

Note:

The TPQFAILUREQ, TPQBEFOREMSGID, TPQTOP, TPQTIME_REL, TPQTIME_ABS, and TPQREPLYQOS options are not supported for tpenqueue requests to TMQUEUE_MQM

DATA

Data to be placed on the queue

LEN

Length of the data to be placed on the queue

FLAGS

Defines the flag settings for the message. The supported flags for tpenqueue requests are as follows:

TPNOTRAN

Messages from callers that are in transaction mode are not queued within the same transaction as the caller.

 

Processing a tpdequeue Request

The syntax for a tpdequeue request is as follows:

tpdequeue (qspace, qname, qctl, data, len, flags)

A tpdequeue request requires all parameters shown previously. Following are brief descriptions of these parameters. For more information, refer to the Oracle TUXEDO Programmer's Guide.

QSPACE

The name of the service advertised by TMQUEUE_MQM. This value can be overwritten in the TUXEDO UBBCONFIG file using the - s option. For example:

-s myname :MQMQUEUE

The default value is MQMQUEUE

QNAME

The name of the queue where you want the adapter to place or retrieve messages. Can contain up to 127 characters. Corresponds to a WebSphere MQ queue mapped from the TUXNAME parameter in the QUEUE section of the TMQUEUE_MQM configuration file.

QCTL

Provides additional information about the message. The supported options you can define for tpdequeue requests are as follows:

TPNOFLAGS

No options apply to this message

TPQGETBYMSGID

Dequeues the message with the specified message ID, if available. The specified message ID is truncated to 24 bytes and passed in the MsgId field of the MQMD structure when calling the WebSphere MQ MQGET API.

TPQGETBYCORRID

Dequeues the message with the specified correlation ID.

TPQPRIORITY

Message priority. TUXEDO values for this field can be from 1-100. The MQ values can be 0-9 and are mapped to TUXEDO values as follows: 0=TUXEDO 1-10, 1=TUXEDO 11-20, etc.

TPQCORRID

Correlation ID. Identifies the response to a request. TUXEDO supports up to 32 bytes. MQ supports up to 24 bytes, so this ID will always fit in 32 bytes supported by Tuxedo. The remaining 8 bytes are set to null characters.

TPQREPLYQ

Name of the queue where you want to place reply messages. Can contain up to 127 characters.

TPQMSGID

Return the message ID generated when the message is placed on the queue. MQ supports up to 24 bytes, so this ID will always fit in 32 bytes supported by Tuxedo. The remaining 8 bytes are set to null characters.

TPQPEEK

If this flag is set, the specified message is read but is not removed from the queue. This flag implies the TPNOTRAN flag has been set for the tpdequeue() operation. That is, non-destructive dequeuing is non-transactional. Note that it is not possible to read messages enqueued or dequeued within a transaction before the transaction completes.

TPQDELIVERYQOS

If this flag is set, the call to tpdequeue() is successful, and the message was queued with a delivery quality of service, then the flag is stored in ctl->delivery_qos. If the MQGET call indicates a Persistence of MQPER_NOT_PERSISTENT, ctl->delivery_qos is set to TPQQOSNONPERSISTENT. Otherwise, it is set to TPQQOSPERSISTENT.

Note:

The TPQWAIT option is not supported for tpdequeue requests to TMQUEUE_MQM

DATA

Data to be placed on the queue

LEN

Length of the data to be placed on the queue

FLAGS

Defines the flag settings for the message. The supported flags for tpdequeue requests are as follows:

TPNOTRAN

Messages from callers that are in transaction mode are not dequeued within the same transaction as the caller.