BEA Logo BEA MessageQ Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

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

Managing the BEA MessageQ MQSeries Connection Environment

 

This chapter describes how to manage the BEA MessageQ MQSeries Connection environment. It covers the following tasks:

Starting the Queue Message Bridge

Note: Before you can start the QMB, you must set the BEA MessageQ environment variables for the BEA MessageQ bus and group to which the QMB will attach.

To start the QMB processes, you must run the qmbsrv command with the required command parameters. You supply the required parameters in a command file or on the command line during an interactive session. Remember that for the bridge to function correctly, you must have at least one QMBDM and one QMBMD.

The command syntax for the QMB program is as follows:

qmbsrv -d msg-direction -s server-type -n mgr-name -r reply-qname
-c pathname -l pathname -a number -i interval
[-e] [-t] [-p] [-v]

Table 4-1 describes the QMB command parameters.

Table 4-1 Queue Message Bridge Command Parameters

Parameter

Description

-d msg-direction

Specifies the direction in which messages flow. You must specify one of the following parameters:

  • QMBDM for messages flowing from BEA MessageQ to IBM MQSeries

  • QMBMD for messages flowing from IBM MQSeries to BEA MessageQ

    This parameter is passed as an ASCII string.

-s server-type

Defines the QMB server type, which can be either PERMANENT or TEMPORARY. However, there must be at least one PERMANENT QMBDM and QMBMD in a QMB server set.

-n mgr-name

Specifies the name of the IBM MQSeries queue manager to which the QMB connects. The mgr-name specified must be the same for all QMB instances in the set. This parameter is passed as an ASCII string.

-r reply-name

Specifies the name of the reply queue. The QMB prefixes the name with either DMQ_ or MQS_ to create a full name. This queue must be defined as a permanent queue on the messaging system. The reply_name must be the same for all QMB instances in the set.

This parameter is passed as an ASCII string.

-c pathname

Specifies the full pathname of the QMB configuration file

-l pathname

Specifies the full pathname of the QMB log file

-a number

Specifies the maximum number of active (reply pending from BEA MessageQ servers) IBM MQSeries clients. The number specified must be the same for all QMB instances in the set. The maximum value is 1000.

-i interval

Specifies the connection index (CI) purge interval (in seconds) for pending replies being sent from a BEA MessageQ application to an IBM MQSeries client.

The interval specified must be the same for all QMB instances in the set.

-e

Specifies event logging. This parameter is optional.

-t

Specifies trace logging. This parameter is optional.

-p

Enables default priority mapping if a valid %PRIORITY MAPPING section is not found in the QMB configuration file. This parameter is optional and is ignored on BEA MessageQ MQSeries Connection Version 4.0A.

-v

Enables Verbose trace logging. This parameter is optional and should only be used for troubleshooting when the -t parameter is not sufficient.

For MQSeries Connection Versions 4.0A and 5.0, the -m memory-name parameter is obsolete. In earlier versions, this parameter specified the shared memory name assigned to the shared memory and semaphore required by the QMB. The name had either _SEM or _SHM appended to it. For the current version, the parameter is ignored and no error is generated if the parameter is used.

Note that the -e, -t, and -v parameters generate a fair amount of information in your log files. These parameters should not be left on for extended periods.

To start the permanent QMB process, enter the following commands:

qmbsrv -d QMBDM -s PERMANENT -n MQMNAME -r DMC_REPLYQ
-c /usr/qmb/qmbprod1.cfg -l /usr/qmb/qmbdm.log -a 60 -i 100

qmbsrv -d QMBMD -s PERMANENT -n MQMNAME -r DMC_REPLYQ
-c /usr/qmb/qmbprod1.cfg -l /usr/qmb/qmbmd.log -a 60 -i 100

Note: Permanent QMBDM and QMBMD processes must be running before any message exchange can occur. These processes register interest in each other and allow message exchange only if both are active. For QMB processes to register interest in each other, the BEA MessageQ SBS Server must be enabled so that AVAIL Services are active.

To add a QMBMD server (in which messages flow from an IBM MQSeries application to a BEA MessageQ application), enter the following command:

qmbsrv -d QMBMD -s TEMPORARY -n MQMNAME -r DMC_REPLYQ
-c /usr/qmb/qmbprod2.cfg -l /usr/qmb/qmbmd.log -a 60 -i 100

You can use a different configuration file (qmbprod2.cfg) to allow specific queues to be serviced by this copy of the QMB. Using a different configuration file gives you an additional level of customization and tuning.

Performance Considerations

You can maximize the performance of the IBM MQSeries to BEA MessageQ connection. To do so, add a temporary QMBMD process with a configuration file designed to service a specific IBM MQSeries LSQ. The required permanent QMBMD process polls (in a round-robin fashion) all IBM MQSeries LSQs for input. You can force a temporary QMBMD process to service a subset or single LSQ or REPLYQ by specifying a tailored configuration file with the -c parameter at startup. The rules that determine how a temporary QMBMD process services its LSQs are as follows:

Stopping the Queue Message Bridge

You can stop QMB processes in the following ways:

Using the BEA MessageQ Monitor Utility

To troubleshoot BEA MessageQ performance problems, use the BEA MessageQ Monitor utility. You can use this utility to determine traffic counts, the status of queues, cross-group connections, and attached programs. You can also use it to determine whether messages are flowing correctly by monitoring detailed information about the queues involved. For more information on the BEA MessageQ Monitor utility, see the BEA MessageQ installation and configuration guide for your system.

Using the runmqsc MQSeries Utility

Use the runmqsc MQSeries utility to determine the state and status of the MQSeries components used by the QMB. You can use the runmqsc utility as follows:

See the MQSeries Command Reference for a complete list of valid commands.

Troubleshooting BEA MessageQ MQSeries Connection Problems

To troubleshoot problems with BEA MessageQ MQSeries Connection, view the log files produced by BEA MessageQ, the QMB, and IBM MQSeries applications. Typically, these log files contain important information about successful and unsuccessful system events.

Note that the most efficient way to troubleshoot message queuing applications is to follow the queues used by the application. Start by making sure you are familiar with the flow of messages in your application as the message goes from queue to queue. Use the tools available on each platform to determine and follow the message flow. The most common approach is to use message counts and queue depths to follow a message.

Queue Message Bridge Log Files

You can view the QMB log files to troubleshoot your messaging application. The QMB produces log files that provide the following information:

The QMB program logs events and errors to the log defined at startup with the -l option to the qmbsrv command. To request a more detailed log file, there are additional command parameters that you can use:

Logging generates a fair amount of information; do not leave it on for extended periods of time. Event logging is generally used to follow message flow. Trace logging is used for problem determination.

Listing 4-1 shows a QMBDM log file created with the -e parameter.

Listing 4-1 QMBDM Log File


QMB: Dec 16 16:48:34 Version: 5.0-00 for HP-UX      

QMB: Dec 16 16:48:34 MQS Client Maximum Active : 100
QMB: Dec 16 16:48:34 MQS Client Inactivity Timer: 300
QMB: Dec 16 16:48:34 Event Logging Enabled
MQS: Dec 16 16:48:35 Connected to Queue Manager QMGR1, Hconn: 1073800288
SEM: Dec 16 16:48:35 Create: /var/tmp/dmq/b_5653/g_00005/ipc/qmb.s Attached:1 Locked : 0
MMF: Dec 16 16:48:35 Name: /var/tmp/dmq/b_5653/g_00005/ipc/qmb.mmf Size: 16804
SHM: Dec 16 16:48:35 Create: b_5653/g_00005/ipc/qmb.m Size:20480
Address: 3233009664
MMF: Dec 16 16:48:35 Mapped: /var/tmp/dmq/b_5653/g_00005/ipc/qmb.mmf
Size:20480 Address: 3233009664
DMQ: Dec 16 16:48:35 Attach - Queue Number : 5.8
QMB: Dec 16 16:48:35 MQS Reply Queue: MQS_DMC_REPLYQ
DMQ: Dec 16 16:48:35 Locate Queue = DMQ_DMC_REPLYQ Name length = 14

QMB: Dec 16 16:48:35 QMB Direction is QMBDM

DMQ: Dec 16 16:48:35 DMQ Reply Queue: DMQ_DMC_REPLYQ MRQ Address:'5.7'

QMB: Dec 16 16:48:35 OPEN: /home3/popp/mqsc_test/dmc500_config.dat
DMQ: Dec 16 16:48:35 Locate Queue = MQS_ECHO Name length = 8
CFG: Dec 16 16:48:35 LSQ: MQS_ECHO Format Name:
CFG: Dec 16 16:48:35 Q Table LSQ: MQS_ECHO CI: 12 LTYPE: D
CFG: Dec 16 16:48:35 Q Table RSQ: MQS_ECHO_SERVER RTYPE: S Header: N State: 1
MQS: Dec 16 16:48:35 Assigned MQS CI: 150
CFG: Dec 16 16:48:35 LSQ: DMQ_ECHO Format Name:
CFG: Dec 16 16:48:35 Q Table LSQ: DMQ_ECHO CI: 150 LTYPE: M
CFG: Dec 16 16:48:35 Q Table RSQ: DMQ_ECHO_SERVER RTYPE: S Header: N State: 1

QMB: Dec 16 16:48:35 User Defined Priority Mapping is Enabled

QMB: Dec 16 16:48:35 DMQ LSQ Count: 1 MQS LSQ Count: 2

DMQ: Dec 16 16:48:35 SEL_MASK 1073817752 Que: 0
DMQ: Dec 16 16:48:35 SEL_MASK 1073817836 Que: 7
DMQ: Dec 16 16:48:35 SEL_MASK 1073817920 Que: 12
DMQ: Dec 16 16:48:35 PAMS_SET_SELECT Success - 3 Queues
DMQ: Dec 16 16:48:35 Locate Queue = QMBMD Name length = 5
DMQ: Dec 16 16:48:35 Register Interest in DMQ process '5.9'
DMQ: Dec 16 16:48:35 PUT tar: 5.99 class:29 type:-1180 len:16 dm:39 prio:0 rspq:0.8
DMQ: Dec 16 16:48:35 Posting DMQ_RECV Select VAR: 1 MODE: -1
DMQ: Dec 16 16:48:35 GET: Q:8 src:5.99 class:29 type:-1182 len:6
prio:0
endian:1
DMQ: Dec 16 16:48:35 TPQ: 8 Src: 5.99 Class: 29 Type: -1182
DMQ: Dec 16 16:48:35 QMB AVAIL Registration Success
DMQ: Dec 16 16:48:35 Posting DMQ_RECV Select VAR: 1 MODE: -1
.
.
.
DMQ: Dec 16 16:48:37 QMB Process AVAILABLE '5.9'
DMQ: Dec 16 16:48:37 Posting DMQ_RECV Select VAR: 1 MODE: -1
DMQ: Dec 16 16:50:02 GET: Q:12 src:5.201 class:32000 type:-5010 len:100 prio:0 endian:1
DMQ: Dec 16 16:50:02 LSQ: 12 RSQ: MQS_ECHO_SERVER SRC: 5.201
MQS: Dec 16 16:50:02 Open RSQ: MQS_ECHO_SERVER

MQS: Dec 16 16:50:02 Open Queue: MQS_ECHO_SERVER Hobj:1073903024
MQS: Dec 16 16:50:02 PUT - DMQ CLI ADD: 00005.201
MQS: Dec 16 16:50:02 Send Request: RSQ: MQS_ECHO_SERVER Size: 100 Persistence: 0 Msg: DMQ_CLI
MQS: Dec 16 16:50:02 MQPUT: Send Queue: MQS_ECHO_SERVER CompCode: 0
DMQ: Dec 16 16:50:02 Posting DMQ_RECV Select VAR: 1 MODE: -1
DMQ: Dec 16 16:50:02 GET: Q:12 src:5.201 class:32000 type:-5010 len:100 prio:0 endian:1
DMQ: Dec 16 16:50:02 LSQ: 12 RSQ: MQS_ECHO_SERVER SRC: 5.201
MQS: Dec 16 16:50:02 PUT - DMQ CLI ADD: 00005.201
MQS: Dec 16 16:50:02 Send Request: RSQ: MQS_ECHO_SERVER Size: 100 Persistence: 0 Msg: DMQ_CLI
MQS: Dec 16 16:50:02 MQPUT: Send Queue: MQS_ECHO_SERVER
CompCode: 0
DMQ: Dec 16 16:50:02 Posting DMQ_RECV Select VAR: 1 MODE: -1
DMQ: Dec 16 16:50:20 GET: Q:8 src:5.202 class:32000 type:-5099 len:0 prio:0 endian:1
DMQ: Dec 16 16:50:20 TPQ: 8 Src: 5.202 Class: 32000 Type: -5099

QMB: Dec 16 16:50:20 QMB Server SHUTDOWN Request...

QMB: Dec 16 16:50:20 QMB Server Exiting
MMF: Dec 16 16:50:20 Write : /var/tmp/dmq/b_5653/g_00005/ipc/qmb.mmf Bytes: 20480

Using IBM MQSeries Log Files

You can use the IBM MQSeries log files to determine any failures or events associated with various components. There are two ways to locate the IBM MQSeries log files:

Using the BEA MessageQ MQSeries Connection Utility

The BEA MessageQ MQSeries Connection distribution media includes a utility called qmb_util which facilitates the sending of control messages to QMB processes. This utility allows you to control the behavior of a target QMB process, without having to close the process or rewrite the client or server application to send the desired control message to that process.

The qmb_util utility is located in /install_dir/bin on UNIX systems and in dev:\install_dir\bin on Windows NT systems.

How the BEA MessageQ MQSeries Connection Utility Works

The qmb_util utility sends a message containing the appropriate BEA MessageQ class and message type to perform the desired control function. In most cases, this message is sent to the QMBDM permanent queue.

Table 4-2 describes the valid control functions listed by message type.

Table 4-2 Valid Control Functions Listed by Message Type

Message Type

Description

MSG_TYPE_PURGE_CI

Purges all nonpersistent connection indexes (CI) from the CI table. This message is processed only by the permanent QMBDM server.

MSG_TYPE_PURGE_CI_ALL

Purges all CIs from the CI table. This message is processed only by the permanent QMBDM server.

MSG_TYPE_NEW_LOG

Closes the existing log and opens a new log. Sending this message to the permanent QMBDM server results in messages being transmitted to the associated QMBMD server and all of their Temporary Primary Queues (TPQs).

MSG_TYPE_LOAD_CONFIG

Reloads the QMB configuration file. Sending this message to the permanent QMBMD server results in messages being transmitted to the associated QMBDM server and all Temporary Primary Queues (TPQs).

MSG_TYPE_RSQ_REGISTER

Requires the RSQ registration structure in the message body of the message structure. Sending this message to the permanent QMBDM server results in messages being transmitted to the associated QMBMD server and all Temporary Primary Queues (TPQs).

MSG_TYPE_EVENT_LOG

Toggles QMB Server event logging. If event logging is enabled (that is, if you started the QMB with the -e parameter), use this message type to disable event logging. Likewise, if event logging is disabled, use this message type to enable event logging.

This message must be sent to each QMB Server that requires a change in event logging status.

MSG_TYPE_TRACE_LOG

Toggles internal trace logging. If trace logging is on (that is, if you started the QMB with the -t parameter), use this message type to toggle trace logging off. Likewise, if trace logging is off, use this message type to toggle trace logging on.

If verbose tracing is enabled, this message disables trace logging. Verbose logging can only be enabled using the -v parameter on the QMB Server command line.

This message must be sent to each QMB Server that requires a change in trace logging status.

MSG_TYPE_DUMP_QTABLES

Dumps MQSeries Message Descriptor (MQMD) to a log file. This message is processed only by the permanent QMBDM server.

MSG_TYPE_TERMINATE

Terminates a QMB Server. If this message is sent to a Permanent QMB Server, the termination request is forwarded to all associated TPQs.

The qmb_util utility sends most control messages to the QMBDM primary queue (which is also the default target [QMBDM] ). However, some control messages work on a specific QMBDM or QMBMD process and must be directed to that process's group and queue. For example, you can terminate a specific temporary QMB process without terminating the permanent process.

The qmb_util allows you to change the target group and queue so that control messages can be sent to queues other than the QMBDM primary queue (the default target).

Starting the BEA MessageQ MQSeries Connection Utility

Before you can run the qmb_util utility, set the DMQ_BUS_ID and DMQ_GROUP_ID environment variables. Then run qmb_util by entering the following command:

% qmb_util

The qmb_util displays the menu as shown in Listing 4-2.

Listing 4-2 The qmb_util Main Menu


        MessageQ MQSeries Connection Utility V5.0

1) Toggle the QMB event log switch (MSG_TYPE_EVENT_LOG)
2) Toggle the QMB trace log switch (MSG_TYPE_TRACE_LOG)
3) Reload QMB config file (MSG_TYPE_LOAD_CONFIG)
4) Close old and open new log file (MSG_TYPE_NEW_LOG)
5) Purge non-persistent CI only (MSG_TYPE_PURGE_CI)
6) Purge all CI (MSG_TYPE_PURGE_CI_ALL)
7) Dump MQMD to Log File (MSG_TYPE_DUMP_QTABLES)
8) Dynamic Service Registration (MSG_TYPE_RSQ_REGISTER)
9) Terminate the QMB processes (MSG_TYPE_TERMINATE)

10) Change target group and queue
11) Set target group and queue to default [QMBDM] primary
12) Exit this utility

Default Target [QMBDM] 5.12
Current Target Default [QMBDM] 5.12

Enter Message Choice:


Note the field, below the menu, labelled "Current Target Default [QMBDM]." The value in this field (5.12) indicates tha target to which control messages are sent. (Specifically, "5.12" represents group 5 and queue 12 of the target.) For more information, see Understanding Current and Default Target Groups and Queues in this chapter.

Understanding Current and Default Target Groups and Queues

When you invoke qmb_util, the default target line is identified in a field below the main menu, as shown in Listing 4-2. The value in this field depends on whether or not the location of the target was known when qmb_util was started. Table 4-3 describes valid values in the "Default Target" and "Current Target Default" fields.

Table 4-3 Target Line Display

Display from Main Menu

Description

Default Target [QMBDM] G.Q

The target was located during startup. (G.Q indicates a valid group and queue number such as 5.12.)

Default Target [QMBDM] UNDEFINED

The qmb_util utility could not locate the QMBDM process.

Current Target Default [QMBDM]G.Q

The default target was located during start up. (G.Q indicates a valid group and queue number such as 5.12.)

Current Target Group:[UNDEFINED]
Queue : [UNDEFINED]

The qmb_util utility could not locate the current target.

After qmb_util is started, the current target may be changed to any group.queue using choice 10 on the menu (Change target group and queue).

After you enter a new target group and queue, the qmb_util displays a message similar to the following:

Current Target Group : [x] Queue : [x]

It is this current target group to which qmb_util control messages are sent. Control messages must be sent to their proper target for the desired QMB action to take place.

Most qmb_util control messages need only a target and message type in order to complete the requested action. Some control messages, however, require additional information. The qmb_util utility prompts for this information.

Selecting the Terminate QMB Process Message Choice

To terminate the QMB process that you specify, select choice 9 from the Connection Utility Menu. When you select choice 9, the menu shown in Listing 4-3 is displayed.

Listing 4-3 Terminate Queue Message Bridge Process Menu


1) Terminate QMBDM & all temporary instances  (MessageQ to MQSeries)
2) Terminate QMBMD & all temporary instances (MQSeries to MessageQ)
3) Terminate a single temporary QMB instance (DMQ Address required)
4) Terminate QMBDM, QMBMD and all temporary instances (Bridge Set)

Select terminate choice or <CR> to exit:


Selecting the Dynamic Service Registration Message Choice

You can change the registration of a queue (the BEA MessageQ RSQ) by selecting choice 8 (Dynamic Service Registration) from the menu. When you select choice 8, the prompts shown in Listing 4-4 are displayed:

Listing 4-4 Dynamic Service Registration for a BEA MessageQ RSQ


Enter LSQ name to assign the RSQ to:  
Enter LSQ Owner (M or D):
Enter MessageQ RSQ group number
Enter MessageQ RSQ queue number:


When you select the Dynamic Service Registration message choice to change the IBM MQSeries RSQ, the prompts shown in Listing 4-5 are displayed:

Listing 4-5 Dynamic Service Registration for an MQSeries RSQ


Enter LSQ name to assign the RSQ to: 
Enter LSQ Owner (M or D):
Enter MQSeries queue name of RSQ:


Selecting the Close Old and Open New Log File Message Choice

To close the QMB Server's current log file and open a new log file, select choice 4 (Close old and open new log file) from the Connection Utility menu. The new log file has the same name as the old log file except that the new one has a tilde (~) suffix. For example, if the name of the current log file is dmc_dm.log, selecting choice 4 causes the log file to be closed and a file named dmc_dm.log~ to be created. A subsequent invocation of message choice causes another tilde to be appended to the file name. In this case, a file named dmc_dm.log~~ will be created.

If this message is sent to the permanent QMBDM server, it is automatically forwarded to the associated QMBMD server and all of their Temporary Primary Queues (TPQs).

Selecting the Reload QMB Configuration File Message

To direct the QMB Servers to reload their configuration files, select choice 3 (Reload QMB config file) from the Connection Utility menu. This allows the configuration file to be updated and reloaded without stopping and restarting the QMB Servers. New queue definitions can be added through this process, but queue definitions cannot be deleted. To delete queue definitions the QMB Servers must be restarted.

The Priority Mapping section of the configuration file can be modified and then reloaded to dynamically update the priority mapping scheme in use.

If this message is sent to the permanent QMBDM Server then it is automatically forwarded to the associated QMBMD Server and all of their TPQs.

Exiting the BEA MessageQ MQSeries Connection Utility

To exit qmb_util, select choice 12 (Exit this utility) from the Connection Utility menu.