Configuring BEA MessageQ MQSeries Connection


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs.beasys.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

MessageQ Doc Home \| MQSeries Connection User's Guide \| Previous Topic \| Next Topic \| Contents \| Index

This chapter describes the tasks required to define queues and configure your system to support BEA MessageQ MQSeries Connection, including:

Overview of Configuration Tasks

Before you configure BEA MessageQ MQSeries Connection, familiarize yourself with the BEA MessageQ and IBM MQSeries applications and queues that your application will access. Specifically, you must know the following:

Types of messages to be passed (datagram, request, reply, control, undefined)
Direction of the message flow between applications
The name of the LSQ, which serves as the intermediate queue for messages
The name of the RSQ, which serves as the final target queue for messages
The message queuing system used for each application and queue

After you know these elements of your application, configure each message queuing system according to the instructions provided with the message queuing system, as follows:

To configure BEA MessageQ, set up the BEA MessageQ group initialization file.
To configure IBM MQSeries, modify the IBM MQSeries queue definitions with the appropriate LSQ and RSQ information.

After you complete the configuration for each message queuing system, configure BEA MessageQ MQSeries Connection using the QMB configuration file.

The BEA MessageQ MQSeries Connection media kit contains programming examples of an IBM MQSeries-to-BEA MessageQ application. It also contains example configuration and initialization files which support the programming examples. These files are as follows:

dmc500_config.dat-the QMB configuration file in which the LSQ to RSQ relationship is defined.
dmc500_dmq_group.init-group initialization file that contains all the QCT entries needed to execute the QMB and programming examples.

The programming examples and supporting files are located in:

/install_dir/examples/mqsc on UNIX systems
dev:\install_dir\examples\mqsc on Windows NT systems

Use programming examples and supporting files to help you understand how to configure the BEA MessageQ MQSeries Connection software. For more information on the programming examples, see Programming Examples.

Configuring BEA MessageQ

For each BEA MessageQ message queuing group that communicates with an IBM MQSeries application, you must set up a BEA MessageQ group initialization file (group.init).

The BEA MessageQ group initialization file that supports a QMB set must include the appropriate queue definitions required for the QMB servers and all available BEA MessageQ local services.

A QMB set requires the following queue entries in the QCT section of the group initialization file:

A permanent primary queue named QMBDM. This is the queue to which the BEA MessageQ to IBM MQSeries QMB server (QMBDM) attaches.
A permanent primary queue named QMBMD. This is the queue to which the IBM MQSeries to BEA MessageQ QMB server (QMBMD) attaches.
A permanent multireader queue. This is the BEA MessageQ reply queue. The name of this queue must be DMQ_r, where r is the value passed in the -r qname parameter of the QMB start command. For example, if you specify -r REPLYQ, then the actual BEA MessageQ queue name is DMQ_REPLYQ. For more information on the -r parameter, see Starting the Queue Message Bridge in Managing the BEA MessageQ MQSeries Connection Environment.

The group initialization file must also include a QCT entry for each LSQ "owned" by BEA MessageQ. All LSQ queues must be defined as permanent multireader queues.

Listing 3-1 provides an example of a BEA MessageQ initialization file queue entry section. In this example, the QMBDM, QMBMD, and DMQ_REPLYQ are required queues for the QMB server. The queues LSQ_TEST and MQS_ECHO are LSQs and DMQ_ECHO_SERVER is an RSQ.

Listing 3-1 BEA MessageQ Configuration File Queue Entry Section

!QUEUE CONFIGURATION SECTION
!
% QCT

!Queue         Queue  Byte   Msg   Quota  UCB  Queue Owner Conf  Perm   Name Security
!Name          Number Quota  Quota Enable Send Type  Queue Style Active Scope
!
QMBDM             8   64000  100    None   .    P     0     .     N      L    N
QMBMD             9   64000  100    None   .    P     0     .     N      L    N
DMQ_DMC_REPLYQ    7   64000  100    None   .    M     0     .     Y      L    N
LSQ_TEST         11   32000   10    None   .    M     0     .     Y      L    N
MQS_ECHO         12   64000  100    None   .    M     0     .     Y      L    N
DMQ_ECHO_SERVER  15   64000  100    None   .    M     0     .     N      L    N

Note that the actual values of Queue Number, Byte Quota, and Msg Quota for each entry are determined by other existing queue configuration entries, message sizes, and arrival rate calculations for the QMB application.

If your application requires multiple QMB servers, the additional servers attach to BEA MessageQ Temporary Primary Queues (TPQs) and associate themselves with the appropriate permanent QMB server. No BEA MessageQ configuration entries are required when using TPQs with additional instances of a QMB server.

See the BEA MessageQ installation and configuration documentation for your platform for more information on configuring the BEA MessageQ product.

Group Name Table

Any BEA MessageQ service that is not local to the group with the QMB must have an entry in the group name table. This table allows BEA MessageQ MQSeries Connection to locate the actual queue address when it processes the RSQ entries in the QMB configuration file.

Note: The QMB supports only local name scope lookups. Global name scope lookups are not supported.

For example, suppose DMQ_ECHO_SERVER, as defined in the QMB configuration file, does not reside in the BEA MessageQ group defined previously. In this case, BEA MessageQ MQSeries Connection requires a group name table entry to allow address resolution. If the DMQ_ECHO_SERVER program is on a remote group such as group 5/queue 24, the entry is as follows:

%GNT

!Name              Address      Scope

DMQ_ECHO_SERVER    5.24          L

The appropriate BEA MessageQ cross-group configuration entries must be in place to allow access to remote services, which are offered in other BEA MessageQ groups.

See the BEA MessageQ installation and configuration documentation for your platform for more information on configuring the BEA MessageQ product.

Configuring IBM MQSeries

This topic describes how to configure IBM MQSeries to use BEA MessageQ MQSeries Connection. It includes the following tasks:

Configuring the Required IBM MQSeries Queues
Defining IBM MQSeries Queues

Configuring the Required IBM MQSeries Queues

A QMB set requires the configuration of an IBM MQSeries permanent shared queue for an IBM MQSeries reply queue and all offered LSQs. These queues must be configured in the Message Queue Manager (MQM) to which the QMB connects. They must have the same characteristics as the IBM MQSeries queue model defined in Listing 3-2.

The reply queue name must be MQS_r, where r is the value passed in the -r parameter of the QMB startup command line. The QMB prefixes the constant MQS_ to the -r parameter for a complete name. For more information on the -r parameter, see Starting the Queue Message Bridge in Managing the BEA MessageQ MQSeries Connection Environment.

Each LSQ that the QMB services must also be defined in the MQM.

Listing 3-2 shows a sample definition of the QMODEL for an IBM MQSeries LSQ. The source for this model is located in /install_dir/templates on UNIX systems and in dev:\install_dir\templates\mqsc on Windows NT systems. This model may be copied to the MQM configuration file or added manually. To add it manually, use the define and alter commands from the runmqsc IBM MQSeries utility.

Listing 3-2 MQSeries Queue Definition

DEFINE QMODEL(`QMBLSQ') 							+
	DESCR(`QMB Local Service Queue Model')						+
	PUT(ENABLED)						+
	DEFPRTY(0)						+
	DEFPSIST(NO)						+
	GET(ENABLED)						+
	MAXDEPTH(5000)						+
	MAXMSGL(4194304)					+
	SHARE					+
	DEFSOPT(SHARED)					+
	MSGDLVSQ(PRIORITY)					+
	USAGE(NORMAL)					+
	NOTRIGGER					+
	RETINTVL(999999999)					+
	BOTHRESH(0)					+
	BONAME(` `)					+
	SCOPE(QMGR)					+
	QDEPTHHI(80)					+
	QDEPTHLO(20)					+
	QDPMAXEV(ENABLED)					+
	QDPHIEV(DISABLED)					+
	QDPLOEV(DISABLED)					+
	QSVCINT(999999999)					+
	QSVCIEV(NONE)

Note: The plus sign in Listing 3-2 is an IBM line continuation character.

Defining IBM MQSeries Queues

You can modify the Message Queue Manager configuration by either executing the runmqsc utility interactively or editing and loading the command file associated with the MQM. See MQSeries Command Reference and MQSeries System Administration for more information.

You can add the QMODEL defined in Listing 3-2 to the command file, and then use the QMODEL in defining the QMB required queues with the runmqsc utility.

To define the IBM MQSeries reply queue, enter the following command:
```
DEFINE QLOCAL(MQS_REPLYQ) LIKE(QMBLSQ)
```
To define an IBM MQSeries LSQ for the echo program, enter the following command:
```
DEFINE QLOCAL(DMQ_ECHO) LIKE(QMBLSQ)
```

Any remote service offered on the local MQM must be defined as QLOCAL. Any remote service that is not on the local MQM must be defined as QREMOTE to allow the messages be forwarded to it. Also, all Distributed Queue Manager (DQM) definitions (channels, xmitq, and others) must exist and be active to allow IBM MQSeries distributed processing to occur.

A template file defining all the IBM MQSeries queues required to run the programming examples is located in /install_dir/templates/dmc500_mqmdef.cfg on UNIX systems and in dev:\install_dir\templates\dmc500_mqmdef.cfg on Windows NT systems.

To load the MQM with the required commands, so that the example QMB queue definitions are included, enter the following command:

runmqsc YOURMQMNAME < dmc500_mqmdef.cfg > mqmdef.out

The mqmdef.out file contains the results of the command executions.

Tips for Configuring IBM MQSeries

Note the following tips when configuring an IBM MQSeries queue:

An IBM MQSeries transmit queue must have a depth greater than the maximum message batch that can ever be received. If it does not, the queue reaches MAXDEPTH and the channel shuts down.
IBM MQSeries queues are created in the following directories:
```
/var/mqm/qmgrs/QNAME/queues on UNIX systems
```
```
dev:\mqm\qmgrs\QNAME\QUEUES on Windows NT systems
```
A queue can grow to the maximum size of (MAXDEPTH * largest_message_received). IBM MQSeries requires that the file system that it is installed on be able to support the expected message volume.
An IBM MQSeries channel must be started manually or triggered by placing a message in the channels transmit queue (assuming the channel is configured to allow triggering). If a channel is triggered, the channel initialization program must be active and properly configured.

See the MQSeries Command Reference for detailed information on how to configure IBM MQSeries software.

Configuring the Queue Message Bridge

Use the QMB configuration file to define the services offered by one messaging system to the other. The QMB processes read the configuration file and set up an association between an LSQ and an RSQ. This association can be established statically or dynamically. An LSQ is a queue that is local to the messaging system of the sending application. An RSQ is a queue that is remote to the messaging system of the sending application and is the final target of all messages received on the associated LSQ. Configuration files for MQSeries Connection Version 5.0 also include priority mapping information.

The QMB configuration file is an ASCII text file that may be located in any directory. Parameters within the file are separated by white space. An example configuration file, named dmc500_config.dat, is located in /install_dir/templates on UNIX systems and in dev:\install_dir\templates on Windows NT systems.

A configuration file for MQSeries Connection Version 4.0A includes only the parameters required to associate an LSQ to an RSQ. A configuration file for MQSeries Connection 5.0 includes a section containing the parameters required to associate an LSQ to an RSQ (%QUEUE) and a section containing the parameters for defining priority mapping (%PRIORITY MAPPING). The version of the configuration file is shown in the %VERSION section at the head of the file.

BEA MessageQ MQSeries Connection Versions 4.0A and 5.0 both support the same QMB configuration file format, except that the Version 4.0A product ignores the %PRIORITY MAPPING section. In addition, both versions support the configuration file format used in BEA MessageQ MQSeries Connection Version 3.2B.

A QMB configuration file includes the following parameters: the LSQ Name, LSQ Owner, RSQ Name, RSQ Association, and Format Name. These parameters must be specified on the same line in the order in which they are listed in Table 3-1. Configuration files for MQSeries Connection Version 5.0 contain an additional section in which priority mapping is defined. Table 3-1 describes all the QMB configuration file parameters.

Table 3-1 Parameters in the Queue Message Bridge Configuration File

Field
Description

LSQ Name

Name of the Local Service Queue defined in either BEA MessageQ or IBM MQSeries. This queue receives messages to be forwarded to the associated RSQ. BEA MessageQ LSQs must be multireader queues in the group to which the QMB attaches. IBM MQSeries LSQs must be shared queues that are defined in the MQM. The QMB connects to the queue specified by this parameter.

LSQ Owner

Indicates the messaging system that owns the LSQ as follows:

A D indicates BEA MessageQ. It is used for messages flowing from BEA MessageQ to IBM MQSeries.
An M indicates IBM MQSeries. It is used for messages flowing from IBM MQSeries to BEA MessageQ.

RSQ Name

Name of the Remote Service Queue associated with the LSQ. The RSQ is the target queue when a message is sent.

If a name is specified, the target queue is static. If a period (.) is specified, it serves as a placeholder for dynamic queue association. This is the final target for all messages sent. The RSQ may be located anywhere in the target messaging system that is accessible to the local BEA MessageQ group or IBM MQSeries MQM. A BEA MessageQ RSQ requires an entry in the Group Name Table if it is not defined in the local group. An IBM MQSeries RSQ requires a QREMOTE definition if it is not defined in the local MQM.

RSQ Association

Method of Remote Service Queue registration as follows:

an s indicates static association of the RSQ name to the LSQ.
A D indicates dynamic queue association of the RSQ name or address received in a registration request to the LSQ.
See Registering Remote Service Queues later in this chapter for more information on static and dynamic queue association.

Format Name

If specified, this name becomes the message descriptor Format parameter. If the IBM MQSeries channel definition associated with the RSQ allows character conversion, the named conversion exit will be invoked.

MessageQ Priority Range

The BEA MessageQ priority range. Each segment of the MessageQ priority range (for example 0-9, 10-19, and so on) must be mapped to a single IBM MQSeries priority and must be listed in ascending order. The priority range segments must be contiguous and all MessageQ priorities (0-99) must be included in the list of ranges. Priority values must not overlap.

Note: This field is recognized only by BEA MessageQ MQSeries Connection Version 5.0 and is ignored by the Version 4.0A product.

IBM MQSeries Priority

The IBM MQSeries priority value in the range of 0-9. All ten priority values must be listed in ascending sequential order and may be listed no more than once.

Note: This field is recognized only by BEA MessageQ MQSeries Connection Version 5.0 and is ignored by the Version 4.0A product.

MessageQ Priority

The BEA MessageQ priority value to which an IBM MQSeries priority value is mapped.

Note: This field is recognized only by BEA MessageQ MQSeries Connection Version 5.0 and is ignored by the Version 4.0A product.

Field	Description
LSQ Name	Name of the Local Service Queue defined in either BEA MessageQ or IBM MQSeries. This queue receives messages to be forwarded to the associated RSQ. BEA MessageQ LSQs must be multireader queues in the group to which the QMB attaches. IBM MQSeries LSQs must be shared queues that are defined in the MQM. The QMB connects to the queue specified by this parameter.
LSQ Owner	Indicates the messaging system that owns the LSQ as follows: A D indicates BEA MessageQ. It is used for messages flowing from BEA MessageQ to IBM MQSeries. An M indicates IBM MQSeries. It is used for messages flowing from IBM MQSeries to BEA MessageQ.
RSQ Name	Name of the Remote Service Queue associated with the LSQ. The RSQ is the target queue when a message is sent. If a name is specified, the target queue is static. If a period (.) is specified, it serves as a placeholder for dynamic queue association. This is the final target for all messages sent. The RSQ may be located anywhere in the target messaging system that is accessible to the local BEA MessageQ group or IBM MQSeries MQM. A BEA MessageQ RSQ requires an entry in the Group Name Table if it is not defined in the local group. An IBM MQSeries RSQ requires a QREMOTE definition if it is not defined in the local MQM.
RSQ Association	Method of Remote Service Queue registration as follows: an s indicates static association of the RSQ name to the LSQ. A D indicates dynamic queue association of the RSQ name or address received in a registration request to the LSQ. See Registering Remote Service Queues later in this chapter for more information on static and dynamic queue association.
Format Name	If specified, this name becomes the message descriptor Format parameter. If the IBM MQSeries channel definition associated with the RSQ allows character conversion, the named conversion exit will be invoked.
MessageQ Priority Range	The BEA MessageQ priority range. Each segment of the MessageQ priority range (for example 0-9, 10-19, and so on) must be mapped to a single IBM MQSeries priority and must be listed in ascending order. The priority range segments must be contiguous and all MessageQ priorities (0-99) must be included in the list of ranges. Priority values must not overlap. Note: This field is recognized only by BEA MessageQ MQSeries Connection Version 5.0 and is ignored by the Version 4.0A product.
IBM MQSeries Priority	The IBM MQSeries priority value in the range of 0-9. All ten priority values must be listed in ascending sequential order and may be listed no more than once. Note: This field is recognized only by BEA MessageQ MQSeries Connection Version 5.0 and is ignored by the Version 4.0A product.
MessageQ Priority	The BEA MessageQ priority value to which an IBM MQSeries priority value is mapped. Note: This field is recognized only by BEA MessageQ MQSeries Connection Version 5.0 and is ignored by the Version 4.0A product.

A QMB server process reads the configuration file passed with the command line, resolves all name-to-address issues, and builds an internal table to allow LSQ to RSQ mapping.

In the following example, BEA MessageQ clients have access to IBM MQSeries servers through the following BEA MessageQ LSQs:

MQS_ECHO (uses static association)
MQSTEST (uses dynamic queue association)

Likewise, IBM MQSeries clients have access to BEA MessageQ servers through the following IBM MQSeries LSQs:

DMQ_ECHO (uses static queue association)
DMQTEST (uses dynamic queue association)

Listing 3-3 shows the QMB configuration file that supports this case.

Listing 3-3 Queues Defined in a QMB Configuration File

! QMB Config File to Support ECHO Servers
!
!LSQ       LSQ     RSQ              RSQ
!Name      Owner   Name             Association
!
MQS_ECHO   D       MQS_ECHO_SERVER  S
MQSTEST    D       .                D
!
DMQ_ECHO   M       DMQ_ECHO_SERVER  S
DMQTEST    M       .                D

An LSQ with a dynamic RSQ association must have a program registered to it before it can be used. Any messages received before registration are returned to the sender with the appropriate Return To Sender (RTS) message type.

Reply queues are built using the -r parameter on the qmbsrv command line and are not required to be defined in the QMB configuration file.

When a QMB server process reads an MQSeries Connection Version 5.0 configuration file, it also sets up an internal table to allow priority mapping. Listing 3-4 shows a sample priority mapping section:

Listing 3-4 Priority Mapping Defined in a QMB Configuration File

* MessageQ Priority Range   MQSeries Priority   MessageQ Priority
*----------------------------------------------------------------
          0-09                       0                    0
         10-19                       1                   11
         20-29                       2                   22
         30-39                       3                   33
         40-49                       4                   44
         50-59                       5                   55
         60-69                       6                   66
         70-79                       7                   77
         80-89                       8                   88
         90-99                       9                   99
*

%EOS

Given a BEA MessageQ priority range of 30-39, an IBM MQSeries priority of 3, and a BEA MessageQ priority of 33, the following priority conversions occur:

A priority of 3 in an IBM MQSeries message is converted to a BEA MessageQ priority of 33.
A priority between 30 and 39 (inclusive) in a BEA MessageQ message is converted to an IBM MQSeries priority of 3.

Registering Remote Service Queues

An RSQ must be registered to an LSQ before any message may be forwarded to it. The RSQ registration may be statically defined in the QMB configuration file or dynamically associated at run time. There are two things that you must do to register an RSQ dynamically:

You must build and fill in a registration message data structure with the information needed to allow the association of the dynamic RSQ to the LSQ. The same structure is used to register BEA MessageQ or IBM MQSeries dynamic RSQs. If registering a BEA MessageQ RSQ, your application must supply the address of the RSQ. If registering an IBM MQSeries RSQ, your application must supply the name of the RSQ.
You must set the message type and class for RSQ registration. Code your application to send a specially formatted message with the BEA MessageQ message type of MSG_TYPE_RSQ_REGISTER and message class of MSG_CLAS_QMB to the permanent QMBDM primary queue (PQ). The QMBDM processes and forwards the registration request to all other associated QMB servers in the set.

In the QMB configuration file, static or dynamic association of an RSQ to an LSQ is determined by the RSQ association parameter of the LSQ entry. The RSQ association parameters are as follows:

[S] Static-The QMB uses the queue name defined in the RSQ name parameter as the RSQ to be associated with the LSQ. Static associations are determined and created at QMB initialization.
[D] Dynamic-The QMB uses the queue name or BEA MessageQ address received in an RSQ registration control message as the RSQ to be associated with the LSQ.

You can also register an RSQ using the BEA MessageQ MQSeries Connection utility. For more information on this utility, see Using the BEA MessageQ MQSeries Connection Utility in Configuring BEA MessageQ MQSeries Connection.

All messages received on the defined LSQ are forwarded to the RSQ name or address. This scheme allows flexibility: the server application can be moved among various BEA MessageQ groups or IBM MQSeries MQMs. Messages received on an LSQ that does not have a registered RSQ are returned to the sender.

Listing 3-5 shows a registration message data structure.

Listing 3-5 Registration Message Data Structure

typedef struct
  {
   char lsq[49];        /* (MAX_MQS_LEN = 49)               */
   char lowner;         /* LSQ Owner [D]MQ or [M]QS         */
   char rsq[49];        /* RSQ name of MQS Appl Queue       */
   char rfu;            /* Reserved for Future Use          */
   q_address rsq_add;   /* DMQ Address of DMQ RSQ           */
  }
   rsq_reg_struct;

Data structures and BEA MessageQ class and type definitions are supplied in the qmbuser.h file, which is located in /install_dir/include on UNIX systems and in dev:\install_dir\include on Windows NT systems. For BEA MessageQ Version 5.0, class and type definitions are also supplied in the p_typecl.h include file.

Table 3-1 Parameters in the Queue Message Bridge Configuration File