Build HTTP header information.

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.

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:
"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.
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.
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:

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" in the CICS Internet Guide 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
- 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.
- LENGERR
- RESP2
values are:
- 35
- The length in NAMELENGTH is not greater than zero.
- 55
- The length in VALUELENGTH is not greater than zero.
NOTOPEN
RESP2
values are: - 27
- Invalid session token.
