Message handlers and the message handler interface

A message handler is a CICS® program that is used to process a web service request during input and to process the response during output. Message handlers use channels and containers to interact with one another and with the system.

The CICS pipeline links to the message handlers using a channel containing a number of containers. Some containers are optional, others are required by all message handlers, and others are used by some message handlers, and not by others. Before a handler is invoked, some or all of the containers are populated with information which the handler can use to perform its work. The containers returned by the handler determine the subsequent processing, and are passed on to later handlers in the pipeline. For an introduction to message handlers and pipelines and an overview of the operation of a pipeline, see Message handlers and pipelines.

The message handler interface lets you perform the following tasks in a message handler program:

Examine the contents of an XML or JSON request or response, without changing it. Your message handler program can retrieve the request from container DFHREQUEST; it can retrieve the response from container DFHRESPONSE.
Change the contents of an XML or JSON request or response.
In a non-terminal message handler, pass an XML or JSON request or response to the next message handler in the pipeline. See Passing a message to the next message handler in the pipeline.
It is the contents of the containers which a message handler returns that determines which message handler is invoked next. See How containers DFHFUNCTION, DFHREQUEST, and DFHRESPONSE control the pipeline protocols.
In a terminal message handler, call an application program, and generate a response. See Working with messages in a terminal message handler.
In the request phase of the pipeline, force a transition to the response phase, by absorbing the request, and generating a response. See Handling one way messages in a service requester pipeline.
Handle errors. Message handlers should be designed to handle errors that might occur in the pipeline; see Handling errors.

Tip: It is advisable to use the SOAP handlers, <cics_soap_1.1_handler>, <cics_soap_1.2_handler>, <cics_soap_1.1_handler_java> or <cics_soap_1.2_handler_java>, to work with SOAP messages. These handlers let you work directly with the major elements in a SOAP message (the SOAP headers and the SOAP body). See CICS-supplied SOAP message handlers.

Deprecated feature: Support for the JVMSERVER-based configuration option for the web services data transformation service is deprecated. The deprecated options can be replaced with the use of a non-Java pipeline for CICS web services, z/OS Connect Enterprise Edition, or by writing web applications in Java or Node.js. For more details, see Stabilization notices.

All programs that are used as message handlers are invoked with the same interface: they are invoked with a channel that holds a number of containers. The containers can be categorized as the following types:

Control containers

These are essential to the operation of the pipeline. Message handlers can use the control containers to modify the sequence in which subsequent handlers are processed. For reference information about these containers, see Control containers.

Context containers

In some situations, message handler programs need information about the context in which they are invoked. CICS provides this information in a set of context containers that are passed to the programs.

Some of the context containers hold information that you can change in your message handler. For example, in a service provider pipeline, you can change the user ID and transaction ID of the target application program by modifying the contents of the appropriate context containers.

For reference information about these containers, see Context containers.

User containers

These contain information that one message handler needs to pass to another. The use of user containers is entirely a matter for the message handlers.

Restriction: Do not use names that start with DFH for user containers.