HTTP header reference for CICS Web support

In CICS® Web support, when messages are sent out from CICS, some HTTP headers are provided automatically by CICS, and some can be added by the user. 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 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, you should 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, such as 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 will 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 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.
    • Start of changeFor 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.End of change
    • 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:
    • 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 which are allowed. HTTP status code reference for CICS Web support has more information about the use of status codes.
The Upgrade header
  • Note as a 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-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. 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. (CICS checks the length that you specify. If it is wrong, CICS sends the response but omits the Connection: Keep-Alive header.) 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 Preset to "IBM_CICS_ Transaction_Server/ 3.1.0 (zOS)". Preset to "IBM_CICS_ Transaction_Server/ 3.1.0 (zOS)".
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. (CICS checks the length that you specify. If it is wrong, CICS sends the response but omits the Connection: Keep-Alive header.)
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.) Start of change 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.End of change
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.
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 Preset to "IBM_CICS_ Transaction_Server/ 3.1.0 (zOS)".