Context containers

In some situations, CICS® programs need information about the context in which they were called. The CICS service provider sends this information to CICS in context containers.

zosConnect-2.0 Applies to zosConnect-2.0.

The use of context containers is optional and available only with CHANNEL, not COMMAREA, programs. You can enable the function in SAR files for the CICS service provider. To enable this function, use either the Use context containers and Context containers HTTP headers configuration options in the API toolkit, or use the useContextContainers and httpHeaders parameters in the build toolkit. For more information, see Configuring service properties for the API toolkit, or the Creating a CICS service for C or top-down for the build toolkit.

The CICS service provider can send the following context containers, which are all of type CHAR.

DFHWS-URI

The full URL for the request. For example, https://localhost:9080/zosConnect/services/cicsService?action=invoke.

DFHWS-URI-QUERY

The query string for the request. For example, action=invoke.

DFHHTTPMETHOD

The HTTP method for the request. The container is padded with spaces to be 8 characters long.

BAQHTTPHEADERS

Specific headers on the request in a JSON document in the following format.


   { "httpHeaders": 
      { "<headerName>": "<headerValue>", ... } 
   }

For example:


   { "httpHeaders": 
      { "MyHeader": "Somevalue", "SecondHeader": "OtherValue" } 
   }

Note:

The DFHWS-URI-QUERY container is created only if a query string exists in the URL.
The BAQHTTPHEADERS container is created only if the Context containers HTTP headers configuration option is configured for the API toolkit or the httpHeaders parameter is specified for the build toolkit.
Headers are considered optional by the CICS service provider, so if a header is specified in Context containers HTTP headers or httpHeaders but not included in the HTTP request, the service provider does not include the header in the container. It does not treat this situation as an error. For example, if no headers are on the request the container would be as follows:
```
   { "httpHeaders": 
      { } 
   }
```
The headers with DFH names are CICS context containers. DFHHTTPMETHOD is documented by CICS TS as a control container, but z/OS Connect treats it only as a context container as it does not affect how the response is processed. For more information, see Containers used in the pipeline in the CICS Transaction Server for z/OS documentation.
Header names are case-insensitive, so the BAQHTTPHEADERS container uses the same case as the header name specified in Context containers HTTP headers and httpHeaders.
Headers that are specified by Context containers HTTP headers and httpHeaders are not included in any swagger documents for APIs that expose services that use context containers. You must manually add the headers in the request-mapping editor to include them in the API documentation.
If the same header appears multiple times on a request, the BAQHTTPHEADERS container includes only one JSON property for the header, with the values concatenated into a single value. For more information, see HTTP Protocol Specifications RFC 2616.

Migration from the WOLA service provider

If you upgrade from the WOLA service provider to the CICS service provider and use context containers, consider these differences.

Context container names are different for each service provider.

Table 1. Context container names for WOLA and CICS service providers
CICS service provider name	WOLA service provider name
`DFHWS-URI`	`ZCONReqURL`
`DFHWS-URI-QUERY`	`ZCONReqQParms`
`DFHHTTPMETHOD`	`ZCONReqMethod`
`BAQHTTPHEADERS`	`ZCONHTTPHEADERS`

The CICS service provider context containers are all of type CHAR. If the CICS program previously used BIT context containers it must be updated to handle CHAR context containers.
The DFHHTTPMETHOD context container includes the HTTP method name padded with spaces to be 8 characters long, whereas the ZCONReqMethod context container does not include padding.