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.
  • 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:
  • 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.