Examining the HTTP headers for a message

Each HTTP header for a request or response message consists of a header name and header value. CICS® stores this information for the application to access if required. An application can receive the value of a specified header, or browse through the names and values of all the headers for a request or response. You can also convert an architected date and time stamp string taken from a header into the ABSTIME format.

About this task

Your application might need to examine information in the headers to process a request or response and to construct subsequent messages.
  • The TE header instructs the application whether trailing headers are permitted in a chunked response message.
  • Conditional headers can provide instructions to the application, such as to reply only if the response document has changed.
Unless you know the exact format of the HTTP request or response, your application must not rely on the presence of any particular header, because web clients and servers can be inconsistent in the headers that they send.

Some HTTP headers contain date and time stamps. CICS provides the CONVERTTIME command to convert common formats for architected date and time stamp strings into the ABSTIME format, for use by the application.

The standard HTTP headers are described in the HTTP/1.1 specification (RFC 2616) and the HTTP/1.0 specification (RFC 1945). HTTP header reference for CICS web support explains the general use of HTTP headers in CICS web support, and the actions that CICS web support takes for specific headers received on messages. CICS ignores some HTTP headers, and the user application must take appropriate action in response. Check the HTTP specification for detailed guidance and requirements about the meaning and correct use of each HTTP header.

If the message includes any trailing headers, you can read these using the EXEC CICS WEB commands in the same way as for standard headers. The Trailer header on the message specifies the names of all the HTTP headers that were sent as trailing headers.

To examine and work with HTTP headers:

Procedure

  • To examine the contents of a particular HTTP header, use the WEB READ HTTPHEADER command.
    Your application program must provide a buffer that receives the contents of the header. CICS returns a NOTFND condition if the header is not present in the request.
  • To browse all the headers in a request or response:
    1. Use the WEB STARTBROWSE HTTPHEADER command to begin browsing the header lines.
    2. Use the WEB READNEXT HTTPHEADER command to retrieve the header name and header value for each line.
      Your application program must provide two buffers: one receives the name of the header, and the other receives its contents. CICS returns an ENDFILE condition when all headers have been read.
    3. Use the WEB ENDBROWSE HTTPHEADER command to end the browse when your program has retrieved all the header information of interest.
  • To convert an architected date and time stamp string that is provided in a HTTP header, receive it into a buffer using the WEB READ HTTPHEADER command, and then process it using the CONVERTTIME command.
    You do not have to identify the format of the date and time stamp; the CONVERTTIME command recognizes and converts three different date and time stamp formats that are commonly used on the Internet. These are RFC 1123 (the web standard), RFC 850 (an older format), and ASCtime (output from C function).
    The application can convert the ABSTIME to other formats, using the FORMATTIME command.