Working with messages in a non-terminal message handler

A typical non-terminal message handler processes a message, then passes control to another message handler in the pipeline.

About this task

In a non-terminal message handler, you can work with a request or response, with or without changing it, and pass it on to the next message handler.
Note: Although web services typically use SOAP messages which contain XML, your message handlers will work as well with other message formats

Procedure

  1. Using the contents of container DFHFUNCTION, determine if the message passed to this message handler is a request or a response.
    DFHFUNCTION Request or response Type of message handler Inbound or outbound
    RECEIVE-REQUEST Request Non-terminal Inbound
    SEND-RESPONSE response Non-terminal Outbound
    SEND-REQUEST Request Non-terminal Outbound
    RECEIVE-RESPONSE response Non-terminal Inbound
    Tip:
    • If DFHFUNCTION contains PROCESS-REQUEST, the message handler is a terminal message handler, and these steps do not apply.
    • If DFHFUNCTION contains HANDLER-ERROR, the handler is being called for error processing, and these steps do not apply.
  2. Retrieve the request or the response from the appropriate container.
    • If the message is a request, it is passed to the program in container DFHREQUEST. Container DFHRESPONSE is also present, with a length of zero.
    • If the message is a response, it is passed to the program in container DFHRESPONSE.
  3. Perform any processing of the message which is required.
    Depending upon the purpose of the message handler, you might:
    • Examine the message without changing it, and pass it to the next message handler in the pipeline.
    • Change the request, and pass it to the next message handler in the pipeline.
    • If the message is a request, you can bypass the following message handlers in the pipeline, and, instead, construct a response message.
    Note: It is the contents of the containers which a message handler returns that determines which message handler is invoked next.

    It is an error if a message handler makes no changes to any of the containers passed to it.

    It is an error for a message handler program to return any of the following:
    • An empty DFHRESPONSE container.
    • A non-empty DFHREQUEST container and a non-empty DFHRESPONSE container.
    • An empty DFHREQUEST container on the outbound request.