WEB WRITE HTTPHEADER

Build HTTP header information.

Read syntax diagramSkip visual syntax diagram
WEB WRITE HTTPHEADER

>>-WEB--WRITE--HTTPHEADER(data-area)---------------------------->

>--+------------------------+--+-----------------------+-------->
   '-NAMELENGTH(data-value)-'  '-SESSTOKEN(data-value)-'   

>--VALUE(data-area)--+-------------------------+---------------><
                     '-VALUELENGTH(data-value)-'   

Conditions: INVREQ, LENGERR, NOTOPEN

This command is threadsafe.

 

Start of change

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:
  • Connection
  • Content-Length
  • Start of changeContent-Type (written by CICS, but can be supplied by a client application if a complex header is required)End of change
  • Date
  • Expect
  • Host
  • Server
  • TE (written by CICS, but the application can add further instances)
  • Transfer-Encoding
  • User-Agent
  • WWW-Authenticate
"HTTP header reference for CICS Web support" in the CICS Internet Guide 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.
  • Start of changeFor 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.End of change
  • 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.

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 any of the HTTP headers you use might be unsuitable for a Web client or remote server below HTTP/1.1 level, check the version information that they supply before writing those headers. For CICS as an HTTP server, the WEB EXTRACT command with the HTTPVERSION option gives this information about the Web client. For CICS as an HTTP client, the options HTTPVNUM and HTTPRNUM that are returned on the WEB OPEN command for the session give this information about the server.

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:
End of change

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.
Start of changeSESSTOKEN(data-value)End of change
Start of change 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" in the CICS Internet Guide explains the use of the session token.End of change
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

INVREQ
RESP2 values are:
1
The command is being issued in a non-CICS Web support application.
Start of change6End of change
Start of changeClient did not send TE: trailers on request, so trailing headers cannot be used.End of change
Start of change19End of change
Start of changeHeader not allowed. Some request headers may only be generated by CICS.End of change
Start of change44End of change
Start of changeHeader not allowed as a trailing header (trailer).End of change
Start of change69End of change
Start of changeChunked transfer-coding not supported.End of change
Start of change70End of change
Start of changeTrailer header has not been created, so trailing headers cannot be written.End of change
Start of change71End of change
Start of changeChunked transfer-coding error.End of change
Start of change74End of change
Start of changePrevious send failed.End of change
Start of change78End of change
Start of changeToo late to write trailing headers for this message.End of change
LENGERR
RESP2 values are:
35
The length in NAMELENGTH is not greater than zero.
55
The length in VALUELENGTH is not greater than zero.
Start of changeNOTOPENEnd of change
Start of changeRESP2 values are:
27
Invalid session token.
End of change