Control containers

The control containers are essential to the operation of the pipeline. Handlers can use the control containers to modify the sequence in which the handlers are processed.

DFHERROR container

DFHERROR is a container of DATATYPE(BIT) that is used to convey information about pipeline errors to other message handlers.

Table 1. Structure of the DFHERROR container
Field name	Length	Contents
PIISNEB-MAJOR-VERSION	1 byte	1
PIISNEB-MINOR-VERSION	1 byte	1
PIISNEB-ERROR-TYPE	1 byte	A numeric value denoting the type of error. See Values for the PIISNEB-ERROR-TYPE field.
PIISNEB-ERROR-MODE	1 byte	Possible values are as follows: P The error occurred in a provider pipeline. R The error occurred in a requester pipeline. T The error occurred in a Trust client.
PIISNEB-ABCODE	4 bytes	The abend code when the error is associated with a transaction abend.
PIISNEB-ERROR-CONTAINER1	16 bytes	The name of the container when the error is associated with a container.
PIISNEB-ERROR-CONTAINER2	16 bytes	The name of the second container when the error is associated with more than one container.
PIISNEB-ERROR-NODE	8 bytes	The name of the handler program in which the error occurred.

Values for the PIISNEB-ERROR-TYPE field

1: The handler program failed. The abend code is in field PIISNEB-ABCODE.
2: A container required by the handler was empty. The name of the container is in field PIISNEB-ERROR-CONTAINER1.
3: A container required by the handler was missing. The name of the container is in field PIISNEB-ERROR-CONTAINER1.
4: Two containers were passed to the handler when only one was expected. The names of the containers are in fields PIISNEB-ERROR-CONTAINER1 and PIISNEB-ERROR-CONTAINER2.
5: An attempt to link to the target program failed. If the target program failed, the abend code is in container PIISNEB-ABCODE.
6: The pipeline manager failed to communicate with a remote server because of an error in the underlying transport.
7: The DFHWS-STSACTION container has an error. It is missing, corrupt, or contains an incorrect value.
8: DFHPIRT failed to start the pipeline.
9: DFHPIRT failed to put a message in a container.
10: DFHPIRT failed to get a message from a container.
11: An unhandled error has occurred.

The COBOL declaration of the container's structure is shown in Figure 1.

Figure 1. COBOL declaration

  01 PIISNEB.                              
  02 PIISNEB-MAJOR-VERSION PIC X(1).     
  02 PIISNEB-MINOR-VERSION PIC X(1).     
  02 PIISNEB-ERROR-TYPE PIC X(1).        
  02 PIISNEB-ERROR-MODE PIC X(1).        
  02 PIISNEB-ABCODE PIC X(4).            
  02 PIISNEB-ERROR-CONTAINER1 PIC X(16). 
  02 PIISNEB-ERROR-CONTAINER2 PIC X(16). 
  02 PIISNEB-ERROR-NODE PIC X(8).

Table 2 lists the language copybooks that map the container.

Table 2. Copybooks that map the container
Language	Copybook
COBOL	DFHPIUCO
PL/I	DFHPIUCL
C® and C++	dfhpiuch.h
Assembler	DFHPIUCD

DFHFUNCTION container

Container DFHFUNCTION indicates where in a pipeline a program is being called. See DFHFUNCTION container.

DFHHTTPMETHOD container

Container DFHHTTPMETHOD is available to application programs in all HTTP provider mode CICS® pipelines. DFHHTTPMETHOD holds the name of the HTTP method that was used on the incoming request. It is not populated if the request did not arrive over HTTP.

DFHHTTPMETHOD is a container of DATATYPE(CHAR) and is 8 characters long.

DFHHTTPSTATUS container

Container DFHHTTPSTATUS is used to specify the HTTP status code and status text for a message produced in the response phase of a service provider pipeline. DFHHTTPSTATUS is a container of DATATYPE(CHAR).

The content of the DFHHTTPSTATUS container must be the same as the initial status line of an HTTP response message, which follows this structure: HTTP/1.1 nnn tttttttt

HTTP/1.1: The version and release of HTTP.
nnn: The 3-digit decimal HTTP status code to return.
tttttttt: The human-readable status text associated with the status code nnn.

The following string is an example of the content:

                                                   
  HTTP/1.1 412 Precondition Failed

The DFHHTTPSTATUS container is ignored when the pipeline uses the IBM® MQ transport.

If the container contains more than 45 bytes of data, CICS sends 45 bytes and ignores the remaining data.

DFHMEDIATYPE container

Container DFHMEDIATYPE is used to specify the media type for a message produced in the response phase of a service provider pipeline. DFHMEDIATYPE is a container of DATATYPE(CHAR).

The DFHMEDIATYPE container is ignored when the pipeline uses the IBM MQ transport.

The content of the DFHMEDIATYPE container must consist of a type and a subtype separated by a slash character. The following strings show two examples of correct content for the DFHMEDIATYPE container.

Examples: text/plain; image/svg+xml

DFHNORESPONSE container

In the request phase of a service requester pipeline, container DFHNORESPONSE indicates that the service provider is not expected to return a response. DFHNORESPONSE is a container of DATATYPE(CHAR).

The contents of the DFHNORESPONSE container are undefined; message handlers that need to know if the service provider is expected to return a response need only determine if the container is present or not:

If container DFHNORESPONSE is present, no response is expected.
If container DFHNORESPONSE is absent, a response is expected.

This information is provided, initially, by the service requester application, based on the protocol used with the service provider. Therefore, you are advised not to delete this container in a message handler (or to create it, if it does not exist), because doing so might disturb the protocol between the endpoints.

Other than in the request phase of a service requester pipeline, the use of this container is not defined.

DFHREQUEST container

Container DFHREQUEST contains the request message that is processed in the request phase of a pipeline. DFHREQUEST is a container of DATATYPE(CHAR).

If one of the CICS-supplied SOAP message handlers is configured in the pipeline, the container DFHREQUEST is updated to include the SOAP message headers in the SOAP envelope. If the message is constructed by a CICS-supplied SOAP message handler and has not been changed subsequently, DFHREQUEST contains a complete SOAP envelope and all of its contents is in the UTF-8 code page.

The DFHREQUEST container is present in the request when a message handler is called and the DFHFUNCTION container contains RECEIVE-REQUEST or SEND-REQUEST.

In this situation, the normal protocol is to return DFHREQUEST to the pipeline with the same or modified contents. Processing of the pipeline request phase continues normally, with the next message handler program in the pipeline, if there is one.

As an alternative, your message handler can delete container DFHREQUEST, and put a response in the DFHRESPONSE container. In this way, the normal sequence of processing is reversed, and the processing continues with the response phase of the pipeline.

DFHRESPONSE container

Container DFHRESPONSE contains the response message that is processed in the response phase of a pipeline. If the message was constructed by a CICS-supplied SOAP message handler and has not been changed subsequently, DFHRESPONSE contains a complete SOAP envelope and all its contents in UTF-8 code page. DFHRESPONSE is a container of DATATYPE(CHAR).

The DFHRESPONSE container is present when a message handler is called and the DFHFUNCTION container contains SEND-RESPONSE or RECEIVE-RESPONSE. In this situation, the normal protocol is to return DFHRESPONSE to the pipeline with the same or modified contents. Pipeline processing continues normally, with the next message handler program in the pipeline, if there is one.

The DFHRESPONSE container is also present, with a length of zero, when DFHFUNCTION contains RECEIVE-REQUEST, SEND-REQUEST, PROCESS-REQUEST, or HANDLER-ERROR.

DFHWS-CCSID container

DFHWS-CCSID is a container of DATATYPE(BIT) that contains a fullword (4 bytes) specifying the CCSID of the data in the response container. The container is valid only for a provider mode pipeline that uses CICS code to transform the language structure into XML.

The CCSID must be compatible with the CCSID used to generate the WSBIND file. If it is not, the SOAP response that is produced might contain incorrect or invalid characters.

The CCSID is not allowed to be changed to or from 930, 1390, 5026 and 1026. Also CICS does not allow the CCSID to be changed to one that is usable as a client CCSID.

If there are any problems processing the value in the DFHWS-CCSID container, processing continues using the CCSID from the WSBIND file.

The DFHWS-CCSID container is checked only on return from a channel-driven application program.

DFHWS-NODEJSAPP container

Container DFHWS-NODEJSAPP holds the name of the NODEJSAPP resource for this pipeline. The container is valid only for a provider mode pipeline, and only if the pipeline is started through a NODEJSAPP resource using the invoke function from the ibm-cics-api module. DFHWS-NODEJSAPP is a container of DATATYPE(CHAR).