|
|
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:
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
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.
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:
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.
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 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.
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 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.
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 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.
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:
# /opt/mqm/samp/bin/amqsput DMQ_ECHO QMGR1
When amqsput starts, it displays the start message and the name of the target queue.
Hello message 1 from MQSeries
Hello message 2 from MQSeries
Last message from MQSeries
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:
# /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
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|