HTTP header reference for CICS web support

In CICS® web support, CICS automatically provides some HTTP headers on outbound messages and you can also add your own headers. When messages are sent to CICS, CICS takes action in response to some HTTP headers, and a user application program can take action in response to others. This reference information describes how CICS web support handles HTTP headers.

The standard HTTP headers are described in the HTTP/1.1 specification (RFC 2616) and the HTTP/1.0 specification (RFC 1945). There are many possible HTTP headers, including extension headers that are not part of the HTTP protocol specifications. For fuller listings, consult the HTTP specification to which you are working. The HTTP protocol has more information about the HTTP specifications.

This topic explains the general use of HTTP headers in CICS web support, and the actions that CICS web support takes for specific headers. Check the HTTP specification to which you are working for detailed guidance and requirements about how you should use HTTP headers; for example, the correct format for header values, and the contexts in which each header should be used.

HTTP headers on messages received by CICS

When an HTTP request or response is received by CICS, some of the HTTP headers are used to determine actions that CICS web support takes. Table 1 shows the actions taken by CICS for headers on an HTTP request. Table 2 shows the actions taken by CICS for headers on an HTTP response. Other headers are not used by CICS, and it is up to the user application to take appropriate action in response to these.
All headers received for a message, whether or not they have been used by CICS, are made available to a user application for inspection using the WEB READ HTTPHEADER command and the HTTP header browsing commands. CICS does not alert the user application to the presence of any particular header on a message. Ignore any headers that the application does not need or understand.
CICS already deals with the MUST level requirements in the HTTP/1.1 specification relating to actions that the server or client must perform on receiving a message. Because of this, you may receive and use a request or response without examining the headers. However, you probably need to examine the headers for information relating to actions that you take in future communications with the web client or server.
HTTP headers consist of a header name and header value, separated by a colon. The HTTP/1.1 specification states that a single space is preferred between the colon and the header value, and that this common form should be followed. In the HTTP/1.0 specification, this single space was a requirement, but the HTTP/1.1 specification permits applications to use more spaces or no spaces. To preserve backwards compatibility, CICS requires the common form of a single space in some headers where action is taken by CICS during message processing (such as the Content-Length header). If you are designing an application that sends HTTP requests to CICS, ensure that this common form is followed for all HTTP headers, as recommended in the HTTP/1.1 specification. The EXEC CICS WEB WRITE HTTPHEADER command produces headers with the appropriate format, and any headers written automatically by CICS are in the appropriate format.

HTTP headers on messages sent out from CICS

On an HTTP request or response that is sent out from CICS with HTTP/1.1 as its version, CICS automatically supplies key headers that should normally be written for a basic message to be compliant with the HTTP/1.1 specification. On an HTTP response with HTTP/1.0 as its version, CICS automatically supplies a smaller number of headers. Some of these headers are generated by CICS for every message, and some are produced because of options that you specify on the WEB SEND command in a user application program. Table 3 and Table 4 list the headers that are written for each HTTP version, and the source of the header.
If the user application program writes a header that CICS also generates, CICS handles this depending on the situation:
- For CICS as an HTTP server, if the header is appropriate for a response CICS does not overwrite it, but allows the application's version to be used.
- For CICS as an HTTP client, if the header is appropriate for a request CICS does not allow the application to write it, and returns an error response to the WEB WRITE HTTPHEADER command. The exceptions are the TE header and the Content-Type header. Application programs can add further instances of the TE header. They can also supply the Content-Type header, if the required header needs to contain spaces or more than 56 characters, and so cannot be specified on the MEDIATYPE option of the WEB SEND command.
- If the header is not normally appropriate for the type of message (request or response), CICS allows it, as is the case for all user-defined headers. This situation should not occur if your message is compliant with the HTTP specification to which you are working.
A user application program can add further HTTP headers to a request or response using the WEB WRITE HTTPHEADER command. CICS tolerates and passes on any additional HTTP headers. Note that for CICS as an HTTP server, if you are providing a static response with a CICS document template or HFS file, headers cannot be added to the response beyond those that are automatically supplied by CICS.
CICS does not check the name or value of user-written headers. You should ensure that your application program is providing correct, and correctly formatted, information in a way that meets the HTTP specification to which you are working. Be particularly careful to check the HTTP specification for applicable requirements if your application is performing complex actions. There are likely to be important (MUST or SHOULD level) requirements to provide certain headers to describe these actions. For example, special HTTP headers are required if you are performing the following actions:
- Responding to, or making, conditional requests using the modification date of the document or an entity tag.
- Varying the content of a response according to the client capability or national language requirements of the web client.
- Providing a response, or making a request, that involves a range of a document rather than the full document.
- Providing cache control information for a response.
The use of certain status codes on your response might also require particular HTTP headers. For example, if you use the status code 405 (Method not allowed), you must use the Allow header to state the methods that are allowed. HTTP status code reference for CICS web support has more information about the use of status codes.

The Upgrade header

Be aware of the special case that in CICS web support, protocol upgrading is not supported. This means:
- For CICS as an HTTP server, it is not possible for an application to take any action in response to an Upgrade header sent by a web client.
- For CICS as an HTTP client, the Upgrade header must not be written on requests.
CICS does not support a switch in HTTP version during a connection, and upgrades in the security layer are not supported.

CICS as an HTTP server: Headers where CICS takes action on receiving an HTTP request

Table 1 shows the action that CICS takes for certain headers on a request received from a web client.

Table 1. CICS as an HTTP server: CICS actions for headers on an HTTP request
Header received from web client	Action taken by CICS where response is to be handled by user application program	Action taken by CICS where response is to be provided by static document
Authorization	Passes supplied user ID and password to RACF® for verification, and rejects request if these are invalid.	As for application-generated response.
Connection	Carries out web client's request for connection close after sending response.	As for application-generated response.
Content-Length	CICS requires the Content-Length header on all inbound HTTP/1.1 messages that have a message body. If a message body is present but the header is not provided, or its value is inaccurate, the socket receive for the faulty message or for a subsequent message can produce unpredictable results. For HTTP/1.0 messages that have a message body, the Content-Length header is optional.	Although a message body is not used in processing for a static response, it must still be received from the socket, so the same requirements apply as for an application-generated response.
Content-Type	Parses header to identify media type and character set for code page conversion.	Parses header to identify character set for code page conversion of response.
Expect	Sends 100-Continue response to web client and waits for remainder of request.	As for application-generated response.
Host	If this header is not present and the client is HTTP/1.1, sends 400 (Bad Request) response to web client.	As for application-generated response.
If-Modified-Since	No action by CICS. User applications could either check for the presence of this header and respond as appropriate, or ignore the header and assume that the application-generated response has been modified.	Document template: Assumes that the response has been modified and sends the requested item. HFS file: Checks modification date and responds according to result of check. Sends 304 response if item has not been modified.
If-Unmodified-Since	If header is present, always sends 412 (Precondition Failed) response to web client, indicating that the response has been modified since the specified time. (This means that user applications do not have to check for the presence of this header.)	Document template: As for application-generated response, assumes that the response has been modified and sends 412 response. HFS file: Checks modification date and responds according to result of check.
Trailer	Makes individual trailing headers available to application through WEB READ HTTPHEADER command.	Chunked messages are not suitable for a static response.
Transfer-Encoding	For "chunked", receives all chunks and assembles into single message to pass to application. For anything other than "chunked", sends 501 (Not Implemented) response to web client. The Transfer-Encoding header remains on the message, but it is for information only.	Chunked messages are not suitable for a static response.
Warning	Writes warning text to the TS queue CWBW. If more than 128 characters are used, the warning text is truncated.	As for application-generated response.

CICS as an HTTP client: Headers where CICS takes action on receiving an HTTP response

Table 2 shows the action that CICS takes for certain headers on a response received from a server.

Table 2. CICS as an HTTP client: CICS actions for headers on an HTTP response
Header received from server	Action taken by CICS
Connection	Carries out server's request for connection close after receiving response.
Content-Length	CICS requires the Content-Length header on all inbound HTTP/1.1 messages that have a message body. If a message body is present but the header is not provided, or its value is inaccurate, the socket receive for the faulty message or for a subsequent message can produce unpredictable results. For HTTP/1.0 messages that have a message body, the Content-Length header is optional.
Content-Type	Parses header to identify media type and character set for code page conversion.
Trailer	Makes trailing headers available to application through WEB READ HTTPHEADER command.
Transfer-Encoding	For "chunked", receives all chunks and assembles into single message to pass to application. For anything other than "chunked", sends 501 (Not Implemented) response to web client. The Transfer-Encoding header remains on the message, but it is for information only.
Warning	Writes warning text to the TS queue CWBW. If more than 128 characters are used, the warning text is truncated.

CICS as an HTTP server: Headers that CICS writes for an HTTP response

Table 3 shows the headers that CICS writes when responding to a request from a web client, the HTTP versions for which the headers are used, and the source of the information that CICS provides in the header.

Table 3. CICS as an HTTP server: CICS-written headers for an HTTP response
Header written by CICS	HTTP version	Source where response is handled by user application program	Source where response is provided by static document
Connection	1.0 and 1.1	CLOSESTATUS option on WEB SEND command. If no close is specified, and client is HTTP/1.0, Keep-Alive is sent. If close is specified, Connection: close is sent, or for HTTP/1.0 client Keep-Alive is omitted. CICS also sends Connection: close if connection throttling is in place for the port, specified by the limit in the MAXPERSIST attribute of the TCPIPSERVICE definition.	Keep-Alive is sent on static responses.
Content-Length (unless chunked transfer-coding is used)	1.0 and 1.1	Where response body is a buffer of data, the length is taken from the FROMLENGTH option on the WEB SEND command. Where response body is a CICS document, the length is calculated by CICS.	Calculated by CICS.
Content-Type	1.0 and 1.1	MEDIATYPE option on WEB SEND command, and character set for response body. (Header is only created when the MEDIATYPE option was specified.)	MEDIATYPE attribute of URIMAP resource definition for request, and character set for response body.
Date	1.0 and 1.1	Current date and time generated by CICS.	Current date and time generated by CICS.
Last-Modified (for static HFS files only)	1.0 and 1.1	Not provided for dynamic response. Application should produce this where feasible.	For HFS file: Modification date of file. For document template: Not provided.
Server	1.0 and 1.1	This depends on your HTTPSERVERHDR system initialization parameter. By default this is set to "IBM_CICS_Transaction_Server/version(z/OS)", where version is the version, release, and modification number of CICS: for example 5.5.0.	This depends on your HTTPSERVERHDR system initialization parameter. By default this is set to "IBM_CICS_Transaction_Server/version(z/OS)", where version is the version, release, and modification number of CICS: for example 5.5.0.
Strict-Transport-Security	1.0 and 1.1	The header value is added if support for HSTS is enabled.	The header value is added if support for HSTS is enabled.
Transfer-Encoding	1.1 only	CHUNKING option on WEB SEND command.	Not used.
WWW-Authenticate	1.0 and 1.1	AUTHENTICATE attribute of TCPIPSERVICE resource definition.	AUTHENTICATE attribute of TCPIPSERVICE resource definition.

CICS as an HTTP client: Headers that CICS writes for an HTTP request

Table 4 shows the headers that CICS writes when an application program sends out a client request to a server, the HTTP versions for which the headers are used, and the source of the information that CICS provides in the header.

Table 4. CICS as an HTTP client: CICS-written headers for an HTTP request
Header written by CICS	HTTP version	Source
Connection	1.0 and 1.1	CLOSESTATUS option on WEB SEND command. Value of header is selected according to HTTP version of server.
Content-Length (unless chunked transfer-coding is used)	1.0 and 1.1	FROMLENGTH option on WEB SEND command.
Content-Type	1.0 and 1.1	MEDIATYPE option on WEB SEND command, and character set for response body. (Header is only created when the MEDIATYPE option was specified.) Application programs can supply the Content-Type header instead of CICS, if the required header needs to contain spaces or more than 56 characters, and so cannot be specified on the MEDIATYPE option.
Date	1.0 and 1.1	Current date and time generated by CICS, in RFC 1123 format with GMT time.
Expect	1.1 only	ACTION(EXPECT) option on WEB SEND command. This option must only be used if your request has a message body. CICS does not send the header to HTTP/1.0 servers. If CICS does not yet know the server version, specifying the ACTION(EXPECT) option triggers an additional request with the OPTIONS method.
Host	1.0 and 1.1	HOST option on WEB OPEN command.
TE	1.1 only	Always added by CICS when sent to HTTP/1.1 servers, to state that chunked messages and trailers are accepted. (Chunked messages are not sent by HTTP/1.0 servers.) The application program may add further TE headers.
Transfer-Encoding	1.1 only	The first WEB SEND command in a sequence to send a chunked message (CHUNKING option on command indicates chunked transfer-coding). Transfer-Encoding header is written only on first chunk of message.
User-Agent	1.0 and 1.1	This depends on your HTTPUSRAGENTHDR system initialization parameter. By default this is set to "IBM_CICS_Transaction_Server/version(z/OS)", where version is the version, release, and modification number of CICS: for example 5.5.0.