The Echo sample programs
The Echo sample programs echo a message from a message queue to the reply queue.
See Features demonstrated in the sample programs on Multiplatforms for the names of these programs.
The programs are intended to run as triggered programs.
On IBM i, UNIX, Linux, and Windows systems, their only input is an MQTMC2 (trigger message) structure that contains the name of a target queue and the queue manager. The COBOL version uses the default queue manager.
On IBM i, for the triggering process to work, ensure that the Echo sample program that we want to use is triggered by messages arriving on queue SYSTEM.SAMPLE.ECHO. To do this, specify the name of the Echo sample program that we want to use in the ApplId field of the process definition SYSTEM.SAMPLE.ECHOPROCESS. (For this, we can use the CHGMQMPRC command; for details, see Change MQ Process (CHGMQMPRC).) The sample queue has a trigger type of FIRST, so, if there are already messages on the queue before you run the Request sample, the Echo sample is not triggered by the messages that you send.
When you have set the definition correctly, first start AMQSERV4 in one job, then start AMQSREQ4 in another. You could use AMQSTRG4 instead of AMQSERV4, but potential job submission delays could make it less easy to follow what is happening.
Use the Request sample programs to send messages to queue SYSTEM.SAMPLE.ECHO. The Echo sample programs send a reply message containing the data in the request message to the reply-to queue specified in the request message.
Design of the Echo sample programs
The program opens the queue named in the trigger message structure that it was passed when it started. (For clarity, this is referred to as the request queue.) The program uses the MQOPEN call to open this queue for shared input.
The program uses the MQGET call to remove messages from this queue. This call uses the MQGMO_ACCEPT_TRUNCATED_MSG, MQGMO_CONVERT, and MQGMO_WAIT options, with a wait interval of 5 seconds. The program tests the descriptor of each message to see if it is a request message; if it is not, the program discards the message and displays a warning message.
For each line of input, the program then reads the text into a buffer and uses the MQPUT1 call to put a request message, containing the text of that line, onto the reply-to queue.
If the MQGET call fails, the program puts a report message on the reply-to queue, setting the Feedback field of the message descriptor to the reason code returned by the MQGET.
When there are no messages remaining on the request queue, the program closes that queue and disconnects from the queue manager.
On IBM i, the program can also respond to messages sent to the queue from platforms other than IBM MQ for IBM i, although no sample is supplied for this situation. To make the ECHO program work:
- Write a program, correctly specifying the Format, Encoding, and CCSID parameters, to send text request messages.
The ECHO program requests the queue manager to perform message data conversion, if this is needed.
- Specify CONVERT(*YES) on the IBM MQ for IBM i sending channel, if the program that we have written does not provide similar conversion for the reply.
Parent topic: Use the sample programs on Multiplatforms