Writing HTTP headers for a response

For dynamic responses created by application programs, CICS® automatically provides the HTTP headers that are required for basic messages, depending on the HTTP protocol version used for the message. Your application does not need to write these headers. However, you might want to add further HTTP headers to your response.

About this task

Here is the full list of headers created by CICS :
  • ARM correlator
  • Connection
  • Content-Type (written by CICS, but can be supplied by a client application if a complex header is required)
  • Content-Length
  • Date
  • Expect
  • Host
  • Server (automatic creation depends on system initialization parameter HTTPSERVERHDR
  • TE (written by CICS but further instances may be added)
  • Transfer-Encoding
  • User-Agent (automatic creation depends on system initialization parameter HTTPUSRAGENTHDR
  • WWW-Authenticate
Note that some of these headers are appropriate, and created, only when CICS is an HTTP client. The circumstances in which these headers are created are described in HTTP header reference for CICS web support . If you do write these headers on a response, CICS does not overwrite them, but uses the versions provided by your application.
The headers that CICS provides when a response is sent are the ones that are typically written to make a basic message comply with the appropriate HTTP protocol specification. You might want to add further HTTP headers to the response for some purposes:
  • Control of caching and document expiry; for example, Cache-Control, Expires, Last-Modified.
  • Content negotiation; for example, Accept-Ranges, Vary.
  • Information for the web client; for example, Title, Warning, further Content headers.
If your application program is performing complex actions, or if you select certain status codes for your response, the HTTP specification to which you are working is likely to require the use of particular HTTP headers for your message. When you add any HTTP headers to a response, check the HTTP specification to which you are working for any important requirements that apply to those headers. See The HTTP protocol for more information about the HTTP specifications.
Note: Your HTTP header must be supplied in code page 037 if the header contains characters other than the standard alphabetic and numeric characters.

Write additional HTTP headers for a message before you issue the WEB SEND command to send the message. The exception to this rule is when you write headers to be sent as trailing headers on a chunked message, in which case the subsequent procedure applies. To write HTTP headers for a response:

Procedure

  • Use the WEB WRITE HTTPHEADER command for each header that you want to add to the message.
    Make sure that you specify the name and value for each header in the format described by the HTTP specification to which you are working. CICS does not validate the content of HTTP headers, because you might want to use new or user-defined headers.
    The command adds a single header, and you can repeat the command to add further headers. If you write a header that you have already written, CICS adds the new header to the request or response in addition to the existing header. Rewrite a header only when the HTTP specification states that the header can be repeated.
    CICS stores the headers ready to be added to the request when it is sent.
  • If any of the HTTP headers that you use might be unsuitable for web clients lower than HTTP/1.1 level, before writing those headers, check the HTTP version information that the web client has supplied to you.
    Use the WEB EXTRACT command to obtain this information.
    To allow you to use user-defined (nonstandard) headers, CICS does not remove unsuitable user-written headers. Some HTTP headers are not understood by servers lower than HTTP/1.1, and might lead to errors in processing your request.

    CICS does not make any special provision for a server or web client that is lower than HTTP/1.0 level. CICS behaves as though they are at HTTP/1.0 level and returns HTTP/1.0 as the HTTP version.

  • If you want to produce a date and time stamp for use in one of your HTTP headers, for example, the Last-Modified header, use the FORMATTIME command.
    The STRINGFORMAT option on the command converts the current date and time, in ABSTIME format, or a date and time produced by the application program, into suitable date and time stamp formats for use on the Web. Other date and time stamp formats might not be accepted by some web clients or servers with which CICS is communicating.
  • If you want to produce a strong entity tag for use in the ETag HTTP header, you can use the SHA-1 digest produced by the BIF DIGEST command.
    The presence of a strong entity tag enables a client to make conditional requests for a resource using the entity tag in If-Match, If-None-Match, or If-Range headers, which is a more precise method of checking the status of a resource than the Last-Modified date and time string. If you want to allow conditional requests, your application program must provide support for them; CICS does not provide its own support for If-Match, If-None-Match, or If-Range functions on HTTP GET requests.
  • If you are using chunked transfer-coding to send an HTTP request or response, and you want to include trailing headers at the end of the chunked message, follow the special instructions in Sending an HTTP request or response with chunked transfer-coding.
    You write a Trailer header before sending the first chunk of the message. All the HTTP headers written after the WEB SEND command for the first chunk are treated as trailing headers.
  • Make sure that your application program carries out any actions that are implied by your user-written headers.
    For example, if you have written content-negotiation headers, your application program must provide different versions of the resource.