MessageQ MQSeries Connection media kit 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 the following directory:
Do not modify these examples in the This topic describes the programming examples for MessageQ and MQSeries applications. The programming examples consist of a set of client and server programs designed to test simple message exchange between two processes running in the MessageQ and MQSeries environments. The programming examples report statistical results on message exchange rates and are designed to run in pairs.
Table B-1 describes the programming examples that are on the kit./usr/kits/DMC32B/examples (or /usr/kits/DMC32C/examples)
example directory. If you want to use these examples as a starting point to develop your applications, copy the programming example to your working directory and edit.
Using the Programming Examples
The programming examples are designed to echo back messages from the following client and servers:
You can have more than one instance of the client running for the programming examples. However, you can only have one instance of the server running.
Figure B-1 shows how messages flow between a MessageQ client and an MQSeries server.
Figure B-2 shows how messages flow between an MQSeries client and a MessageQ server.
The prefix to the _ECHO_SERVER programs indicates the message queuing environment of the server program. The MQS_ECHO_SERVER and DMQ_ECHO_SERVER programs act like mirrors, and they return any messages they receive to the originators of the messages.
The prefix to the _CLIENT programs indicates the message queuing of the client program. For example, MQS indicates MQSeries. The MQS_CLIENT and DMQ_CLIENT programs act as drivers, making requests of echo servers running in the opposite queuing environment.
To build the programs, invoke the makefile by using the DMQ_ECHO_SERVER is a MessageQ program designed to listen on a well-known address. It returns the message it just received to the sender of the message.
In this example, the address is named DMQ_ECHO_SERVER. In the MessageQ group initialization file, there must be an entry in the QUEUE CONFIGURATION SECTION or the GROUP NAME TABLE SECTION (if the server program is not run from the local group) for a queue named DMQ_ECHO_SERVER.
The command syntax for the DMQ_ECHO_SERVER program is as follows:
Table B-2 describes the DMQ_ECHO_SERVER parameters.Figure B-1 DMQ_CLIENT and MQS_ECHO_SERVER
Figure B-2 MQS_CLIENT and DMQ_ECHO_SERVER
Prefixes for Clients and Servers
Building the Programming Examples
make command.
DMQ_ECHO_SERVER
% DMQ_ECHO_SERVER [-d] [-?]
For example, to invoke DMQ_ECHO_SERVER, enter the following command:
% DMQ_ECHO_SERVER
If you want to invoke DMQ_ECHO_SERVER in the debug mode to print trace information, enter the following command:
% DMQ_ECHO_SERVER -d
MQS_ECHO_SERVER is an MQSeries application program designed to listen on the queue named on the command line, which must be a valid, configured MQSeries queue.
The command syntax for the MQS_ECHO_SERVER program is as follows:
% MQS_ECHO_SERVER -rqname[-mname] [-d] [-?]
Table B-3 describes the MQS_ECHO_SERVER parameters.
To invoke MQS_ECHO_SERVER, enter the following command:
% MQS_ECHO_SERVER -r MQS_ECHO_SERVER
DMQ_CLIENT is a MessageQ application designed to send requests to the MQS_ECHO_SERVER and then read the replies. The target group is the MessageQ group in which the QMB is running. The target queue number of the DMQ_CLIENT should have that queue's name in the DMC320_CONFIG.DAT file. This file maps the LSQ to the RSQ in the MQSeries environment, which is the queue name the MQS_ECHO_SERVER is listening on.
The command syntax of the DMQ_CLIENT program is as follows:
DMQ_CLIENT [-?] -gn-qn[-d] [-i] -ln-bn[-sn]
Table B-4 describes the parameters for the DMQ_CLIENT program.
For example, to invoke the DMQ_CLIENT, enter one of the following commands:
% DMQ_CLIENT -g 5 -q 12 -l 10 -b 2 -s 1024 -d
% DMQ_CLIENT -g 5 -q 12 -d -i
If DMQ_CLIENT is run with the interactive mode (-i), the program prompts for a text message to send to the MQS_ECHO_SERVER.
MQS_CLIENT is an MQSeries client application designed to send requests to DMQ_ECHO_SERVER and then read any replies from the named reply queue. The target queue is the name of the queue in the CONFIG.DAT file. The name maps the LSQ to the RSQ in the MessageQ environment, which is the queue name the DMQ_ECHO_SERVER is attached to.
The command syntax for the MQS_CLIENT program is as follows:
% MQS_CLIENT [-?] -tname-rname[-mname]
[-d] [-i] -ln-bn- sn
Table B-5 describes the MQS_CLIENT parameters.
For example, to invoke MQS_CLIENT, enter one of the following commands:
% MQS_CLIENT -t DMQ_ECHO -r MQS_CLIENT_REPLYQ
-m QMNAME -l 10 -b 2 -s 1024 -d
% MQS_CLIENT -t DMQ_ECHO -r MQS_REPLYQ
-m QMNAME -d -i
To run the MQS_ECHO_SERVER and DMQ_CLIENT test pair, you must first set up the QMB configuration file and the MessageQ initialization file with the proper parameters. Then, you can invoke the MQS_ECHO_SERVER and DMQ_CLIENT programs.
For example, suppose the QMB is running on group 5 and the desired target queue of DMQ_CLIENT is MQS_ECHO_SERVER. In this case, the DMQ_CLIENT sends to the queue number of the LSQ defined in the DMC320_CONFIG.DAT file that maps to the MQS_ECHO_SERVER. Listing B-1 shows a QMB configuration file.
Listing B-1 Queue Message Bridge Configuration File
!LSQ Name LSQ RSQ RSQ
!Name Owner Name Association
!
MQS_ECHO D MQS_ECHO_SERVER S
Listing B-2 shows what you need in the QUEUE CONFIGURATION SECTION of the MessageQ initialization file, DMQ.INIT, for group 5.
Listing B-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 MQS_ECHO_SERVER and DMQ_CLIENT programs. Enter the following command on the MQSeries system to invoke the MQS_ECHO_SERVER program:
% MQS_ECHO_SERVER -r MQS_ECHO_SERVER
Enter the following command on the MessageQ system to invoke the DMQ_CLIENT program:
% DMQ_CLIENT -g 5 -q 12 -l 10 -b 2 -s 1024 -d
In this example, the MQS_ECHO, which is defined in the MessageQ initialization file, is identified by the -g 5 and -q 12 parameters.
To run the MQS_CLIENT and DMQ_ECHO_SERVER test pair, you must first set up the QMB configuration file and the MessageQ initialization file with the proper parameters. Then, you can invoke the MQS_CLIENT and DMQ_ECHO_SERVER programs.
For example, suppose the target queue of the MQS_CLIENT is DMQ_ECHO_SERVER. In this case, MQS_CLIENT sends to the queue name of the LSQ defined in the DMC320_CONFIG.DAT file that maps to the RSQ (named DMQ_ECHO_SERVER).
Listing B-3 shows the DMC320_CONFIG.DAT file.
Listing B-3 Queue Message Bridge Configuration File
!LSQ Name LSQ RSQ RSQ
!Name Owner Name Association
!
DMQ_ECHO M DMQ_ECHO_SERVER S
Listing B-4 shows the QUEUE CONFIGURATION SECTION in the MessageQ Initialization File (DMQ.INIT) for group 5.
Listing B-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 MessageQ group, the entry shown in Listing B-5 is needed in the GROUP NAME TABLE SECTION:
Listing B-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 DMQ_ECHO_SERVER and MQS_CLIENT programming examples. On the MQSeries system, enter the following command to invoke the MQS_CLIENT program:
% MQS_CLIENT -t DMQ_ECHO -r MQS_CLIENT_REPLYQ
-m QMNAME -l 10 -b 2 -s 1024 -d
Enter the following command on a MessageQ system to invoke the DMQ_ECHO_SERVER program:
% DMQ_ECHO_SERVER -d
The MessageQ and MQSeries products both provide programming examples that you can use to see how the product works. You can also use these programs to verify the MessageQ MQSeries Connection installation and configuration. To verify, use the MessageQ Test Utility (dmqtestm or dmqtestc) and the MQSeries programming examples (amqsget0 and amqsput0). With these programming examples and the Test Utility, simple datagram message exchange is achieved between queue messaging environments (MessageQ and MQSeries) if qmbsrv (MessageQ MQSeries Connection server) is a properly configured pair.
For more information about the MessageQ Test Utility, see the MessageQ Programmer's Guide.
For information about the MQSeries amqsget0 and amqsput0 programming examples, see the IBM MQSeries documentation set.
You can perform simple datagram messaging with out-of-the-box MessageQ and MQSeries test tools and examples, if there is a properly configured qmbsrv 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 MessageQ type and class fields and to fill in the MQSeries MQS_CLIENT_REPLYQ fields.
MessageQ MQSeries Connection provides an example DMC320_CONFIG.DAT file, DMC320_DMQ_GROUP.INIT file, an MQSC command file AMQSQMB.CFG, and example scripts to start a qmbsrv pair.
The following examples are based on the configuration established and the queue associations defined in the DMC320_CONFIG.DAT file.
Note:
Use the DMQ320_DMQ.INIT file for MessageQ startup. You can copy this file from the /usr/kits/DMC32B/examples (or /usr/kits/DMC32C/examples)directory.
To send an MQSeries message to MessageQ, follow these steps:
amqsput0 on the system running MQSeries. Invoke
amqsput0 with the name of the target queue and the queue manager name. The
target queue is the name of the MQSeries LSQ, which maps to the MessageQ RSQ
through the DMC320_CONFIG.DAT file. For example:
In this example, the # amqsput0
target-queue QMNAMEtarget-queue is the name of the MQSeries LSQ.
amqsput0 starts, it prints the start message and the name of the target
queue.
Hello message 1 from MQSeries
amqsput0 expects another message. Enter it. Once amqsput0 gets a second
message, it prints it as well. For example:
To terminate amqsput0, enter ctl-d.
On the MessageQ side, you can test the connection using either dmqtestc or dmqtestm. Follow this procedure:
dmqtestm or dmqtestc programs. The dmqtestc and dmqtestm
programs, once invoked, display their main menu. For example:
% dmqtestc
Main Menu
1 Parameters
2 Actions
3 Exit
Enter Menu Selection >> 1