WEB WRITE HTTPHEADER

Build HTTP header information.

WEB WRITE HTTPHEADER

Conditions: INVREQ, LENGERR, NOTOPEN

This command is threadsafe.

Description

WEB WRITE HTTPHEADER enables an application to add HTTP header information to a message. When CICS® is an HTTP server, the message is a response to a Web client. When CICS is an HTTP client, the message is a request to a server, and the SESSTOKEN option is specified.

Some HTTP headers are created automatically by CICS if the message requires them, and the application does not need to write these headers. These are:

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. See The HTTPSERVERHDR system initialization parameter.)
TE (written by CICS but further instances may be added)
Transfer-Encoding
User-Agent (automatic creation depends on system initialization parameter HTTPUSRAGENTHDR. See The HTTPUSRAGENTHDR system initialization parameter.)
WWW-Authenticate

HTTP header reference for CICS Web support describes the circumstances in which these headers are created. 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.
If the WEB WRITE HTTPHEADER is used to write a server header then a server header will be provided, even if the CICS supplied server header is suppressed by the HTTPSERVERHDR=NO parameter.

The WEB WRITE HTTPHEADER 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 or response, CICS adds the new header to the request or response in addition to the existing header.

The name and value of the headers you write, and the circumstances in which you choose to write them, should conform to the requirements of the HTTP specification to which you are working.

If you want to use a header to request an action that might not be carried out correctly by a server or client below HTTP/1.1 level, and you need to confirm whether the action will succeed, use the WEB EXTRACT command with the HTTPVERSION option to check the HTTP version of the server.

For CICS as an HTTP client, if you are writing a Trailer header (for use with a chunked message) on your first request to the server, and you did not specify the options HTTPVNUM and HTTPRNUM on the WEB OPEN command for the session, CICS makes a request with the OPTIONS method to check the HTTP version of the server. This additional request is only made for the Trailer header.

The WEB WRITE HTTPHEADER command cannot be used if the connection with the server or Web client has been closed by either party sending a Connection: close header on a request or response.

For guidance on the correct use of this command:

When writing headers for an HTTP response sent by CICS as an HTTP server, seeWriting Web-aware application programs for CICS as an HTTP server .
When writing headers for an HTTP request sent by CICS as an HTTP client, see HTTP client requests from a CICS application .
When using chunked transfer-coding to send an HTTP request or response, see Using chunked transfer-coding to send an HTTP request or response . That topic explains the correct procedure for writing trailing headers for a chunked message.

Options

HTTPHEADER(data-area): Specifies the name of the HTTP header to be added to the request or response. The name, which is a string of text, should conform to the standards in the HTTP specification to which you are working.
NAMELENGTH(data-value): Specifies the length, as a fullword binary value, of the HTTP header name.
SESSTOKEN(data-value): For CICS as an HTTP client, this option is required. It specifies the session token, an 8-byte binary value that uniquely identifies a connection between CICS and a server. This value is returned by a WEB OPEN command for CICS as an HTTP client. Session tokens explains the use of the session token.
VALUE(data-area): Specifies the value of the named HTTP header. The value, which is a string of text, should conform to the standards in the HTTP specification to which you are working.
VALUELENGTH(data-value): Specifies the length, as a fullword binary value, of the HTTP header value.

Conditions

16 INVREQ

RESP2 values are:

1: The command is being issued in a non-CICS Web support application.
6: Client did not send TE: trailers on request, so trailing headers cannot be used.
19: Header not allowed. Some request headers may only be generated by CICS.
44: Header not allowed as a trailing header (trailer).
69: Chunked transfer-coding not supported.
70: Trailer header has not been created, so trailing headers cannot be written.
71: Chunked transfer-coding error.
74: Previous send failed.
78: Too late to write trailing headers for this message.

22 LENGERR

RESP2 values are:

35: The length in NAMELENGTH is not greater than zero.
55: The length in VALUELENGTH is not greater than zero or greater than 32000.

19 NOTOPEN

RESP2 values are:

27: Invalid session token.