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.
Table 1 shows the action that CICS takes for certain headers on a request received from a web client.
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. zFS 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. zFS 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. |
Table 2 shows the action that CICS takes for certain headers on a response received from a server.
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. |
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.
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 zFS files only) | 1.0 and 1.1 | Not provided for dynamic response. Application should produce this where feasible. | For zFS file: Modification date of file. For document template: Not provided. |
Server | 1.0 and 1.1 | Preset to "IBM_CICS_ Transaction_Server/ 4.2.0(zOS)". | Preset to "IBM_CICS_ Transaction_Server/ 4.2.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. |
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.
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 | Preset to "IBM_CICS_ Transaction_Server/ 4.2.0(zOS)". |