Design of the samples for asynchronous message consumption

The sample COBOL programs include a registration client and messaging client that run under CICS® transaction s, and three callback routines that consume messages or events from CICS-MQ. Each of the sample programs uses COBOL DISPLAY statements to display messages at appropriate points so that you can observe its behavior.

The messages from the sample programs are sent to the transient data queue CESE, which is the CEEMSG data set. The messages issued by the event handler and message consumers indicate the CICS-MQ call type for which the program was driven, such as START or REGISTER.

Registration client program CSQ4CVRG

The registration client is started from a CICS terminal under the CICS transaction MVRG, but it does not take any input. The registration client registers the event handler CSQ4CVEV, the message consumer CSQ4CVCN, and the message consumer CSQ4CVCT with IBM® MQ as callback routines. It also passes to CSQ4CVCT a data structure containing the names of all three registered callback routines, with the object handles associated with the two message consumers.

When the registration client has registered the callback routines, it issues an MQCTL START_WAIT command to start asynchronous message consumption. It then suspends until control is returned to it.

Control is returned to the registration client if one of the callback routines issues an MQCTL STOP command to stop asynchronous message consumption.

Messaging client program CSQ4CVPT

The messaging client is started from a CICS terminal under the CICS transaction MVMP, and it takes command line input. The messaging client has two functions:
  • Publish a basic text message to the topic News/Media/Movies to be consumed by CSQ4CVCN.
  • Put a control message on the queue SAMPLE.CONTROL.QUEUE to be consumed by CSQ4CVCT. The control messages make CSQ4CVCT issue commands to change the behavior of the set of sample programs, and you can observe the results through the messages displayed by the sample programs.
CSQ4CVPT, sample messaging client explains how to use CSQ4CVPT to create messages.

Message consumer program CSQ4CVCN, for basic messages

CSQ4CVCN is a message consumer that consumes basic IBM MQ messages that you publish under the topic News/Media/Movies , using the messaging client.

When CSQ4CVCN is called with the IBM MQ call type MSG_REMOVED, it retrieves the inbound message and echoes it to the CICS job log.

Message consumer program CSQ4CVCT, for control messages

CSQ4CVCT is a message consumer that consumes IBM MQ messages that you put on the queue SAMPLE.CONTROL.QUEUE. When CSQ4CVCT is called with the IBM MQ call type MSG_REMOVED, it retrieves the inbound message and also the data structure that the registration client passed to it.

You can use the messaging client to create control messages to instruct CSQ4CVCT to take the following actions. CSQ4CVCT issues appropriate MQCB or MQCTL commands to carry out the action that you request:
  • Deregister a specified callback routine
  • Resume a specified callback routine
  • Suspend a specified callback routine
  • Stop asynchronous message consumption by issuing an MQCTL STOP command, returning control to the registration client

You may instruct CSQ4CVCT to suspend or deregister itself, but, if you do that, you can no longer control the behavior of the sample programs. If you suspend or deregister all the callback routines, control returns to the registration client, and the task ends.

Event handler program CSQ4CVEV

As an event handler, CSQ4CVEV receives IBM MQ notifications when a condition occurs that affects the whole callback environment, such as a queue manager stopping or quiescing.

If reason code CONNECTION_QUIESCING is received, CSQ4CVEV issues an MQCTL STOP command to stop asynchronous message consumption and returns control to the registration client.