Context containers

In some situations, user-written message handler programs, and header processing programs, need information about the context in which they are called. CICS® provides this information in a set of context containers, which are passed to the programs.

CICS initializes the contents of each context container, but, in some cases, you can change the contents in your message handler programs, and header processing program. For example, in a service provider pipeline in which the terminal handler is one of the CICS-provided SOAP handlers, you can change the user ID and transaction ID of the target application program by modifying the contents of the appropriate context containers; in this case, a context switch occurs causing the program named in the <apphandler> element to run in a separate task.

Some of the information provided in the containers applies only to a service provider, or only to a service requester, and therefore some of the context containers are not available in both.

DFH-EXIT-HEADER1 container

DFH-EXIT-HEADER1 is a container of DATATYPE(CHAR). It contains one or more SOAP headers that are added to a response from a web service provider application in CICS.

Programs running global user exit XWSPRRWO can add a header to a SOAP response. The header must be valid SOAP and the name spaces must be self-contained in the header XML. A program that puts data in this container must check for its presence and add the new header to the end of the data. By following this best practice, multiple programs can be driven at the same exit point if required.

DFH-HANDLERPLIST container

DFH-HANDLERPLIST is a container of DATATYPE(CHAR) that is initialized with the contents of the appropriate <handler_parameter_list> element of the pipeline configuration file. If you have not specified a handler parameter list in the pipeline configuration file, the container is empty; that is, it has a length of zero. You cannot change the contents of this container.

DFH-SERVICEPLIST container

DFH-SERVICEPLIST is a container of DATATYPE(CHAR) that contains the contents of the <service_parameter_list> element of the pipeline configuration file. If you have not specified a service parameter list in the pipeline configuration file, the container is empty; that is, it has a length of zero. You cannot change the contents of this container.

DFHWS-APPHANDLER container

DFHWS-APPHANDLER is a container of DATATYPE(CHAR) that, in a service provider pipeline, is initialized with the contents of the <apphandler> element of the pipeline configuration file.

In the terminal handler of a pipeline that contains the <apphandler> element, the supplied SOAP handlers get the name of the target application program from this container.

You can change the contents of this container in your message handlers or header-processing programs.

CICS does not provide this container in a service requester pipeline.

DFHWS-APPHANCLAS container

DFHWS-APPHANCLAS is a container of DATATYPE(CHAR) that, in a service provider pipeline, is initialized with the contents of the <apphandler_class> element of the pipeline configuration file.

In the terminal handler of a Java-based pipeline, the supplied SOAP handlers, <cics_soap_1.1_handler_java> and <cics_soap_1.2_handler_java>, get the name of the target application program from this container.

CICS does not provide this container in a service requester pipeline.

DFHWS-DATA container

Container DFHWS-DATA is used in service requester applications and optionally in service provider applications that are deployed with the CICS web services assistant. DFHWS-DATA is a container of DATATYPE(BIT) that holds the top-level data structure that is mapped to and from a SOAP request.

In service requester applications, the DFHWS-DATA container must be present when the service requester program issues an EXEC CICS INVOKE SERVICE command. When the command is issued, CICS converts the data structure that is in the container into a SOAP request. When the SOAP response is received, CICS converts it into another data structure that is returned to the application in the same container.

In service provider applications, the DFHWS-DATA container is used by default when you do not specify the CONTID parameter on the DFHLS2WS or DFHWS2LS batch jobs. CICS converts the SOAP request message into the data structure that is passed to the application in the DFHWS-DATA container. The response is then saved in the same container, and CICS converts the data structure into a SOAP response message.

DFHWS-DPLTRANID container

DFHWS-DPLTRANID is a container of DATATYPE(CHAR) that can contain the transaction identifier of the mirror task to be used to run the target application program remotely. If this container is created in a service provider pipeline, it should contain the transaction identifier of the mirror task to be used to run the application in a remote region. If the container is to have any effect, it must be created before control is passed to the target application program. If the container is not present, remote web service application programs are executed under the default mirror transaction, CSMI.

DFHWS-FAULT container

DFHWS-FAULT is a container of DATATYPE(BIT) that holds information about the type of SOAP fault CICS generates. The container holds a binary fullword that indicates the fault type that can be used in further processing for a web service response:
  1. The most recent SOAP fault was for a CICS fault (for example, CICS or user abend).
  2. The most recent SOAP fault was for an application fault. The container is deleted when you issue the EXEC CICS SOAPFAULT DELETE command. If a second or new SOAP fault is created, CICS updates the new container appropriately.

You cannot change the contents of this container.

DFHWS-LOCATION container

DFHWS-LOCATION is a container of DATATYPE(CHAR) that contains the supplied Location header when the HTTP response was 302, 303 or 307.

DFHWS-MEP container

DFHWS-MEP is a container of DATATYPE(BIT) that holds a representative value for the message exchange pattern (MEP) of an inbound or outbound SOAP message. This value is one byte in length.

CICS supports four message exchange patterns for both service requesters and service providers. The message exchange pattern is defined in the WSDL 2.0 document for the web service and determines whether CICS responds as the provider, and whether CICS expects a response from an external provider. In requester mode, the time that CICS waits for a response is configured with the PIPELINE resource.

If you used the CICS web services assistant to deploy your application, this container is populated by CICS:

  • In a service provider pipeline, this container is populated by the DFHPITP application handler when it receives the inbound message from the terminal handler.
  • In a service requester pipeline, this container is populated when the application uses the INVOKE SERVICE command.

If the application uses the DFHPIRT channel to start the pipeline, the application populates this container. If the container is not present or has no value, CICS assumes that the request is using either the In-Out or In-Only MEP, depending on whether the DFHNORESPONSE container is present in the channel.

This container is populated by the supplied application handler program, DFHPITP. If you use a different application handler, then this container is not available for use.

Table 1. Values that can appear in container DFHWS-MEP
Value MEP URI
1 In-Only http://www.w3.org/ns/wsdl/in-only
2 In-Out http://www.w3.org/ns/wsdl/in-out
4 Robust-In-Only http://www.w3.org/ns/wsdl/robust-in-only
8 In-Optional-Out http://www.w3.org/ns/wsdl/in-opt-out

DFHWS-OPERATION container

Container DFHWS-OPERATION is usually used in a service provider application deployed with the CICS web services assistant. DFHWS-OPERATION is a container of DATATYPE(CHAR) that holds the name of the operation that is specified in a SOAP request.

In a service provider, the container supplies the name of the operation for which the application is being called. It is populated when a supplied SOAP message handler passes control to the target application program, and is visible only when the target program is called with a channel interface.

In a service requester pipeline, the container holds the name specified in the OPERATION option of the EXEC CICS INVOKE SERVICE command. The container is not available to the application that issues the command.

This container is populated by the supplied application handler program, DFHPITP. If you use a different application handler then this container is not available for use.

DFHWS-PIPELINE container

DFHWS-PIPELINE is a container of DATATYPE(CHAR) that contains the name of the PIPELINE in which the program is being run. You cannot change the contents of this container.

DFHWS-RESPWAIT container

DFHWS-RESPWAIT is a container of DATATYPE(BIT) that contains an unsigned fullword binary number to represent the timeout in seconds that applies to outbound web service request and response messages.

The value of this container is supplied by the RESPWAIT attribute of the PIPELINE definition and is set by CICS when the INVOKE SERVICE command is issued. Any value set in this container by the user application before the INVOKE SERVICE command is issued will be ignored.

A message handler program that is invoked during pipeline processing can overwrite the value of the DFHWS-RESPWAIT container. If this is done, the updated value is only used if the PIPELINE definition has a RESPWAIT attribute that is not set to DEFT or left blank. If the PIPELINE definition has the RESPWAIT attribute set to DEFT or left blank, the default timeout value of the transport protocol is always used, regardless of the value in the DFHWS-RESPWAIT container.

This container is used only in requester mode pipelines.

DFHWS-SOAPLEVEL container

DFHWS-SOAPLEVEL is a container of DATATYPE(BIT) that holds information about the level of SOAP used in the message that you are processing. The data is a binary fullword and is one of the following values:
1
The request or response is a SOAP 1.1 message.
2
The request or response is a SOAP 1.2 message.
10
The request or response is not a SOAP message.

You cannot change the contents of this container.

DFHWS-TRANID container

DFHWS-TRANID is a container of DATATYPE(CHAR) that is initialized with the transaction ID of the task in which the pipeline is running.

If you change the contents of this container in a service provider pipeline in which the terminal handler is one of the CICS-supplied SOAP handlers (and you do so before control is passed to the target application program), the target application runs in a new task with the new transaction ID.

New tasks cannot be started when both the terminal handler and the application handler of a pipeline run in the same JVM server. For this reason, if you deploy JAX-WS Axis2 applications into CICS, DFHWS-TRANID cannot be used to change the transaction ID.

DFHWS-URI container

DFHWS-URI is a container of DATATYPE(CHAR) that contains the URI of the service.

In a service provider pipeline, CICS extracts the relative URI from the incoming message and places it in the DFHWS-URI container.

In a service requester pipeline, CICS puts the URI that is specified on the INVOKE SERVICE command, or, if missing, the URI from the web service binding, in the DFHWS-URI container. You can override this URI by using a message handler in the pipeline.

For details, see Using the DFHWS-URI container.

DFHWS-URI-RESID container

Container DFHWS-URI-RESID is available only to applications attached by a JSON pipeline. DFHWS-URI-RESID is a container of DATATYPE(CHAR) that holds a simplified copy of the URI path (a RESource IDentifier), in which the path URI fragment that was used for URIMAP matching has been removed.

Example
Assume that the URIMAP that matched the incoming request has a PATH of /JSONServices/CustomerDetails/* and that the incoming URI from the client was

http://www.example.org:10000/JSONServices/CustomerDetails/customerNumber/13388?action=query

Then the contents of DFHWS-URI-RESID would be: customerNumber/13388

RESTful JSON applications can use this container to help identify the resource id (or primary key) for RESTful resources that are matched using a wild-carded URIMAP. This should be significantly simpler than parsing through the contents of DFHWS-URI.
Note:
  • If the PATH attribute of the matching URIMAP isn't wild-carded (i.e. it contained the complete Path for the URI), the contents of this container will be empty.
  • The PATH attribute of the matching URIMAP may contain an optional query string fragment. If so, the query string fragment is ignored when constructing this container.

DFHWS-URI-QUERY container

Container DFHWS-URI-QUERY is available to application programs in all HTTP provider mode CICS pipelines. DFHWS-URI-QUERY is a container of DATATYPE(CHAR) that holds the query string fragment of the URI.

Example
Assume that the incoming URI from the client was

http://www.example.org:10000/JSONServices/CustomerDetails/customerNumber/13388?action=query&page=1

Then the contents of DFHWS-URI-QUERY would be: action=query&page=1

Applications may parse through the contents of this container to identify individual name=value parameters from the URI.

Note: If the incoming URI did not include a query string, then this container will not be present on the channel.

DFHWS-URIMAP container

DFHWS-URIMAP is a container of DATATYPE(CHAR). In a requester pipeline, DFHWS-URIMAP contains the 8-character name of the URIMAP used on the INVOKE SERVICE command, or 8 blanks if a URIMAP was not specified. For a provider pipeline, DFHWS-URIMAP contains the 8-character name of the URIMAP that matched the inbound request. You cannot change the contents of this container.

DFHWS-URIMAPPATH container

DFHWS-URIMAPPATH is a container of DATATYPE(CHAR) that holds a copy of the PATH data from the URIMAP that was used to match the incoming URI. Any pipeline attached application may make use of this container to understand more about how it came to be attached.

DFHWS-USERID container

DFHWS-USERID is a container of DATATYPE(CHAR) that is initialized with the user ID of the task in which the pipeline is running.

If you change the contents of this container in a service provider pipeline in which the terminal handler is one of the CICS-supplied SOAP handlers (and you do so before control is passed to the target application program), the target application runs in a new task that is associated with the new user ID. Unless you change the contents of container DFHWS-TRANID, the new task has the same transaction ID as the task in which the pipeline is running.

New tasks cannot be started when both the terminal handler and the application handler of a pipeline run in the same JVM server. For this reason, if you deploy JAX-WS Axis2 applications into CICS, DFHWS-USERID cannot be used to change the user ID.

DFHWS-WEBSERVICE container

DFHWS-WEBSERVICE is a container of DATATYPE(CHAR), and it holds the name of the web service that specifies the execution environment when the target application has been deployed by using the web services assistant.

DFHWS-CID-DOMAIN container

DFHWS-CID-DOMAIN is a container of DATATYPE(CHAR). It contains the domain name that is used to generate content-ID values for referencing binary attachments. The value of the domain name is cicsts by default. You can override the value by specifying the <mime_options> element in the pipeline configuration file. You cannot change the contents of this container.

DFHWS-MTOM-IN container

DFHWS-MTOM-IN is a container of DATATYPE(BIT) that holds information about the specified options for the <cics_mtom_handler> element of the pipeline configuration file and information about the message format that has been received in the pipeline. It contains the information to process an inbound MTOM message in the pipeline. The inbound message can be a request message from a web service requester or a response message from a web service provider.

If you do not specify a <cics_mtom_handler> element in the pipeline configuration file, or if a SOAP message is received instead of an MTOM message, this container is not created.

If web services security is configured in the pipeline, or if validation is switched on for a web service, the contents of field XOP_MODE in DFHWS-MTOM-IN can be overridden by CICS when the container is created. For example, if you configure the pipeline to process the content of MTOM messages in direct mode, and you then switch validation on for the web service, CICS overrides the defined value in the pipeline configuration file and sets the XOP processing to run in compatibility mode. CICS performs the override because of the restrictions in support for processing XOP documents and binary attachments in the pipeline.

You cannot change the contents of this container.

Table 2. Structure of the DFHWS-MTOM-IN container
Field name Length (bytes) Contents
MTOM_STATUS 4 Contains the value "1", indicating that the message received by CICS is in MTOM format.
MTOMNOXOP_STATUS 4 Contains one of the following values:
0
The MTOM message contains binary attachments.
1
The MTOM message does not contain binary attachments.
XOP_MODE 4 Contains one of the following values:
0
No XOP processing takes place.
1
XOP processing takes place in compatibility mode.
2
XOP processing takes place in direct mode.

DFHWS-MTOM-OUT container

DFHWS-MTOM-OUT is a container of DATATYPE(BIT) that holds information about the specified options for the <cics_mtom_handler> element of the pipeline configuration file. It contains the information to process an outbound MTOM message in the pipeline, whether it is a response message for a web service requester or a request message for a web service provider.

If you do not specify a <cics_mtom_handler> element in the pipeline configuration file, or if the <mtom_options> element in the pipeline configuration file has the attribute send_mtom="no", this container is not created.

In provider mode, this container is created at the same time as the DFHWS-MTOM-IN container. If the <mtom_options> element in the pipeline configuration file has the attribute send_mtom="same", the MTOM_STATUS field is set to indicate whether the web service requester wants an MTOM or SOAP response message.

If web services security is configured in the pipeline, or if validation is switched on for a web service, the XOP_MODE field of DFHWS-MTOM-OUT can be changed by CICS when the container is created. For example, if you configure the pipeline to process the XOP document and any binary attachments using direct mode, and you then switch validation on for a web service, CICS overrides the defined value in the pipeline configuration file and sets the XOP processing to run in compatibility mode when it creates the container. CICS performs the override because of restrictions in support for processing XOP documents and binary attachments in the pipeline.

You cannot change the contents of this container.

Table 3. Structure of the DFHWS-MTOM-OUT container
Field name Length (bytes) Contents
MTOM_STATUS 4 Indicates whether MTOM is enabled:
0
MTOM is not enabled. The outbound message is sent in SOAP format.
1
MTOM is enabled. The outbound message is sent in MTOM format.
MTOMNOXOP_STATUS 4 Indicates whether to use MTOM when there are no binary attachments:
0
Do not send an MTOM message when there are no binary attachments.
1
Send an MTOM message when there are no binary attachments.
XOP_MODE 4 Indicates what XOP processing should take place:
0
No XOP processing takes place.
1
XOP processing takes place in compatibility mode.
2
XOP processing takes place in direct mode.

DFHWS-WSDL-CTX container

Container DFHWS-WSDL-CTX is used in either a service provider or a service requester application deployed with the CICS web services assistant. DFHWS-WSDL-CTX is a container of DATATYPE(CHAR) that holds WSDL context information that can be used for monitoring purposes.

DFHWS-WSDL-CTX holds the following context information for the WSDL document:
  • The name and namespace of the operation for which the application is being invoked.
  • If known, the name and namespace for the WSDL 1.1 port or WSDL 2.0 endpoint that is being used.

These values are separated by space characters. DFHWS-WSDL-CTX is populated by CICS only at runtime level 2.1 and later.

If you used the CICS web services assistant to deploy your application, this container is populated by CICS:
  • In a service provider pipeline, this container is populated by the DFHPITP application handler when it receives the inbound message from the terminal handler.
  • In a service requester pipeline, this container is populated when the application uses the INVOKE SERVICE command.

If the application uses the DFHPIRT program to start the pipeline, the application populates the DFHWS-WSDL-CTX container if required.

DFHWS-XOP-IN container

DFHWS-XOP-IN is a container of DATATYPE(BIT) that contains a list of references to the binary attachments that have been unpackaged from an inbound MIME message and placed in containers using XOP processing.

Each attachment record in the DFHWS-XOP-IN container consists of these items:
  • The 16-byte name of the container that holds the MIME headers for the binary attachment
  • The 16-byte name of the container that holds the binary attachment
  • The 2-byte length of the content-ID, in signed halfword binary format
  • The content-ID, including the < and > delimiters, stored as an ASCII character string

You cannot change the contents of this container.

DFHWS-XOP-OUT container

DFHWS-XOP-OUT is a container of DATATYPE(BIT) that contains a list of references to the containers that hold binary attachments. The binary attachments are packaged into an outbound MIME message by the MTOM handler program.

Each attachment record in the DFHWS-XOP-OUT container consists of these items:
  • The 16-byte name of the container that holds the MIME headers for the binary attachment
  • The 16-byte name of the container that holds the binary attachment
  • The 2-byte length of the content-ID, in signed halfword binary format
  • The content-ID, including the < and > delimiters, stored as an ASCII character string

You cannot change the contents of this container.