![]() ![]() ![]() ![]() ![]() ![]() |
This chapter contains the following topics:
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.
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:
*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.
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:
# 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:
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.
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:
*SERVERS
identifier
TM_MQI SRVGRP="" 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.
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:
*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.
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.
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:
The TM_MQO configuration file has one optional 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.
The syntax for the QUEUE_MANAGER section of the TM_MQO configuration file is as follows in Listing 3-5:
*QUEUE_MANAGER
NAME=string
LQMID=string
Note: | The configuration file can only have one QUEUE_MANAGER section. |
The following parameter must be included in the QUEUE_MANAGER section of the TM_MQO configuration file.
NAME= string
The following parameter is optional:
LQMID= string
The syntax for the SERVICE section of the TM_MQO configuration file is as follows in Listing 3-6:
*SERVICE
string
NAME=MQNAME=string
FORMAT=string
TRAN={Y/N}
MAXMSGLEN=integer
REPLYTOQ=string
TIMEOUT=integer
EXPIRE=integer
PRIORITY=integer
INFIELD=string
OUTFIELD=string
OUTFIELDVNAME=string
The following parameters must be included in the SERVICE section of the TM_MQO configuration file.
NAME = string
MQNAME = string
MAXMSGLEN = integer
TIMEOUT = integer
The following parameters are optional.
EXPIRE = integer
PRIORITY = integer
FORMAT = string
TRAN = {Y|N}
REPLYTOQ = string
INFIELD = string
OUTFIELD = string
OUTFIELDVNAME = view32name
The syntax for the SERVER section of the TM_MQO configuration file is as follows in Listing 3-7:
*SERVER
DEFTIMEOUT=integer
DEFMAXMSGLEN=integer
MINMSGLEVEL=integer
MAXMSGLEVEL=integer
There are no required parameters in the *SERVER section.
MINMSGLEVEL = integer
MAXMSGLEVEL = integer
Notes: |
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.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.DEFMAXMSGLEN = integer
DEFTIMEOUT = integer
MAXRETRIES = integer
MAXRETRIES
is set to 0, connection retry is turned off.
Listing 3-8 is the 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
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:
The TM_MQI configuration file has one optional 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.
The syntax for the QUEUE_MANAGER section of the TM_MQI configuration file is as follows in Listing 3-9:
*QUEUE_MANAGER
NAME=string
LQMID=string
Note: | The configuration file can only have one QUEUE_MANAGER section. |
The following parameter must be included in the QUEUE_MANAGER section of the TM_MQO configuration file.
NAME = string
The following parameter is optional in the QUEUE_MANAGER section:
LQMID = string
The syntax for the QUEUE section of the TM_MQI configuration file is as follows in Listing 3-10:
*QUEUE
MQNAME=string
MAXMSGLEN=integer
SERVICE=string
The following parameter must be included in the QUEUE section of the TM_MQI configuration file:
MQNAME = string
The following parameters are optional:
MAXMSGLEN = integer
MaxMsgLength
value defined for the WebSphere MQ queue will be used.
SERVICE = string
There are no other parameters in the QUEUE section.
The syntax for the SERVICE section of the TM_MQI configuration file is as follows in Listing 3-11:
*SERVICE
NAME=string
FORMAT=string
TRAN={Y|N}
The following parameters must be included in the SERVICE section of the TM_MQI configuration file.
NAME = string
FORMAT = string
The following parameter is optional.
TRAN = {Y|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.)
The syntax for the *SERVER
section of the TM_MQI
configuration file is as follows in Listing 3-12:
*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. |
There are no required parameters in the *SERVER
section.
MINMSGLEVEL = integer
MAXMSGLEVEL = integer
Notes: |
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.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.DEFMAXMSGLEN = integer
REPLYONSVCERR = {Y|N}
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
.
REPLYONSVCERR
is set, the MQ Client must check the Md.Feedback
field to make sure the reply message is available.
TPESVCFAILDATA = {Y|N}
TPESVCFAIL
errors from Oracle Tuxedo with associated non-zero length data. The default value is N
.
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
RETRYINTERVAL = integer
Note: | This parameter is only available for multi-threaded TM_MQI . |
MAXRETRIES = integer
MAXRETRIES
is set to 0, connection retry is turned off.
Note: | This parameter is only available for multi-threaded TM_MQI . |
Listing 3-13 shows a 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
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:
The TMQUEUE_MQM configuration file has one optional 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.
The syntax for the QUEUE_MANAGER section of the TMQUEUE_MQM configuration file is as follows in Listing 3-14:
*QUEUE_MANAGER
NAME=string
LQMID=string
Note: | The configuration file can only have one QUEUE_MANAGER section. |
The following parameter must be included in the QUEUE_MANAGER section of the TMQUEUE_MQM configuration file:
NAME = string
LQMID = string
Listing 3-15 shows the syntax for the QUEUE section of the TMQUEUE_MQM configuration file.
*QUEUE
MQNAME=string
TUXNAME=string
MAXMSGLEN=integer
The following parameters must be included in the QUEUE section of the TMQUEUE_MQM configuration file.
MQNAME = string
TUXNAME = string
MAXMSGLEN = integer
Listing 3-16 shows the syntax for the SERVER section of the TMQUEUE_MQM configuration file.
*SERVER
MINMSGLEVEL=integer
MAXMSGLEVEL=integer
DEFMAXMSGLEN=integer
Note: | The configuration file can only have one SERVER section. |
There are no required parameters in the SERVER section.
MINMSGLEVEL = integer
MAXMSGLEVEL = integer
Notes: |
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.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.DEFMAXMSGLEN = integer
Listing 3-17 shows 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
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.
![]() ![]() ![]() |