Configuring eLink Adapter for MQSeries

Configuring the environment for eLink Adapter for MQSeries consists of the following basic tasks:

Configuring the TUXEDO Servers

The eLink Adapter for MQSeries consists of three TUXEDO servers: an eLink to MQSeries server (ELINKMQO), an MQSeries to eLink server (ELINKMQI), and a server for handling tpenqueue() and tpdequeue() requests (TMQUEUE_MQM). You must identify each of these servers in the TUXEDO UBBCONFIG file. In addition, the eLink 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 provided on the eLink Adapter for MQSeries installation CD-ROM. You can use these samples 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 TUXEDO UBBCONFIG file, and how to set up the configuration file required by the eLink Adapter for each of these servers.

Configuring the eLink to MQSeries Server (ELINKMQO)

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

You define the ELINKMQO server in the SERVERS section of the TUXEDO UBBCONFIG file as follows:

Listing 3-1 Syntax for ELINKMQO Server Definition in UBBCONFIG

*SERVER
ELINKMQO SRVGRP="identifier" SRVID="number"
CLOPT="-- -C configuration_file_name"

For information about the SRVGRP, SRVID, and CLOPT parameter syntax and definitions, refer to the BEA TUXEDO Reference Manual.

CLOPT= "-- -C eLink to MQSeries configfile": specifies the server's configuration file.

A configuration file provides a list of services and their associated parameters to the server at startup. The sample configuration file included on the installation CD-ROM for ELINKMQO is called ELINKMQO.CFG. Refer to "Creating the Server Configuration Files" for an explanation of the parameters you need to define.

Defining FML32 Fields for the eLink to MQSeries Server

You must also define FML32 fields for ELINKMQO in a field definition table. BEA eLink Platform uses FML functions to manipulate fielded buffers related to errors. Refer to the BEA TUXEDO FML Programmer's Guide for more information on FML32.

The syntax for the field definition table for ELINKMQO is as follows:

Listing 3-2 Syntax for field definition table for ELINKMQO

# name                  number    type    flags   comments

ELINK_ADAPTER_ERR        `n'     string      -        -

ELINK_ADAPTER_ERR_CODE   `n'     string      -        -

ELINK_APP_ERR            `n'     string      -        -

The FML32 fields you need to define are as follows.

ELINK_ADAPTER_ERR: stores the details of the errors specific to the eLink Adapter for MQSeries.
ELINK_ADAPTER_ERR_CODE: stores the category code for the adapter-specific errors.
ELINK_APP_ERR: stores the details of the errors specific to MQSeries.

A sample field definition table (elinkadk.fml) is included on the installation CD-ROM. You can edit this file to assign field ID numbers that are appropriate for your installation.

Note: Make sure the field ID numbers you assign do not conflict with any other field ID numbers you may have for other applications.

When you have created the field definition table, copy it to the directory defined in the environment variable FLDTBLDIR32 and update the environment variable to include this file (elinkadk.fml). Refer to the BEA TUXEDO Reference Manual for more information on environment variables.

Configuring the MQSeries to eLink Server (ELINKMQI)

ELINKMQI forwards messages requested from MQSeries applications to TUXEDO services. The application queues a request to a designated queue that is monitored by ELINKMQI. The requested service is specified in the message descriptor. Like ELINKMQO, ELINKMQI 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 ELINKMQI server in the SERVERS section of the TUXEDO UBBCONFIG file as follows:

Listing 3-3 Syntax for ELINKMQI Definition in UBBCONFIG

*SERVER
ELINKMQI="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 BEA TUXEDO Reference Manual.

CLOPT= "-- -C MQSeries to eLink configfile": specifies the server's configuration file.

A configuration file provides a list of services and their associated parameters to the server at startup. The sample configuration file included on the installation CD-ROM for ELINKMQI is called ELINKMQI.CFG. Refer to "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 TUXEDO applications that need to send or retrieve data to or from an MQSeries queue.

You define the TMQUEUE_MQM server in the SERVERS section of the TUXEDO UBBCONFIG file as follows:

Listing 3-4 Syntax for TMQUEUE_MQM Definition in UBBCONFIG

*SERVER
TMQUEUE_MQM="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 BEA TUXEDO Reference Manual.

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

A configuration file provides a list of services and their associated parameters to the server at startup. The sample configuration file included on the installation CD-ROM for TMQUEUE-MQM is called TMQUEUE-MQM.CFG. Refer to "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 eLink Adapter for MQSeries servers. The installation CD-ROM contains 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 eLink to MQSeries Server Configuration File

The ELINKMQO.CFG file controls the operation of the eLink to MQSeries server (ELINKMQO). Following are the sections of the ELINKMQO configuration file and the parameters you can define for each section. A sample configuration file follows the descriptions.

Note: ELINKMQO.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 TUXEDO UBBCONFIG file. (See Configuring the eLink to MQSeries Server (ELINKMQO) for instructions on configuring the ELINKMQO server in the UBBCONFIG file.)

The ELINKMQO 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 ELINKMQO 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 QUEUE_MANAGER Section (Required)

The syntax for the QUEUE_MANAGER section of the ELINKMQO configuration file is as follows:

Listing 3-5 Syntax for QUEUE_MANAGER section

*QUEUE_MANAGER

LQMID=string
NAME=string

Note: The configuration file can only have one QUEUE_MANAGER section. Required Parameters

The following parameters must be included in the QUEUE_MANAGER section of the ELINKMQO configuration file.

LQMID= string: Specifies the logical Queue Manager ID for mapping Queues to the QUEUE_MANAGER. Can contain up to 8 alphanumeric characters, upper and lowercase.
NAME= string: Specified the name of the MQSeries Queue Manager. Can contain up to 48 characters, all uppercase. Refer to MQSeries documentation for the specific format of Queue Manager names. Optional Parameters

There are no optional parameters for the QUEUE_MANAGER section.

Defining the SERVICE Section (Required)

The syntax for the SERVICE section of the ELINKMQO configuration file is as follows:

Listing 3-6 Syntax for SERVICE section

*SERVICE

NAME=string

MQNAME=string

LQMID=string
FORMAT=string

TRAN=Y/N

MAXMSGLEN=integer

REPLYTOQ=string

TIMEOUT=integer

INFIELD=string

OUTFIELD=string

Required Parameters

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

NAME = string: Specifies the TUXEDO Service Name. Can contain up to a maximum of 15 characters, upper or lowercase.
MQNAME = string: Specifies the name of the MQSeries Queue. Can contain up to a maximum of 48 characters, all uppercase. Refer to MQSeries documentation for the specific format of Queue names.
LQMID = string: Specifies the logical queue manager ID for mapping the SERVICE queue defined by MQNAME to a QUEUE_MANAGER section. Can contain up to 8 alphanumeric characters, upper and lowercase.
MAXMSGLEN = integer: Specifies the maximum message length expected for buffers received by this service. 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 service. The value must be greater than or equal to 0. A value of 0 indicates that the service will not be timed out.

Required parameter unless DEFTIMEOUT is specified in the SERVER section. Optional Parameters

The following parameters are optional.

FORMAT = string: Maps to the MQSeries Message Descriptor Format. Can contain up to 8 characters. Refer to MQSeries 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.; Default value is N.
REPLYTOQ = string: Specifies the name of the MQSeries Reply To Queue. Can contain up to 48 characters, all uppercase. Refer to MQSeries 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, all requests for this service must pass FML32 buffers for input.
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.

Defining the SERVER Section (Optional)

The syntax for the SERVER section of the ELINKMQO configuration file is as follows:

Listing 3-7 Syntax for SERVERS section

*SERVER

 DEFTIMEOUT=integer

 DEFMSGLEN=integer

 MINMSGLEVEL=integer

 MAXMSGLEVEL=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 ADKDebug logging.
MAXMSGLEVEL = integer: Specifies maximum debug level desired for ADKDebug logging.
DEFMAXMSGLEN = integer: Specifies the default maximum message length expected for buffers received by eLink to MQSeries services. The DEFMAXMSGLEN is overridden by the Service MAXMSGLEN parameter.
DEFTIMEOUT = integer: Specifies the amount of time, in seconds, that is allowed for processing of the indicated service. 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.

Sample ELINKMQO.CFG

Listing 3-8 Sample Configuration File for ELINKMQO Server

*SERVER

    DEFTIMEOUT=60

    DEFMSGLEN=4096

    MINMSGLEVEL=10

    MAXMSGLEVEL=30

*QUEUE_MANAGER

    LQMID=QM1

    NAME=BEA.TEST.MANAGER

*SERVICE

    NAME=MQTest1

    LQMID=QM1

    TIMEOUT=20

    MQNAME=TEST.SAMPLE.ECHO

    REPLYTOQ=TEST.REPLY.QUEUE

*SERVICE

    NAME=MQTest2

    LQMID=QM1

    TIMEOUT=15

    REPLYTOQ=TEST.REPLY.QUEUE

    MQNAME=TEST.SAMPLE.TOUPPER

*SERVICE

    NAME=MQTest3

    LQMID=QM1

    MQNAME=TEST.NOREPLY.QUEUE

    TRAN=YES

    MAXMSGLEN=1024

Creating the MQSeries to eLink Server Configuration File

The ELINKMQI.CFG file controls the operation of the MQSeries to eLink server (ELINKMQI). Following are the sections of the ELINKMQI configuration file and the parameters you can define for each section. A sample configuration file follows the descriptions.

Note: ELINKMQI.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 TUXEDO UBBCONFIG file. (See Configuring the MQSeries to eLink Server (ELINKMQI) for instructions on configuring the ELINKMQI server in the UBBCONFIG file.)

The ELINKMQI 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 TUXEDO service.

The ELINKMQI configuration file has one optional section:

SERVER

Defines the minimum and maximum debug level.
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 QUEUE_MANAGER Section (Required)

The syntax for the QUEUE_MANAGER section of the ELINKMQI configuration file is as follows:

Listing 3-9 Syntax for QUEUE_MANAGER section

*QUEUE_MANAGER

LQMID=string
NAME=string

Note: The configuration file can only have one QUEUE_MANAGER section. Required Parameters

The following parameters must be included in the QUEUE_MANAGER section of the ELINKMQO configuration file.

LQMID = string: Specifies the logical Queue Manager ID for mapping Queue Managers to queues. Can contain up to 8 alphanumeric characters, upper and lowercase.
NAME = string: Specified the name of the MQSeries Queue Manager assigned to the queue to be processed by the server. Can contain up to 48 characters, all uppercase. Refer to MQSeries documentation for the specific format of Queue Manager names. Optional Parameters

There are no optional parameters for the QUEUE_MANAGER section.

Defining the QUEUE Section (Required)

The syntax for the QUEUE section of the ELINKMQI configuration file is as follows:

Listing 3-10 Syntax for QUEUE section

*QUEUE_MANAGER

LQMID=string
MQNAME=string

MAXMSGLEN=integer

Required Parameters

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

LQMID = string: Specifies the logical Queue Manager ID for mapping Queue Managers to Queues. Can contain up to 8 alphanumeric characters, upper and lowercase.
MQNAME = string: Specifies the name of an MQSeries queue to be processed by the server. Can contain up to 48 characters, all uppercase. Refer to MQSeries documentation for specific format of queue names.
MAXMSGLEN = integer: Specifies the maximum message length expected for queue buffers received by this server. Optional Parameters

There are no optional parameters for the QUEUE section.

Defining the SERVICE Section (Required)

The syntax for the SERVICE section of the ELINKMQI configuration file is as follows:

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 ELINKMQI configuration file.

NAME = string: Specifies the TUXEDO Service Name. Can contain up to a maximum of 15 characters, upper or lowercase.
FORMAT = string: Maps the MQSeries Message Descriptor Format field to the service being called. Can contain up to 8 characters. Refer to MQSeries documentation for specific format of the Message Descriptor Format field. Optional Parameters

The following parameters are optional.

TRAN = {Y|N}: Specifies whether the Service is transactional. Y indicates transactional; N indicates non-transactional.; Default value is N.

Defining the SERVER Section (Optional)

The syntax for the SERVER section of the ELINKMQI configuration file is as follows:

Listing 3-12 Syntax for SERVER section

*SERVER

 MINMSGLEVEL=integer

 MAXMSGLEVEL=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 ADKDebug logging.
MAXMSGLEVEL = integer: Specifies maximum debug level desired for ADKDebug logging.

Sample ELINKMQI.CFG

Listing 3-13 Sample Configuration File for ELINKMQI Server

*SERVER

    MINMSGLEVEL=1

    MAXMSGLEVEL=100

*QUEUE_MANAGER

    LQMID=QM1

    NAME=BEA.TEST.MANAGER

*SERVICE

    NAME=SvcToupper

    FORMAT=UPPER

*SERVICE

    NAME=SvcEcho

    FORMAT=ECHO

    TRAN=YES

*QUEUE

    MQNAME=TEST.SAMPLE.QUEUE1

    LQMID=QM1

    MAXMSGLEN=200

*QUEUE

    MQNAME=TEST.SAMPLE.QUEUE2

    LQMID=QM1

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 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 incoming message queue.

The TQMQUEUE_MQM configuration file has one optional section:

SERVER

Defines the minimum and maximum debug level and the default 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 QUEUE_MANAGER Section (Required)

The syntax for the QUEUE_MANAGER section of the TQMQUEUE_MQM configuration file is as follows:

Listing 3-14 Syntax for QUEUE_MANAGER section

*QUEUE_MANAGER

LQMID=string
NAME=string

Note: The configuration file can only have one QUEUE_MANAGER section. Required Parameters

The following parameters must be included in the QUEUE_MANAGER section of the TQMQUEUE_MQM configuration file.

LQMID = string: Specifies the logical Queue Manager ID for mapping Queue Managers to queues. Can contain up to 8 alphanumeric characters, upper and lowercase.
NAME = string: Specifies the name of the MQSeries Queue Manager assigned to the queue to be processed by the server. Can contain up to 48 characters, all uppercase. Refer to MQSeries documentation for the specific format of Queue Manager names. Optional Parameters

There are no optional parameters for the QUEUE_MANAGER section.

Defining the QUEUE Section (Required)

The syntax for the QUEUE section of the TQMQUEUE_MQM configuration file is as follows:

Listing 3-15 Syntax for QUEUE section

*QUEUE_MANAGER

LQMID=string
MQNAME=string

TUXNAME=string

MAXMSGLEN=integer

Required Parameters

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

LQMID = string: Specifies the logical Queue Manager ID for mapping Queue Managers to Services. Can contain up to 8 alphanumeric characters, upper and lowercase.
MQNAME = string: Specifies the name of an MQSeries queue to be processed by the server. Can contain up to 48 characters, all uppercase. Refer to MQSeries documentation for specific format of queue names.
TUXNAME = string: Specifies the name of the queue used for ATMI enqueue/dequeue calls. Can contain up to 15 charaters. Optional Parameters

The following parameter is optional for the QUEUE_MANAGER section of the

MAXMSGLEN = integer: Specifies the maximum message length expected for this queue. Value must be less than or equal to the MaxMsgLength of the MQSeries Queue. This parameter overrides the SERVER DEFMAXMSGLEN parameter.

Defining the SERVER Section (Optional)

The syntax for the SERVER section of the TQMQUEUE_MQM configuration file is as follows:

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 ADKDebug logging.
MAXMSGLEVEL = integer: Specifies maximum debug level desired for ADKDebug logging.
DEFMAXMSGLEN=integer: Specifies the default maximum message length expected for buffers received by the Queues. The DEFMAXMSGLEN is overridden by the QUEUE MAXMSGLEN parameter. Value must be less than or equal to the MaxMsgLength parameter specified for the MQSeries Queue.

Sample TMQUEUE_MQM.CFG

Listing 3-17 Sample Configuration File for the TMQUEUE_MQM Server

*SERVER

    DEFMAXMSGLEN=4096

*QUEUE_MANAGER

    LQMID=QM1

    NAME=BEA.TEST.MANAGER

*QUEUE

    TUXNAME=MQTest1

    LQMID=QM1

    MQNAME=TEST.NOREPLY.QUEUE

*QUEUE

    TUXNAME=MQEcho

    LQMID=QM1

    MQNAME=TEST.SAMPLE.ECHO

    MAXMSGLEN=2048

*QUEUE

    TUXNAME=MQReply

    LQMID=QM1

    MQNAME=TEST.REPLY.QUEUE

Configuring the MQSeries Queue Manager

You must configure the MQSeries queue manager in order to run the eLink Adapter for MQSeries. Refer to your MQSeries documentation for specific instructions on configuring queue managers.

[Table of Contents] [Prev] [Next]