MQ Adapter

Configuring the Oracle Tuxedo MQ Adapter

This chapter contains the following topics:

Configuring the Oracle Tuxedo Servers

The Oracle Tuxedo MQ Adapter consists of three Oracle Tuxedo servers: an Oracle Tuxedo to WebSphere MQ server (TM_MQO), a WebSphere MQ to Oracle Tuxedo server (TM_MQI), and a server for handling tpenqueue() and tpdequeue() requests (TMQUEUE_MQM). You must identify each of the servers that you intend to use in the Oracle Tuxedo UBBCONFIG file. In addition, the MQ Adapter requires that certain parameters be set for each server. You define these parameters in a server configuration file. A sample configuration file for each server is shown in this document. You can use these sample configuration files as a base and insert the specific information required for your environment.

The following sections describe how to identify each of the servers in the Oracle Tuxedo UBBCONFIG file, and how to set up the configuration file required by the MQ Adapter for each of these servers.

Configuring the Oracle Tuxedo to WebSphere MQ Server (TM_MQO)

TM_MQO routes all requests for WebSphere MQ services from Oracle Tuxedo clients. It interacts with WebSphere MQ via the Message Queue Interface (MQI) by enqueuing and dequeuing service requests and responses. The MQI is a common application programming interface that all WebSphere MQ applications implement.

You define the TM_MQO server in the SERVERS section of the Oracle Tuxedo UBBCONFIG file as follows in Listing 3-1:

Listing 3-1 Syntax for TM_MQO Server Definition in UBBCONFIG

*SERVERS
TM_MQO SRVGRP="identifier" SRVID="number"
CLOPT="-- -C configuration_file_name"

For SRVGRP, SRVID, and CLOPT parameter syntax and definitions information, see File Formats, Data Descriptions, MIBs, and System Processes Reference.

CLOPT= "-- -C Tuxedo to WebSphere MQ configfile" specifies the server's configuration file.

A configuration file provides a list of services and their associated parameters to the server at startup. See Creating the Server Configuration Files for an explanation of the parameters you need to define.

Defining FML32 Fields for the Oracle Tuxedo to WebSphere MQ Server

Oracle Tuxedo has defined FML32 fields for TM_MQO in the $TUXDIR/udataobj/Usysfl32 field definition table and in the $TUXDIR/include/Usysfl32.h header file. The Oracle Tuxedo MQ Adapter uses FML32 functions to manipulate fielded buffers related to errors. For more information about FML32 programming, see the Programming an Oracle Tuxedo ATMI Application Using FML.

The syntax for the field definition table for TM_MQO is as follows in Listing 3-2:

Listing 3-2 Syntax for field definition table for TM_MQO

# name                  number    type    flags   comments
TPMQ_ADAPTER_ERR        `n'     string      -        -
TPMQ_ADAPTER_ERR_CODE   `n'     string      -        -
TPMQ_APP_ERR            `n'     string      -        -

These FML32 fields are used as follows:

TPMQ_ADAPTER_ERR: stores the details of the errors specific to the Oracle Tuxedo MQ Adapter.
TPMQ_ADAPTER_ERR_CODE: stores the category code for the adapter-specific errors.
TPMQ_APP_ERR: stores the details of the errors specific to WebSphere MQ.

These fields are defined in $TUXDIR/udataobj/Usysfl32 and in $TUXDIR/include/Usysfl32.h. (If an interoperating client running Oracle Tuxedo 9.1 or earlier wants to use these fields, the client will need to define these fields using the same field numbers as in later versions of Oracle Tuxedo.).

The environment variables FLDTBLDIR32 and FIELDTBLS32 should be set so that the system will look in $TUXDIR/udataobj/Usysfl32 for FML32 field definitions.

Configuring the WebSphere MQ to Oracle Tuxedo Server (TM_MQI)

TM_MQI forwards messages requested from WebSphere MQ applications to Oracle Tuxedo services. The application queues a request to a designated queue that is monitored by TM_MQI. The requested service is specified in the message descriptor. Like TM_MQO, TM_MQI must perform data and semantic transformations on the data stored on a queue before delivering it to a service. It must do the same to replies.

You define the TM_MQI server in the SERVERS section of the Oracle Tuxedo UBBCONFIG file as follows in Listing 3-3:

Listing 3-3 Syntax for TM_MQI Definition in UBBCONFIG

*SERVERS TM_MQI SRVGRP="identifier" SRVID="number" REPLYQ=N CLOPT="-- -C configuration_file_name"

For information about the SRVGRP, SRVID, REPLYQ, and CLOPT parameter syntax and definitions, refer to the Oracle Oracle Tuxedo Reference Manual.

CLOPT= "-- -C WebSphere MQ to Tuxedo configfile" specifies the server's configuration file.

A configuration file provides a list of queues and services and their associated parameters to the server at startup. See Creating the Server Configuration Files for an explanation of the parameters you need to define.

Configuring the TMQUEUE_MQM Server

TMQUEUE_MQM processes the tpenqueue() and tpdequeue() requests from Oracle Tuxedo applications that need to send or retrieve data to or from an WebSphere MQ queue.

You define the TMQUEUE_MQM server in the SERVERS section of the Oracle Tuxedo UBBCONFIG file as follows in Listing 3-4:

Listing 3-4 Syntax for TMQUEUE_MQM Definition in UBBCONFIG

*SERVERS

TMQUEUE_MQM SRVGRP="identifier" SRVID="number" REPLYQ=N CLOPT="--  -C configuration_file_name"

For information about the SRVGRP, SRVID, REPLYQ, and CLOPT parameter syntax and definitions, refer to the Oracle Tuxedo Reference Manual.

CLOPT= "-- -C enqueue/dequeue configfile" specifies the server's configuration file.

A configuration file provides a list of queues and their associated parameters to the server at startup. See Creating the Server Configuration Files for an explanation of the parameters you need to define.

Creating the Server Configuration Files

You must create a configuration file for each of the three MQ Adapter servers. The documentation shows sample files you can use as a base for creating your own configuration files. You can substitute the parameter settings in the sample files with the settings required for your own environment.

Creating the Oracle Tuxedo to WebSphere MQ Server Configuration File

The TM_MQO.CFG file controls the operation of the Oracle Tuxedo to WebSphere MQ server (TM_MQO). Following are the sections of the TM_MQO configuration file and the parameters you can define for each section. A sample configuration file follows the descriptions.

Note:

TM_MQO.CFG is a generic filename. You can name this file anything you choose, but the filename must match the -C configuration_file_name parameter you specify in the Oracle Tuxedo UBBCONFIG file. (See Configuring the Oracle Tuxedo to WebSphere MQ Server (TM_MQO) for instructions on configuring the TM_MQO server in the UBBCONFIG file.)

The TM_MQO configuration file is divided into the following required sections:

Queue_Manager

Defines the queue manager name and logical ID.

Note:

The configuration file can only have one QUEUE_MANAGER section.

SERVICES

Defines various parameters for services and messages.

The TM_MQO configuration file has one optional section:

SERVER

Defines minimum and maximum settings for services and messages.

Note:

The configuration file can only have one SERVER section.

These sections and the parameters within each section can be in any order in the configuration file, as long as the required sections and parameters are defined.

Defining the TM_MQO QUEUE_MANAGER Section (Required)

The syntax for the QUEUE_MANAGER section of the TM_MQO configuration file is as follows in Listing 3-5:

Listing 3-5 Syntax for QUEUE_MANAGER section

*QUEUE_MANAGER

NAME=string

LQMID=string

Note:

The configuration file can only have one QUEUE_MANAGER section.

Required Parameter

The following parameter must be included in the QUEUE_MANAGER section of the TM_MQO configuration file.

`NAME= string`

Specifies the name of the WebSphere MQ Queue Manager. Can contain up to 48 characters, all uppercase. Refer to WebSphere MQ documentation for the specific format of Queue Manager names.

Optional Parameter

The following parameter is optional:

`LQMID= string`

Specifies the logical Queue Manager ID. Can contain up to 8 alphanumeric characters, upper and lowercase. If this parameter is specified, it will be included in certain userlog messages.

Defining the TM_MQO SERVICE Section (Required)

The syntax for the SERVICE section of the TM_MQO configuration file is as follows in Listing 3-6:

Listing 3-6 Syntax for SERVICE section

*SERVICE
NAME=string
MQNAME=string
FORMAT=string
TRAN={Y/N}
MAXMSGLEN=integer
REPLYTOQ=string
TIMEOUT=integer
EXPIRE=integer
PRIORITY=integer
INFIELD=string
OUTFIELD=string
OUTFIELDVNAME=string

Required Parameters

The following parameters must be included in the SERVICE section of the TM_MQO configuration file.

`NAME = string`

Specifies the Oracle Tuxedo Service Name. The maximum length of this parameter is the same as the maximum length of an Oracle Tuxedo service name, which is currently 127 characters of mixed case. Note that the NAME string should be unique among all of the *SERVICE sections in a particular TM_MQO configuration file.

`MQNAME = string`

Specifies the name of the WebSphere MQ Queue. Can contain up to a maximum of 48 characters, all uppercase. Refer to WebSphere MQ documentation for the specific format of Queue names.

`MAXMSGLEN = integer`

Specifies the maximum message length expected for buffers received by this service. This is a required parameter unless DEFMAXMSGLEN is specified in the SERVER section. (See Defining the SERVER Section (Optional) for more information).

`TIMEOUT = integer`

Specifies the amount of time, in seconds, that is allowed for processing of the indicated MQ service. (This is the maximum amount of time that MQGET will wait for a message on the reply queue after the MQ service is invoked with MQPUT1.) The value must be greater than or equal to 0. A value of 0 indicates that the service will not be timed out. This is a required parameter unless DEFTIMEOUT is specified in the SERVER section. (See Defining the SERVER Section (Optional) for more information).

Optional Parameters

The following parameters are optional.

`EXPIRE = integer`

Specifies the amount of time, in tenths of a second, the expiry time for the MQ service request message sent with MQPUT1. The value must be greater than or equal to 0. A value of 0 indicates that the message will not be expired. The default value is 0.

`PRIORITY = integer`

Specifies the WebSphere MQ priority at which requests to this service will be sent. WebSphere MQ has traditionally allowed values of 0 through 9 for priorities. If not specified, the default queue priority represented in MQ by the value MQPRI_PRIORITY_AS_Q_DEF will be used.

`FORMAT = string`

Maps to the WebSphere MQ Message Descriptor Format. Can contain up to 8 characters. Refer to WebSphere MQ documentation for specific format of the Message Descriptor Format field.

`TRAN = {Y|N}`

Specifies whether the Service is transactional. Y indicates transactional; N indicates non-transactional. The default value is N. (A service defined as transactional must be called within an Oracle Tuxedo transaction. A service defined as non-transactional must be called outside of an Oracle Tuxedo transaction. Messages sent to transactional services are sent with persistence MQPER_PERSISTENT and messages sent to non-transactional services are sent with the default queue persistence MQPER_PERSISTENCE_AS_Q_DEF.)

`REPLYTOQ = string`

Specifies the name of the WebSphere MQ Reply To Queue. Can contain up to 48 characters, all uppercase. Refer to WebSphere MQ documentation for the specific format of Queue names.

`INFIELD = string`

Specifies the FML32 field name of the input data in an FML32 buffer. If you specify this parameter, requests for this service may pass FML32 buffers for input, and the data in INFIELD will be passed as the actual service data. (A request to a service which specifies INFIELD may still pass a non-FML32 data type as input, which will be treated exactly as if INFIELD had not been specified, but a request to a service which specifies INFIELD may not pass NULL data.)

If INFIELD is a FLD_VIEW32 field, TM_MQO will pass only the actual VIEW32 data to MQ and will not pass the FVIEWFLD structure that was returned by FML32. The MQ program must know which view it is expecting to receive. The application should not use fields of type FLD_PTR, FLD_FML32, FLD_MBSTRING, or FLD_FML for the TM_MQO INFIELD or OUTFIELD. These field types will not result in meaningful data being passed to or from the MQ application. If INFIELD is not specified, then TM_MQO will accept only buffers not of type FML32 as input, and will pass this data directly to WebSphere MQ.

`OUTFIELD = string`

Specifies the FML32 field name of the output data to be used when building an FML32 response buffer. If you specify this parameter, you must also specify the INFIELD parameter. The omission of this parameter causes the response data field name to match the name specified by the INFIELD parameter.

When OUTFIELD is a FLD_VIEW32 field, the data returned by MQ should be VIEW32 data, and not a FVIEWFLD structure. In order to pass VIEW32 data back to an Oracle Tuxedo application, TM_MQO must internally fill in a FVIEWFLD structure to add the VIEW32 data to the FML32 reply buffer, and therefore TM_MQO must know the name of the view to be returned. The TM_MQO server will obtain this information in the following manner:

If the OUTFIELDVNAME parameter is set, the value of this parameter will be used as the view32 name.
Otherwise, if the INFIELD was a FLD_VIEW32 field, the same viewname used in the INFIELD will be used for the OUTFIELD.
Otherwise, TM_MQO will log an error message and call tpreturn() with TPFAIL.

The application should not use fields of type FLD_PTR, FLD_FML32, FLD_MBSTRING, or FLD_FML for the TM_MQO INFIELD or OUTFIELD. These field types will not result in meaningful data being passed to or from the MQ application.

`OUTFIELDVNAME = view32name`

Specifies the name of the VIEW32 subtype used for output to the FML32 OUTFIELD (or the FML32 INFIELD if OUTFIELD is not configured.) OUTFIELDVNAME is allowed only if OUTFIELD and/or INFIELD are also specified.

Defining the TM_MQO SERVER Section (Optional)

The syntax for the SERVER section of the TM_MQO configuration file is as follows in Listing 3-7:

Listing 3-7 Syntax for SERVER section

*SERVER
DEFTIMEOUT=integer
DEFMAXMSGLEN=integer
MINMSGLEVEL=integer
MAXMSGLEVEL=integer

Required Parameters

There are no required parameters in the *SERVER section.

Optional Parameters

`MINMSGLEVEL = integer`

Specifies minimum debug level desired for userlog messages.

`MAXMSGLEVEL = integer`

Specifies maximum debug level desired for userlog messages.

Notes:

The absolute maximum value for MAXMSGLEVEL is 100, however, the highest meaningful value for customer debugging is 30. All the higher values should (only) be used by Oracle Support for deeper analysis or debugging.
Parameters MINMSGLEVEL and MAXMSGLEVEL are intended only for application debugging, and setting MAXMSGLEVEL to a large value can result in excessive output to the ULOG, therefore they have to be used with caution.

Level range for customers:

[10]: The log of message flow, mainly MQPUT log, or major function entry points only.
[20]: Detailed level of tracing. The information of MQ, Service, User, CompCode, and Reason are printed.
[30]: MQGET log in TM_MQI.

`DEFMAXMSGLEN = integer`

Specifies the default maximum message length expected for buffers received by Oracle Tuxedo to WebSphere MQ services. The DEFMAXMSGLEN parameter is overridden by the Service MAXMSGLEN parameter.

`DEFTIMEOUT = integer`

Specifies the default amount of time, in seconds, that is allowed for processing of WebSphere MQ services. The value must be greater than or equal to 0. A value of 0 indicates that the service will not be timed out. The DEFTIMEOUT is overridden by the Service TIMEOUT parameter.

`MAXRETRIES = integer`

Specifies the maximum attempts of connection retry. The minimum and default value is 0, and the maximum value is 2147483647. If MAXRETRIES is set to 0, connection retry is turned off.

Sample TM_MQO.CFG

Listing 3-8 is the sample configuration file for TM_MQO Server.

Listing 3-8 Sample Configuration File for TM_MQO Server

*SERVER
	DEFTIMEOUT=60
	DEFMAXMSGLEN=4096
	MINMSGLEVEL=10
	MAXMSGLEVEL=30

*QUEUE_MANAGER
	LQMID=QM1
	NAME=BEA.TEST.MANAGER

*SERVICE
	NAME=MQTest1
	TIMEOUT=20
	MQNAME=TEST.SAMPLE.ECHO
	REPLYTOQ=TEST.REPLY.QUEUE

*SERVICE
	NAME=MQTest2
	TIMEOUT=15
	REPLYTOQ=TEST.REPLY.QUEUE
	MQNAME=TEST.SAMPLE.TOUPPER

*SERVICE
	NAME=MQTest3
	MQNAME=TEST.NOREPLY.QUEUE
	TRAN=Y
	MAXMSGLEN=1024

Creating the WebSphere MQ to Oracle Tuxedo Server Configuration File

The TM_MQI.CFG file controls the operation of the WebSphere MQ to Oracle Tuxedo server (TM_MQI). Following are the sections of the TM_MQI configuration file and the parameters you can define for each section. A sample configuration file follows the descriptions.

Note: TM_MQI.CFG is a generic filename. You can name this file anything you choose, but the filename must match the -C configuration_file_name parameter you specify in the Oracle Tuxedo UBBCONFIG file. (See Configuring the WebSphere MQ to Oracle Tuxedo Server (TM_MQI) for instructions on configuring the TM_MQI server in the UBBCONFIG file.)

The TM_MQI configuration file is divided into the following required sections:

Queue_Manager

Defines the queue manager name and logical ID.

Note:

The configuration file can only have one QUEUE_MANAGER section.

QUEUE

Defines various parameters for the incoming message queue.

SERVICE

Defines various parameters for the Oracle Tuxedo service.

The TM_MQI configuration file has one optional section:

SERVER

Defines the minimum and maximum settings for services and messages.

Note:

The configuration file can only have one SERVER section.

These sections and the parameters within each section can be in any order in the configuration file, as long as the required sections and parameters are defined.

Defining the TM_MQI QUEUE_MANAGER Section (Required)

The syntax for the QUEUE_MANAGER section of the TM_MQI configuration file is as follows in Listing 3-9:

Listing 3-9 Syntax for QUEUE_MANAGER section

*QUEUE_MANAGER
NAME=string
LQMID=string

Note:

The configuration file can only have one QUEUE_MANAGER section.

Required Parameter

The following parameter must be included in the QUEUE_MANAGER section of the TM_MQO configuration file.

`NAME = string`

Specifies the name of the WebSphere MQ Queue Manager assigned to the queue to be processed by the server. Can contain up to 48 characters, all uppercase. Refer to WebSphere MQ documentation for the specific format of Queue Manager names.

Optional Parameter

The following parameter is optional in the QUEUE_MANAGER section:

`LQMID = string`

Specifies the logical Queue Manager ID. Can contain up to 8 alphanumeric characters, upper and lowercase. If this parameter is specified, it will be included in certain userlog messages.

Defining the TM_MQI QUEUE Section (Required)

The syntax for the QUEUE section of the TM_MQI configuration file is as follows in Listing 3-10:

Listing 3-10 Syntax for QUEUE section

*QUEUE

MQNAME=string

MAXMSGLEN=integer

SERVICE=string

Required Parameters

The following parameter must be included in the QUEUE section of the TM_MQI configuration file:

`MQNAME = string`

Specifies the name of a WebSphere MQ queue to be processed by the server. Can contain up to 48 characters, all uppercase. Refer to WebSphere MQ documentation for specific format of queue names. Note that the MQNAME string should be unique among all of the *QUEUE sections in a particular TM_MQI configuration file.

Optional Parameters

The following parameters are optional:

`MAXMSGLEN = integer`

Specifies the maximum message length expected for MQ queue buffers received by this server. Any message longer than this length read from the WebSphere MQ queue will be sent to the dead letter queue. If this parameter is not set, the value of the SERVER section DEFMAXMSGLEN parameter will be used. If the SERVER section DEFMAXMSGLEN parameter is also not set, the MaxMsgLength value defined for the WebSphere MQ queue will be used.

`SERVICE = string`

Specifies the name of the Oracle Tuxedo service that will process requests received on this queue. If not specified, the value of the Format field in the MQMD structure received from WebSphere MQ will be used as the Oracle Tuxedo service name. In either case, the service name must be defined in the TM_MQI SERVICE section in order for the Oracle Tuxedo service to be invoked.

There are no other parameters in the QUEUE section.

Defining the TM_MQI SERVICE Section (Required)

The syntax for the SERVICE section of the TM_MQI configuration file is as follows in Listing 3-11:

Listing 3-11 Syntax for SERVICE section

*SERVICE

NAME=string

FORMAT=string

TRAN={Y|N}

Required Parameters

The following parameters must be included in the SERVICE section of the TM_MQI configuration file.

`NAME = string`

Specifies the Oracle Tuxedo Service Name. The maximum length of this parameter is the same as the maximum length of an Oracle Tuxedo service name, which is currently 127 characters of mixed case.

`FORMAT = string`

Maps the WebSphere MQ Message Descriptor Format field to the service being called. Can contain up to 8 characters. Refer to WebSphere MQ documentation for specific format of the Message Descriptor Format field. Note that the FORMAT string should be unique among all of the *SERVICE sections in a particular TM_MQI configuration file. If the same FORMAT is used for two or more Oracle Tuxedo services, it is undefined which service the MQ adapter will map that particular FORMAT to.

Optional Parameter

The following parameter is optional.

`TRAN = {Y|N}`

Specifies whether the Service is transactional.

indicates transactional; N indicates non-transactional. Default value is N.

(TM_MQI starts an Oracle Tuxedo transaction before reading each message from a WebSphere MQ queue. If TRAN=Y, the call to the Oracle Tuxedo service is made within this transaction. If TRAN=N, then the call to the Oracle Tuxedo service is made with the TPNOTRAN flag.)

Defining the TM_MQI SERVER Section (Optional)

The syntax for the *SERVER section of the TM_MQI configuration file is as follows in Listing 3-12:

Listing 3-12 Syntax for SERVER section

*SERVER
MINMSGLEVEL=integer
MAXMSGLEVEL=integer
DEFMAXMSGLEN=integer
REPLYONSVCERR={Y|N}
TPESVCFAILDATA={Y|N}
POLINTERVAL=integer
RETRYINTERVAL=integer
MAXRETRIES=integer

Note: The configuration file can only have one *SERVER section.

Required Parameters

There are no required parameters in the *SERVER section.

Optional Parameters

`MINMSGLEVEL = integer`

Specifies minimum debug level desired for userlog messages.

`MAXMSGLEVEL = integer`

Specifies maximum debug level desired for userlog messages.

Notes:

The absolute maximum value for MAXMSGLEVEL is 100, however, the highest meaningful value for customer debugging is 30. All the higher values should (only) be used by Oracle Support for deeper analysis or debugging.
Parameters MINMSGLEVEL and MAXMSGLEVEL are intended only for application debugging, and setting MAXMSGLEVEL to a large value can result in excessive output to the ULOG, therefore they have to be used with caution.

Level range for customers:

[10]: The log of message flow, mainly MQPUT log, or major function entry points only.
[20]: Detailed level of tracing. The information of MQ, Service, User, CompCode, and Reason are printed.
[30]: MQGET log in TM_MQI.

`DEFMAXMSGLEN = integer`

Specifies the default value for the MAXMSGLEN parameter in the *QUEUE section.

`REPLYONSVCERR = {Y|N}`

Specifies if a feedback interpreting errors other than TPEVSCFAIL will be added. The default value is N. When tpcall fails with any tperrno value other than TPESVCFAIL, TM_MQI returns a reply to the reply queue only if REPLYONSVCERR is set so that existing applications that are not checking the Md.Feedback field are not confused the reply content. In this case, TM_MQI sets MQMD Feedback to MQFB_APPL_FIRST+TPERRNO.

When REPLYONSVCERR is set, the MQ Client must check the Md.Feedback field to make sure the reply message is available.

`TPESVCFAILDATA = {Y|N}`

Specifies the manner of handling TPESVCFAIL errors from Oracle Tuxedo with associated non-zero length data. The default value is N.

If TPESVCFAILDATA=N, then any error occurring on tpcall() causes TM_MQI to send the original data sent to tpcall to the MQ dead letter queue, if any. If TPESVCFAILDATA=Y, then TM_MQI returns data to the caller reply queue and will not send the original message to the MQ dead letter queue if tpcall() fails with TPESVCFAIL and a non-zero length reply. TM_MQI sets MQMD Feedback to MQFB_APPL_FIRST+TPESVCFAIL in this case. If an Oracle Tuxedo service call fails with zero-length data or with any tperrno value other than TPESVCFAIL, the original message is sent to the Dead Letter Queue.

`POLINTERVAL = integer`

Specifies the polling interval in milliseconds of the MQ Series in queue for TM_MQI server.

If not specified, the default value is 500. The recommended range is 50 to 500. Setting this one to lower value (0 to 49) may imply a high server load and to a higher value (501 and up) may lead to performance application decrease as the MQ Series incoming request queue will be check out less often and thus introduce delay to process the MQ Series request.

`RETRYINTERVAL = integer`

Specifies reconnection interval (in seconds). The minimum value is 1 and maximum value is 2147483647.

Note: This parameter is only available for multi-threaded TM_MQI.

`MAXRETRIES = integer`

Specifies the maximum attempts of connection retry. The minimum and default value is 0, and the maximum value is 2147483647. If MAXRETRIES is set to 0, connection retry is turned off.

Note: This parameter is only available for multi-threaded TM_MQI.

Sample TM_MQI.CFG

Listing 3-13 shows a TM_MQI Server configuration file example

Listing 3-13 TM_MQI Server Configuration File Example

*SERVER
	MINMSGLEVEL=1
	MAXMSGLEVEL=100

*QUEUE_MANAGER
	LQMID=QM1
	NAME=BEA.TEST.MANAGER

*SERVICE
	NAME=SvcToupper
	FORMAT=UPPER

*SERVICE
	NAME=SvcEcho
	FORMAT=ECHO
	TRAN=Y

*QUEUE
	MQNAME=TEST.SAMPLE.QUEUE1
	MAXMSGLEN=200
*QUEUE
	MQNAME=TEST.SAMPLE.QUEUE2

Creating the enqueue/dequeue Server Configuration File

The TMQUEUE_MQM.CFG file controls the operation of the server that handles tpenqueue and tpdequeue requests (TMQUEUE_MQM). Following are the sections of the TMQUEUE_MQM configuration file and the parameters you can define for each section. A sample configuration file follows the descriptions.

Note: TMQUEUE_MQM.CFG is a generic filename. You can name this file anything you choose, but the filename must match the -C configuration_file_name parameter you specify in the Oracle Tuxedo UBBCONFIG file. (See Configuring the TMQUEUE_MQM Server for instructions on configuring the TMQUEUE_MQM server in the UBBCONFIG file.)

The TMQUEUE_MQM configuration file is divided into the following required sections:

Queue_Manager

Defines the queue manager name and logical ID.

Note:

The configuration file can only have one QUEUE_MANAGER section.

QUEUE

Defines various parameters for the message queue.

The TMQUEUE_MQM configuration file has one optional section:

SERVER

Defines the minimum and maximum debug level and the default maximum message length.

Note:

The configuration file can only have one SERVER section.

These sections and the parameters within each section can be in any order in the configuration file, as long as the required sections and parameters are defined.

Defining the TMQUEUE_MQM QUEUE_MANAGER Section (Required)

The syntax for the QUEUE_MANAGER section of the TMQUEUE_MQM configuration file is as follows in Listing 3-14:

Listing 3-14 Syntax for QUEUE_MANAGER section

*QUEUE_MANAGER
NAME=string
LQMID=string

Note:

The configuration file can only have one QUEUE_MANAGER section.

Required Parameter

The following parameter must be included in the QUEUE_MANAGER section of the TMQUEUE_MQM configuration file:

`NAME = string`

Optional Parameter

`LQMID = string`

Specifies the logical Queue Manager ID. Can contain up to 8 alphanumeric characters, upper and lowercase. If this parameter is specified, it will be included in certain userlog messages.

Defining the TMQUEUE_MQM QUEUE Section (Required)

Listing 3-15 shows the syntax for the QUEUE section of the TMQUEUE_MQM configuration file.

Listing 3-15 Syntax for QUEUE section

*QUEUE
MQNAME=string
TUXNAME=string
MAXMSGLEN=integer

Required Parameters

The following parameters must be included in the QUEUE section of the TMQUEUE_MQM configuration file.

`MQNAME = string`

Specifies the name of a WebSphere MQ queue to be processed by the server. Can contain up to 48 characters, all uppercase. Refer to WebSphere MQ documentation for specific format of queue names.

`TUXNAME = string`

Specifies the name of the queue used for ATMI enqueue/dequeue calls. The maximum length of this parameter is the same as the maximum length of an Oracle Tuxedo queue name, which is currently 127 characters of mixed case. Note that the TUXNAME string should be unique among all of the *QUEUE sections in a particular TMQUEUE_MQM configuration file.

`MAXMSGLEN = integer`

Specifies the maximum message length expected for buffers received from this queue. This parameter overrides the SERVER DEFMAXMSGLEN parameter. If DEFMAXMSGLEN is not specified, then MAXMSGLEN is required.

Defining the TMQUEUE_MQM SERVER Section (Optional)

Listing 3-16 shows the syntax for the SERVER section of the TMQUEUE_MQM configuration file.

Listing 3-16 Syntax for SERVER section

*SERVER
MINMSGLEVEL=integer
MAXMSGLEVEL=integer
DEFMAXMSGLEN=integer

Note:

The configuration file can only have one SERVER section.

Required Parameters

There are no required parameters in the SERVER section.

Optional Parameters

`MINMSGLEVEL = integer`

Specifies minimum debug level desired for userlog messages.

`MAXMSGLEVEL = integer`

Specifies maximum debug level desired for userlog messages.

Notes:

The absolute maximum value for MAXMSGLEVEL is 100, however, the highest meaningful value for customer debugging is 30. All the higher values should (only) be used by Oracle Support for deeper analysis or debugging.
Parameters MINMSGLEVEL and MAXMSGLEVEL are intended only for application debugging, and setting MAXMSGLEVEL to a large value can result in excessive output to the ULOG, therefore they have to be used with caution.

Level range for customers:

[10]: The log of message flow, mainly MQPUT log, or major function entry points only.
[20]: Detailed level of tracing. The information of MQ, Service, User, CompCode, and Reason are printed.
[30]: MQGET log in TM_MQI.

`DEFMAXMSGLEN = integer`

Specifies the default maximum message length expected for buffers received from WebSphere MQ queues. The DEFMAXMSGLEN parameter is overridden by the QUEUE section MAXMSGLEN parameter.

Sample TMQUEUE_MQM.CFG

Listing 3-17 shows TMQUEUE_MQM Server configuration file example.

Listing 3-17 TMQUEUE_MQM Server Configuration File Example

*SERVER
	DEFMAXMSGLEN=4096

*QUEUE_MANAGER
	LQMID=QM1
	NAME=BEA.TEST.MANAGER


*QUEUE
	TUXNAME=MQTest1
	MQNAME=TEST.NOREPLY.QUEUE

*QUEUE
	TUXNAME=MQEcho
	MQNAME=TEST.SAMPLE.ECHO
	MAXMSGLEN=2048

*QUEUE
	TUXNAME=MQReply
	MQNAME=TEST.REPLY.QUEUE

Configuring the WebSphere MQ Queue Manager

You must configure the WebSphere MQ queue manager in order to run the MQ Adapter for Oracle Tuxedo. Refer to your WebSphere MQ documentation for specific instructions on configuring queue managers.