Programming Examples

 

The BEA MessageQ MQSeries Connection media includes a set of programming examples that show how applications can use interprocess message queuing to exchange information. The following programming examples are included:

• BEA MessageQ MQSeries Connection client/server programs

• Programs for testing BEA MessageQ MQSeries Connection

The programming examples are located in /install_dir/examples/mqsc on UNIX systems and in dev:\install_dir\examples\mqsc on Windows NT systems.

Note: Do not modify these examples in the example directory. If you want to use an example as a starting point to develop an application, copy the programming example to your working directory and edit it there.

This appendix discusses the following topics:

• Using the Programming Examples

• Testing the Programming Examples

Using the Programming Examples

This section describes the programming examples for BEA MessageQ and IBM MQSeries applications. The programming examples consist of a set of client and server programs designed to test a simple message exchange between two processes running in the BEA MessageQ and IBM MQSeries environments. The programming examples report statistical results on message exchange rates and are designed to run in pairs.

Table A-1 describes the programming examples that are provided in the kit.

Table A-1 Programming Examples

Program Name	Description
QMB_DMQECHO	A BEA MessageQ server application that attaches to an RSQ and receives requests from an IBM MQSeries LSQ.
QMB_MQSECHO	An IBM MQSeries client application that reads from an RSQ and receives requests from an BEA MessageQ LSQ.
QMB_DMQCLIENT	A BEA MessageQ client application that sends requests to a BEA MessageQ LSQ which are then forwarded by the QMBDM to the corresponding IBM MQSeries RSQ.
QMB_MQSCLIENT	An IBM MQSeries client application that sends requests to an IBM MQSeries LSQ which are then forwarded by the QMBMD to the corresponding BEA MessageQ RSQ.

The programming examples are designed to echo back messages from the following client and servers:

• BEA MessageQ client (QMB_DMQCLIENT) to an IBM MQSeries server (QMB_MQSECHO).

• IBM MQSeries client (QMB_MQSCLIENT) to a BEA MessageQ server (QMB_DMQECHO).

When using these programming examples, you can have more than one instance of the client running, but only one instance of the server running.

Building the Programming Examples

To build the programs, invoke the appropriate makefile by using the make command. Two makefiles are available: /install_dir/examples/mqsc/makefile for UNIX systems and dev:\install_dir\examples\mqsc\mqsc.mak for Windows NT systems. For Windows NT, build the examples using the following command:

nmake -f mqsc.mak

QMB_DMQECHO

QMB_DMQECHO is a BEA MessageQ program designed to listen on a well-known address. It returns any message it receives, immediately after receipt, to the sender.

In this example, the address is named DMQ_ECHO_SERVER. The BEA MessageQ group initialization file must contain an entry for a queue named DMQ_ECHO_SERVER. This entry must be included in the QUEUE CONFIGURATION SECTION (%QCT) or in the GROUP NAME TABLE SECTION (%GNT).

The command syntax for the QMB_DMQECHO program is as follows:

% qmb_dmqecho [-q queue_name] [-d] [-?]

Table A-2 describes the QMB_DMQECHO parameters.

Table A-2 QMB_DMQECHO Command Parameters

Parameter	Description
-q	Defines the source queue name. This parameter is optional. The default name is DMQ_ECHO_SERVER.
-d	Enables debug mode to print trace information. This parameter is optional. The default setting is debugging mode disabled.
-?	Prints a simple help message. This parameter is optional.

QMB_MQSECHO

QMB_MQSECHO is an IBM MQSeries application program designed to listen on the queue named on the command line, which must be a valid, configured IBM MQSeries queue.

The command syntax for the QMB_MQSECHO program is as follows:

% qmb_mqsecho -r qname [-m MQMname] [-d] [-?]

Table A-3 describes the QMB_MQSECHO parameters.

Table A-3 QMB_MQSECHO Command Parameters

Parameter	Description
-r qname	Specifies the name of a valid, configured IBM MQSeries RSQ from which QMB_MQSECHO expects to read requests. This parameter is required.
-m MQMname	Specifies the name of the IBM MQSeries queue manager (MQM) to which QMB_MQSECHO should connect. This parameter is optional. If no MQM name is supplied, the default IBM MQSeries MQM is used.
-d	Enables debugging mode to print trace information. This parameter is optional. The default setting is debugging mode disabled.
-?	Prints a simple help message. This parameter is optional.

QMB_DMQCLIENT

QMB_DMQCLIENT is a BEA MessageQ application designed to send requests to the QMB_MQSECHO and then read the replies. The target group is the BEA MessageQ group in which the QMB is running. The target queue number is the BEA MessageQ LSQ that maps to the RSQ on which QMB_MQSECHO is listening. The dmc500_config.dat file should include the name associated with the target queue number used by the QMB_DMQCLIENT. This file maps the LSQ to the RSQ in the IBM MQSeries environment.

The command syntax of the QMB_DMQCLIENT program is as follows:

% qmb_dmqclient -g n -q n [-i] [-l n] [-b n] [-s n] [-d] [-p n] [-c correlid] [-j] [-?]

Table A-4 describes the parameters for the QMB_DMQCLIENT program.

Table A-4 QMB_DMQCLIENT Command Parameters

Parameter	Description
-g n	Specifies the number of the target BEA MessageQ LSQ group. This parameter is required.
-q n	Specifies the number of the target BEA MessageQ LSQ queue. This parameter is required.
-i	Specifies interactive mode. If this parameter is specified, the following parameters are ignored: -l, -b, and -s. This parameter is optional.
-l n	Specifies the loop count, which is the number of iterations. This parameter is optional. The default is 1 iteration.
-b n	Specifies the burst count, which is the number of messages per iteration. This parameter is optional. The default is 1 message.
-s n	Specifies the size of the message, in bytes. The minimum size is 60, which allows for the sequence number and time stamp. If this parameter is not specified, the default is 60. The maximum is 4194304 bytes.
-d	Specifies debugging mode, which prints trace information. This parameter is optional.The default is debugging mode disabled.
-p	The number indicating the priority of the message. This parameter is optional. The valid range is 0-1 for BEA MessageQ V4.0A and 0-99 for BEA MessageQ V5.0.
-c	The correlation identifier. This parameter is optional. The default is no correlation identifier. This feature is supported only for BEA MessageQ V5.0.
-j	Enables journaling. This parameter is optional. The default is no journaling.
-?	Prints a simple help message. This parameter is optional.

QMB_MQSCLIENT

QMB_MQSCLIENT is an IBM MQSeries client application designed to send requests to QMB_DMQECHO and then read any replies from the named reply queue. The target queue is the IBM MQSeries LSQ queue name that maps to the RSQ on which QMB_DMQECHO is listening. The target queue is specified in the config.dat file.

The command syntax for the QMB_MQSCLIENT program is as follows:

% qmb_mqsclient -t name -r name [-m MQMname][-d][-i] [-l n] [-b n] [-s n] [-p n] [-c correlid] [-j] [-?]

Table B-5 describes the QMB_MQSCLIENT parameters.

Table A-5 QMB_MQSCLIENT Command Parameters

Parameter	Description
-t name	Specifies the name of the target IBM MQSeries LSQ queue. This parameter is required.
-r name	Specifies the name of the reply queue. This parameter is required.
-m name	Specifies the name of the IBM MQSeries Queue Manager (MQM). This parameter is optional. If no MQM is specified, the default MQM is used.
-d	Enables debugging mode, which prints trace information. This parameter is optional.
-i	Specifies interactive mode. The program prompts for a text message. If this parameter is specified, the following parameters are ignored: -l, -b, and -s.
-l n	Specifies the loop count. This parameter is optional. The default count is 1.
-b n	Specifies the burst count. This parameter is optional. The default count is 1.
-s n	Specifies the size of the message, in bytes. The minimum size is 60 bytes. If the size is not specified, the default is 60, which allows for the sequence number and time stamp. The maximum size is 4194304 bytes.
-p n	The number indicating the priority of the message. This parameter is optional. The valid range is 0-9 for IBM MQSeries V5.0. The default is 0.
-c correlid	The correlation identifier. This parameter is optional. The default is no correlation identifier. This feature is supported only for BEA MessageQ V5.0.
-j	Persistent messaging is enabled. This parameter is optional. The default is persistent messaging disabled.
-?	Prints a simple help message

Running the QMB_MQSECHO and QMB_DMQCLIENT Test Pair

To run the QMB_MQSECHO and QMB_DMQCLIENT test pair, you must first set up the QMB configuration file and the BEA MessageQ initialization file with the proper parameters. Then, you can invoke the QMB_MQSECHO and QMB_DMQCLIENT programs.

For example, suppose the QMB is running on group 5 and the desired target queue of QMB_DMQCLIENT is MQS_ECHO_SERVER. In this case, the QMB_DMQCLIENT sends a request to the queue number defined as the LSQ in the DMC320_CONFIG.DAT file that maps to the MQS_ECHO_SERVER. Listing A-1 shows a QMB configuration file.

Listing A-1 Queue Message Bridge Configuration File

---

!LSQ       LSQ     RSQ              RSQ
!Name      Owner   Name             Association
!
MQS_ECHO   D       MQS_ECHO_SERVER  S

---

Listing A-2 shows the entry you must provide for group 5 in the QUEUE CONFIGURATION SECTION (%QCT) of the BEA MessageQ initialization file, group.init.

Listing A-2 QUEUE CONFIGURATION SECTION

---

!QUEUE CONFIGURATION SECTION
!
% QCT

!Queue   Queue  Byte   Msg   Quota  UCB  Queue Owner Conf  Perm   Name
!Name    Number Quota  Quota Enable Send Type  Queue Style Active Scope Security
MQS_ECHO          12   64000   100   None   .    M     0     .     Y      L     N

---

To run the test pair, you must invoke both the QMB_MQSECHO and QMB_DMQCLIENT programs. Enter the following command on the IBM MQSeries system to invoke the QMB_MQSECHO program:

% qmb_mqsecho  -r MQS_ECHO_SERVER

Enter the following command on the BEA MessageQ system to invoke the QMB_DMQCLIENT program:

% qmb_dmqclient -g 5 -q 12 -l 10 -b 2 -s 1024 -d

In this example, MQS_ECHO, which is defined in the BEA MessageQ initialization file, is identified by the -g 5 and -q 12 parameters.

Running the QMB_MQSCLIENT and QMB_DMQECHO Test Pair

Before you can run the QMB_MQSCLIENT and QMB_DMQECHO test pair, you must first set up the QMB configuration file and the BEA MessageQ initialization file with the proper parameters.

For example, suppose the target queue of the QMB_MQSCLIENT is DMQ_ECHO_SERVER. In this case, QMB_MQSCLIENT sends a request to the LSQ (defined in the dmc500_config.dat file) that maps to the RSQ (named DMQ_ECHO_SERVER).

Listing A-3 shows the dmc500_config.dat file.

Listing A-3 Queue Message Bridge Configuration File

---

!LSQ       LSQ     RSQ              RSQ
!Name      Owner   Name             Association
!
DMQ_ECHO    M      DMQ_ECHO_SERVER  S

---

Listing A-4 shows the QUEUE CONFIGURATION SECTION in which group 5 is defined in the BEA MessageQ Initialization File (group.init).

Listing A-4 QUEUE CONFIGURATION SECTION

---

!QUEUE CONFIGURATION SECTION
!
% QCT

!Queue   Queue  Byte   Msg   Quota  UCB  Queue Owner Conf  Perm   Name
!Name    Number Quota  Quota Enable Send Type  Queue Style Active Scope Security
!
DMQ_ECHO_SERVER 15 64000 100 None   .    M     0     .     Y      L     N

---

If the DMQ_ECHO_SERVER runs on a remote BEA MessageQ group, the entry shown in Listing A-5 is needed in the GROUP NAME TABLE SECTION (%GNT):

Listing A-5 GROUP NAME TABLE SECTION

---

!GROUP NAME TABLE SECTION
!
% GNT
DMQ_ECHO_SERVER 62.15 L

---

To run the test pair, you must invoke both the QMB_DMQECHO and QMB_MQSCLIENT programming examples. On the IBM MQSeries system, enter the following command to invoke the QMB_MQSCLIENT program:

% qmb_mqsclient -t DMQ_ECHO -r MQS_CLIENT_REPLYQ -m QMNAME  -l 10  
  -b 2  -s 1024  -d

Enter the following command on a BEA MessageQ system to invoke the QMB_DMQECHO program:

% qmb_dmqecho  -d

Testing the Programming Examples

BEA MessageQ and IBM MQSeries both provide programming examples that help you learn how these products work. You can also use these programs to verify the BEA MessageQ MQSeries Connection installation and configuration. To verify, use the BEA MessageQ Test Utility (dmqtestm or dmqtestc) and the IBM MQSeries programming examples (amqsget0 and amqsput0). With these programming examples and the Test Utility, simple datagram messages can be exchanged by different queue messaging environments (BEA MessageQ and IBM MQSeries) if the BEA MessageQ MQSeries Connection servers (QMB server) are properly configured.

For more information about the BEA MessageQ Test Utility, see the BEA MessageQ Programmer's Guide.

For information about the IBM MQSeries amqsget0 and amqsput0 programming examples, see the MQSeries Application Programming Guide.

You can perform simple datagram messaging with out-of-the-box BEA MessageQ and IBM MQSeries test tools and examples, if there is a properly configured QMB server pair. However, you cannot perform other types of message exchange (such as request or reply) because these applications do not follow programming conventions that allow the QMB to exchange messages. To perform request and reply message exchange, you need to modify the applications to pass the appropriate BEA MessageQ type and class fields and to fill in the IBM MQSeries MQS_CLIENT_REPLYQ fields.

BEA MessageQ MQSeries Connection provides an example dmc500_config.dat file, dmc500_dmq_group.init file, an MQSC command file (dmc500_mqmdef.cfg), and example scripts to start a QMB server pair.

The following examples are based on the configuration established and the queue associations defined in the dmc500_config.dat file.

Note: Use the dmc500_dmq_group.init file for BEA MessageQ startup. You can copy this file from /install_dir/templates on UNIX systems and from dev:\install_dir\templates on Windows NT systems.

Testing the IBM MQSeries Connection to BEA MessageQ

To send an IBM MQSeries message to BEA MessageQ, complete the following procedure:

1. In a test window on the BEA MessageQ side, run the dmqtestc utility. Using this utility, Attach By Name to the DMQ_ECHO_SERVER queue.

2. Enter the command to start amqsput on the system running IBM MQSeries. Invoke amqsput with DMQ_ECHO as the target queue and QMGR1 as the queue manager name. (The target queue is the IBM MQSeries LSQ, which maps to the BEA MessageQ RSQ through the dmc500_config.dat file.) For example, on an HP-UX system:

   # /opt/mqm/samp/bin/amqsput DMQ_ECHO QMGR1

   When amqsput starts, it displays the start message and the name of the target queue.

3. Enter messages. amqsput expects ASCII input followed by the newline character. Once amqsput gets a message, it displays it. For example:

   Hello message 1 from MQSeries
   Hello message 2 from MQSeries
   Last message from MQSeries

4. From the dmqtestc utility, issue three GET commands to read the inbound messages from amqsput.

See the following section for instructions on testing the BEA MessageQ connection to IBM MQSeries.

Testing the BEA MessageQ Connection to IBM MQSeries

On the BEA MessageQ side, you can test the connection using dmqtestc. Complete the following procedure:

1. Invoke the dmqtestc program.

2. Issue a PUT command with the text "Hello from BEA MessageQ" to queue MQS_ECHO. (You can use the LOCATE_Q command to return the queue number fro MQS_ECHO.)

3. Run amqsget with a source queue name of MQS_ECHO_SERVER and a queue manager name of QMGR1. (The source queue name is the name of the IBM MQSeries RSQ which maps to the MessageQ LSQ through the dmc500_config.dat file.) For example, on an HP-UX system:

   # /opt/mqm/samp/bin/amqsget MQS_ECHO_SERVER QMGR1

   The amqsget utility should have received one message similar to the following:

   Sample AMQSGET start
   message <Hello from BEA MessageQ>
   no more messages
   Sample AMQSGET end