Writing HTTP headers for a request

For client HTTP requests, CICS® automatically provides the HTTP headers that are required for basic messages, depending on the HTTP protocol version used for the message. You might need to add further HTTP headers to your request.

About this task

These HTTP headers are created automatically by CICS if the message requires them:

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
TE (written by CICS but further instances may be added)
Transfer-Encoding
User-Agent
WWW-Authenticate

Some of these headers are appropriate only for CICS as an HTTP server. The circumstances in which these headers are created are described in HTTP header reference for CICS web support. You cannot write your own versions of CICS-supplied request headers, except for the Content-Type and TE headers.

Typically, the headers that CICS provides for a request are written for a basic HTTP/1.1 message, to comply with the HTTP/1.1 specification. (CICS sends your request with HTTP/1.1 given as the HTTP version.) You might want to add further HTTP headers for purposes such as these:

Stating preferences to the server; for example, Accept-Encoding, Accept-Language
Making a conditional request; for example, If-Match, If-Modified-Since
Providing basic authentication information to a server or proxy; Authorization, Proxy-Authorization

Check the HTTP specification to which you are working for requirements relating to any additional HTTP headers that you decide to use for your message. Refer to The HTTP protocol.

Write additional HTTP headers for a message before you issue the WEB SEND command to send the message. However, if you are writing headers to be sent as trailing headers on a chunked message, the following procedure applies. Note these points:

Procedure

For all commands, specify the session token for this use of the connection, using the SESSTOKEN option.
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. 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 for the request, CICS adds the new header to the request in addition to the existing header. Repeat headers only where the HTTP specification states that the header may be repeated. CICS stores the headers ready to be added to the request when it is sent.
If you do not know the HTTP version of the server, and you want to use a header to request an action that might not be carried out correctly by a server below HTTP/1.1 level, use the WEB EXTRACT command to check the HTTP version of the server. You do not always have to check the HTTP version of the server before carrying out actions that depend on the version. Consult the HTTP specification to which you are working to see whether it is acceptable to attempt the action with a server of the wrong version. For example, some unsuitable HTTP headers might be ignored by the recipient. You might be able to attempt the request without checking, and handle any error response from the server.
If you want to produce a date and time stamp for use in one of your HTTP headers (for example, the If-Modified-Since header), you can 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 are using chunked transfer-coding to send an HTTP request, and you want to include trailing headers at the end of the chunked message, refer to Sending an HTTP request or response with chunked transfer-coding. You must 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.

dfhtl_outmaking_headers.html | Timestamp icon

Last updated: Thursday, 27 June 2019