Message handlers

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 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
  • 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
  • In a terminal message handler, call an application program, and generate a response
  • In the request phase of the pipeline, force a transition to the response phase, by absorbing the request, and generating a response
  • Handle 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).
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.
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.

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.