Use the WEB SEND command to make CICS® assemble the HTTP headers, entity
body, status code and reason phrase for an HTTP response, carry out code page
conversion, and transmit the response to the Web client.
If wanted, the response can be sent in chunks (chunked transfer-coding).
You cannot send pipelined responses back to a Web client (you must send a
single response to each request sent by the Web client).
The CICS Application
Programming Reference has full reference information and descriptions
of the options available on the WEB SEND command. When you issue the command:
- Specify the STATUSCODE option to select an appropriate status code
for the response, depending on the situation, and the STATUSTEXT and STATUSLEN
options to provide the reason phrase. CICS does not validate your choice of status
code, and it is the user application's responsibility to ensure that the value
is valid and conforms to the rules for HTTP status codes. Depending
on the status code that you select, you might need to complete some or all
of the following steps before issuing the WEB SEND command:
- Check the HTTP version of the Web client's request, to ensure
that the status code can be understood. The HTTP/1.1 specification
includes more status codes than the HTTP/1.0 specification.
- If the HTTP specification states that the status code should
be accompanied by certain HTTP headers, use the WRITE HTTPHEADER command to
create those headers.
- If the HTTP specification states that the status code should
be accompanied by a message body giving special information, create an appropriate
entity body. This is normally the case when the status code indicates
an error or requests further action from the client. Message bodies
are not allowed with status codes 204, 205, and 304. If you have selected
a status code that does not allow a message body, and attempt to use a message
body, CICS gives
an error response to the WEB SEND command.
- Identify the source of any entity body for the response by specifying
either the DOCTOKEN option, for a CICS document that you have created, or
the FROM option, for a body of data that you have assembled. If you are using
the FROM option, specify the FROMLENGTH option to give the length of the entity
body, or of the chunk if chunked transfer-coding is in use. For
chunked transfer-coding, the DOCTOKEN option cannot be used.
- Specify the media type for the body of the response, using the
MEDIATYPE option. CICS does not check the validity of the
specification against the data content. There is no default. If
you do not specify this, CICS does not build a Content-Type header for the response.
- If you want the message to be sent immediately, rather than at
the end of the task (which is the default), specify IMMEDIATE for the ACTION
option. If you are using chunked transfer-coding, IMMEDIATE is
the default, so there is no need to make this choice.
Note: Only
one response can be sent during a task. This can be a standard response using
one WEB SEND command, or a chunked response using a sequence of WEB SEND commands.
- If you want to close the connection after sending the response,
specify CLOSE for the CONNECTION option. CICS writes a Connection: close header
on the response, which notifies the Web client that the connection is closed
and no more requests should be sent. (For a Web client at HTTP/1.0 level, CICS achieves
the same effect by omitting the Connection: Keep-Alive header.)
- Specify the appropriate settings for code page conversion of the
message body.
- The SERVERCONV option provides overall control of code page
conversion. Use it to specify whether or not code page conversion takes place. For CICS as
an HTTP server, for compatibility with Web-aware applications coded in earlier
releases, code page conversion is assumed if SERVERCONV is not specified but
another code page conversion option is specified. If you want to prevent code
page conversion, either specify SERVERCONV(NOSRVCONVERT), or omit all the
code page conversion options.
- If you want code page conversion, but the character set selected
by CICS is
not suitable, use the CHARACTERSET option to specify an alternative. By default, CICS uses the character set specified in the Content-Type
header of the Web client's original request. If that character set was unsupported
or not stated, CICS uses
the ISO-8859-1 character set instead.
A Web client might specify
alternative acceptable character sets in an Accept-Charset header. If you
want to specify one of these, it is up to your application to analyze the
header (which might include quality values to indicate the Web client's preference),
and select an appropriate supported character set.
CICS does not support all the character
sets named by IANA. HTML coded character sets lists the IANA
character sets that are supported by CICS for code page conversion.
- If you want code page conversion, and are using the FROM option
to specify the message body, you need to use the HOSTCODEPAGE option to identify
your application's code page, if this is not the default code page
for the local CICS region
(as specified in the LOCALCCSID system initialization parameter). If
you are using a CICS document
(DOCTOKEN option), CICS identifies the host code page from the CICS document
domain's record of the host code pages for the document.
Code page conversion does not take place for messages that specify a
non-text media type (unless you do not specify SERVERCONV, in which case for
compatibility purposes, the media type is not taken into account). The HTTP headers and status line are always converted into the ISO-8859-1
character set by CICS.
- If you are using chunked transfer-coding (or chunking), in addition
to the basic instructions in this topic, you need to follow the special instructions
in Using chunked transfer-coding to send an HTTP request or response. You need to ensure that the procedure described in that topic is followed
correctly, so that the chunked message is acceptable to the recipient. Chunked
messages are sent using several instances of the WEB SEND command, with particular
options.