![]() |
![]() |
![]() |
![]() |
![]() |
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:Listing 3‑1 Syntax for TM_MQO Server Definition in UBBCONFIGFor 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.Listing 3‑2 Syntax for field definition table for TM_MQO
• 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.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 UBBCONFIGCLOPT= "-- -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:Listing 3‑4 Syntax for TMQUEUE_MQM Definition in UBBCONFIGTMQUEUE_MQM SRVGRP="identifier" SRVID="number" REPLYQ=N CLOPT="-- -C configuration_file_name"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.
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 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 sectionNAME=stringLQMID=stringListing 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
•
• Otherwise, TM_MQO will log an error message and call tpreturn() with TPFAIL.Listing 3‑7 Syntax for SERVER section
• 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.
• [10]: The log of message flow, mainly MQPUT log, or major function entry points only.
• 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.Listing 3‑8 is the sample configuration file for TM_MQO Server.Listing 3‑8 Sample Configuration File for TM_MQO ServerNote: 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 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 sectionListing 3‑10 Syntax for QUEUE sectionSpecifies 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.Listing 3‑11 Syntax for SERVICE section(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.)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.There are no required parameters in the *SERVER section.
• 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.
• [10]: The log of message flow, mainly MQPUT log, or major function entry points only.
• 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.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.
Note: 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: Listing 3‑13 shows a TM_MQI Server configuration file exampleListing 3‑13 TM_MQI Server Configuration File ExampleThe 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 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 sectionListing 3‑15 shows the syntax for the QUEUE section of the TMQUEUE_MQM configuration file.Listing 3‑15 Syntax for QUEUE sectionListing 3‑16 shows the syntax for the SERVER section of the TMQUEUE_MQM configuration file.Listing 3‑16 Syntax for SERVER section
• 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.
• [10]: The log of message flow, mainly MQPUT log, or major function entry points only.
• Listing 3‑17 shows TMQUEUE_MQM Server configuration file example.Listing 3‑17 TMQUEUE_MQM Server Configuration File Example