The CICS Asynchronous Consumption and Publish/Subscribe sample on z/OS

The Asynchronous Consumption and Publish/Subscribe sample programs demonstrate the use of asynchronous consumption, and publish and subscribe features within CICS®.

A Registration client program registers three Callback handlers (an event handler, and two message consumers), and starts Asynchronous Consumption. A Messaging client program puts messages to a queue, or publishes suitable messages from a CICS console for consumption by the two Message Consumers (CSQ4CVCN and CSQ4CVCT).

To provide runtime control over the behavior of the sample, one of the message consumers can be instructed using the messages it receives, to SUSPEND, RESUME, or DEREGISTER any of the Callback handlers. It can also be used to issue an MQCTL STOP to end Asynchronous Consumption under control. The other message consumer is registered to subscribe to a topic.

Each program issues COBOL DISPLAY statements at appropriate points to display the behavior of the sample.

The applications use these MQI calls:

The programs are delivered in the COBOL language. See CICS Asynchronous Consumption and Publish/Subscribe samples for the CICS applications. This topic also provides the following information:


Setup

The names of the Queue and Topic used by the Message Consumers are hardcoded in the Registration and Messaging Client programs.

The Queue, SAMPLE.CONTROL.QUEUE, should be defined to the Queue Manager associated with the CICS region before running the sample. The Topic, News/Media/Movies, can be defined if required, or it is created at runtime under the default Administrative Object if it does not exist.

CICS programs and transaction definitions can be installed by installing a group: CSQ4SAMP.


Registration Client CSQ4CVRG

The Registration Client program must be started under the CICS transaction MVRG. It takes no input.

When started, the Registration Client registers the following Callback handlers using MQCB:

  • CSQ4CVEV as an Event Handler.
  • CSQ4CVCN as a Message Consumer on a topic, News/Media/Movies.
  • CSQ4CVCT as a Message Consumer on a Queue, SAMPLE.CONTROL.QUEUE.
The Registration Client passes a data structure containing the names of all three registered Callback handlers to CSQ4CVCT, together with the object handles associated with the two message consumers.

Having registered the Callback handlers, the Registration Client issues an MQCTL START_WAIT to start Asynchronous Consumption, and suspend until control is returned to it (for example, by one of the Callback handlers issuing an MQCTL STOP).


Event handler CSQ4CVEV

When driven, the Event Handler displays a message indicating the call type (for example, START). When driven for IBM MQ reason code CONNECTION_QUIESCING, the Event Handler issues an MQCTL STOP to end Asynchronous Consumption and return control to the Registration Client.


Simple Message Consumer CSQ4CVCN

When driven, this Message Consumer displays a message indicating the call type (for example, REGISTER). When driven for the MSG_REMOVED call type, the Message Consumer retrieves the inbound message and outputs it to the CICS job log.


Control Message Consumer CSQ4CVCT

When driven, this Message Consumer displays a message indicating the call type (for example, START). When driven for the MSG_REMOVED call type, the Message Consumer retrieves the inbound message and the data structure passed by the Registration Client. Based on the message content, it issues appropriate MQCB or MQCTL commands to one of the following:

  • STOP Asynchronous Consumption (returning control to the Registration Client).
  • SUSPEND, RESUME, or DEREGISTER a named Callback handler (including itself).


Messaging Client CSQ4CVPT

The Messaging Client has two functions:

  • It publishes a message to a topic for consumption by the Message Consumer CSQ4CVCN.
  • It puts a control message to a queue for consumption by the Control Message Consumer CSQ4CVCT, resulting in a potential change in behavior of the sample.

The Messaging Client program must be started from a CICS console under a CICS transaction, and it takes command line input with the following syntax:

CSQ4CVPT

MVMP , PUBLISH,,?Message Text,STOP,DEREGISTER,RESUME,SUSPEND,Callback Handler,

    PUBLISH
    Publish the Message Text (or a default message) as a Retained Message for consumption by the Simple Message Consumer.

    STOP
    Stop Asynchronous Consumption.

    DEREGISTER
    Deregister the named Callback handler.

    RESUME
    Resume the named Callback handler.

    SUSPEND
    Suspend the named Callback handler.

Input fields are positional, and comma-separated. Keywords and Callback Handler names are not case-sensitive.

Examples:
Table 1. Input examples
Example Description
MVMP,PUBLISH,, Publish a default message
MVMP,publish, A short message, Publish the given text
MVMP,STOP, Stop Asynchronous Consumption
MVMP,DEREGISTER,CSQ4CVEV, Deregister the Event Handler
MVMP,resume,csq4cvcn, Resume the Simple Message Consumer
MVMP,SUSPEND,CSQ4CVEV, Suspend the Event Handler
Where MVMP is the CICS transaction associated with the Messaging Client program CSQ4CVPT. Note:

  • Suspending or deregistering all Callback handlers terminates the START_WAIT issued by the Registration Client, returning control to it, and ending the task.
  • Suspending or deregistering the Control Callback Handler has deliberately not been prevented, but it removes the ability to further control the behavior of the sample.