- ACTION(cvda)
- specifies
how the message should be sent out. The CVDA values that apply for CICS as an HTTP
server are:
- IMMEDIATE
- sends the response immediately
to the Web client. If CHUNKING is specified, the IMMEDIATE option is assumed.
For message sends that do not use chunked transfer-coding, EVENTUAL is the
default, which sends the response at end of task.
- EVENTUAL
- sends
the response to the Web client at end of task. If CHUNKING is specified, the
EVENTUAL option is ignored. This option produces the same behaviour as CICS Web
support had in releases before CICS Transaction Server for z/OS, Version 3 Release 1,
and it is the default for CICS as an HTTP server.
- CHARACTERSET(data-value)
- specifies
a character set into which CICS translates the entity body of the item sent by
the command before sending. The name of the character set can consist of up
to 40 alphanumeric characters, including appropriate punctuation. CICS does not
support all the character sets named by IANA. The CICS Internet Guide lists
the IANA character sets that are supported by CICS for code page conversion.
When
the CHARACTERSET option is specified, SERVERCONV(SRVCONVERT) is assumed, so
code page conversion of the entity body takes place. As an alternative to
selecting the character set yourself, specifying either SERVERCONV(SRVCONVERT),
or HOSTCODEPAGE (if allowed), or both, and omitting CHARACTERSET, lets CICS
determine a suitable character set for the message body. The
description for the SERVERCONV option tells you what happens in this case.
If
you omit all of the code page conversion options, no code page conversion
takes place.
- CHUNKING(cvda)
- is
used for controlling the message send when the message is being sent in chunks
(known as chunked transfer-coding). The default when the option is not specified
is that chunked transfer-coding is not in use. Chunked transfer-coding is
only acceptable to HTTP/1.1 clients, and it cannot be used with HTTP/1.0 clients
or non-HTTP messages.
The content of a chunked message can be divided into
chunks in whatever way is most convenient for the application program. The
body of a chunked message cannot be formed directly from CICS documents,
so the DOCTOKEN option cannot be used.
Use a separate WEB SEND command
with CHUNKING(CHUNKYES) for each chunk of the message. Use the FROM option
to specify the chunk of data, and the FROMLENGTH option to specify the length
of the chunk. Other options for the message, such as the CLOSESTATUS option,
can be specified on the first WEB SEND command of the sequence (which sends
the first chunk), but do not specify them on subsequent commands (which send
the second and subsequent chunks).
When you have sent the last chunk of the data, specify a further WEB SEND
command with CHUNKING(CHUNKEND) and no FROM or FROMLENGTH option. CICS then sends
an empty chunk to the recipient to complete the chunked message.
If
one of the WEB SEND commands fails during the sequence, an error response
is returned, and subsequent sends will also fail. The application should handle
this situation appropriately. If all of the chunks are sent successfully but
the application does not issue the final WEB SEND command with CHUNKING(CHUNKEND),
the transaction is abended with abend code AWBP. An incomplete chunked message
should be ignored and discarded by the recipient.
The CICS
Internet Guide has a full description of the procedure for chunked
transfer-coding, which should be followed in order for your chunked message
to be acceptable to the recipient.
CVDA values are:- CHUNKNO
- Chunked
transfer-coding is not used for the message. This is the default if the CHUNKING
option is not specified.
- CHUNKYES
- Chunked
transfer-coding is in progress. The data specified by the FROM option represents
a chunk of the message.
- CHUNKEND
- Chunked
transfer-coding is complete. No data is specified for this send. CICS sends an
empty chunk to the recipient to complete the chunked message.
- CLNTCODEPAGE(data-value)
- This
option is supported for migration purposes only. CHARACTERSET replaces it.
The action taken by CICS is the same for both keywords. This means that code
page conversion does take place when CLNTCODEPAGE is specified, even if the
SERVERCONV option is not specified. Code page conversion does not take place
if all the code page conversion options are omitted.
- CLOSESTATUS(cvda)
- specifies
whether or not CICS closes
the connection after sending the message. The default is that the connection
is not closed. The CVDA values are:
- CLOSE
- CICS writes
a Connection header with the "close" connection option (Connection: close)
for this response, and closes the connection with the Web client after sending
the response. The header notifies the Web client of the closure. (For a Web
client at HTTP/1.0 level, CICS achieves the same effect by omitting the Connection:
Keep-Alive header.)
If chunked transfer-coding is in use, the CLOSESTATUS(CLOSE)
option can be specified on the first chunk of the message, to inform the Web
client that the connection is closed after the chunked message is complete.
- NOCLOSE
- means
that the Connection: close header is not used for this response, and the connection
is kept open. If the Web client is identified as HTTP/1.0 and has sent a Connection
header with the "Keep-Alive" connection option (Connection: Keep-Alive), CICS sends
the same header, to notify that a persistent connection will be maintained.
- DOCTOKEN(data-value)
- specifies
the 16-byte binary token of a document to be sent as the message body. The
document is created using the CICS Document interface (EXEC CICS DOCUMENT
CREATE, INSERT, and SET commands), as described in the CICS Application
Programming Guide. The FROM option provides an alternative way to create
a message body.
The body of a chunked message cannot be formed from CICS documents,
so the DOCTOKEN option cannot be used for chunked transfer-coding.
CICS
documents cannot be converted to the UTF-8 and UTF-16 character encodings.
- FROM(data-area)
- specifies
a buffer of data which holds the complete message body, or a chunk of the
message body. The message body is built by the application program. When you
specify the FROM option, use the FROMLENGTH option to specify the length of
the buffer of data. The DOCTOKEN option provides an alternative way to create
the message body, but that option cannot be used for the body of a chunked
message.
There is no set maximum limit for the size
of the data-area, but its size is limited in practice by storage considerations. The CICS
Internet Guide has more information about these.
- FROMLENGTH(data-value)
- specifies
the length, as a fullword binary value, of the buffer of data supplied on
the FROM option. It is important to state this value correctly, because an
incorrect data length can cause problems for the recipient of the message.
- HOSTCODEPAGE(data-value)
- specifies
the 8-character name of the CICS (host) code page that was used by the application
program for the entity body of the response. When the HOSTCODEPAGE option
is specified, SERVERCONV(SRVCONVERT) is assumed, so code page conversion of
the entity body takes place. Specifying either SERVERCONV(SRVCONVERT), or
CHARACTERSET, or both, and omitting HOSTCODEPAGE, lets CICS identify the host
code page.
If a CICS document is used to form the response body (DOCTOKEN
option), do not specify the HOSTCODEPAGE option, because CICS identifies
the host code page from the CICS document domain's record of the host code pages
for the document.
If a buffer of data is used to form the response body
(FROM option), you may need to specify HOSTCODEPAGE. The default if this option
is not present is the default code page for the local CICS region, as set in the LOCALCCSID system
initialization parameter. If you require code page conversion but your application
has used a different code page, use HOSTCODEPAGE to specify it.
If
you omit all of the code page conversion options, no code page conversion
takes place.
- LENGTH(data-value)
- This
option is supported for migration purposes only. STATUSLEN replaces it.
- MEDIATYPE(data-value)
- specifies
the data content of the message body, for example text/xml.
The media type is up to 56 alphanumeric characters, including appropriate
punctuation,
but not spaces
.. See the CICS
Internet Guide for more information about media types. CICS checks
that the format of the media type is correct, but does not check the validity
of the media type against the data content. CICS does not provide a default. In some circumstances, the media type that you specify
affects whether or not code page conversion is carried out; see the description
of the SERVERCONV option for more information.
- SERVERCONV(cvda)
- specifies
whether or not CICS translates
the entity body of the item sent by the command before sending, from the code
page used by the application, to a character set suitable for the recipient.
You can use the CHARACTERSET and HOSTCODEPAGE options on this command to specify
the character set and code page that are used. If you specify either of these
options, code page conversion (SRVCONVERT) is assumed. Alternatively, you
can omit either or both of these options, specify SERVERCONV(SRVCONVERT) and
let CICS determine a suitable character set and code page.
- SRVCONVERT
- CICS converts the entity body of the message.
When you specify SRVCONVERT without CHARACTERSET, CICS determines
a suitable character set as follows:
- If the Web client's request has a Content-Type header naming a character
set supported by CICS, that character set is used.
- If the Web client's request has no Content-Type header or the named character
set is unsupported, the ISO-8859-1 character set is used.
- For non-HTTP messages (sent using the USER protocol), the ISO-8859-1 character
set is used.
When you specify SRVCONVERT without HOSTCODEPAGE, CICS identifies the
host code page as follows:
- If the FROM option is used, CICS identifies the host code page as the
default code page for the local CICS region, as specified in the LOCALCCSID
system initialization parameter.
- If the DOCTOKEN option is used, CICS identifies the host code page from
the CICS document
domain's record of the host code pages for the document.
If you specify SRVCONVERT alone, note that
for code page conversion to take place, the MEDIATYPE option must specify
a type of data content that can be identified as text according to the IANA
definitions. For non-text media types, CICS does not convert the message body.
However, for compatibility with Web-aware applications coded in earlier releases,
if you specify either of the CHARACTERSET or HOSTCODEPAGE options or omit
the SERVERCONV option, the MEDIATYPE option does not influence code page conversion.
- NOSRVCONVERT
- CICS does not convert the entity body of
the HTTP request, and it is sent to the server in the code page used by the
application. If you specify NOSRVCONVERT, you cannot specify the CHARACTERSET
or HOSTCODEPAGE options.
Note: If you omit all of the code page conversion options
(SERVERCONV, CLNTCODEPAGE, CHARACTERSET, HOSTCODEPAGE), no code page conversion
takes place.
- STATUSCODE(data-value)
- specifies
a standard HTTP status code determined by the application program, which is
to be inserted on the status line of the HTTP response. The code is a halfword
binary value. Examples are 200 (normal response) or 404 (not found). If this
option is not specified, CICS supplies a default of 200.
The CICS
Internet Guide has information about the use of status codes for
CICS Web support. For status codes 204, 205, and 304, a message body
is not allowed, and CICS returns an error response to the command if you
attempt to include one. Other than that, CICS does not check that your use
of the status code is appropriate.
- STATUSLEN(data-value)
- specifies
the length, as a fullword binary value, of the string supplied on the STATUSTEXT
option.
- STATUSTEXT(data-area)
- specifies
a data-area containing human-readable text to describe the reason for the
status code. The text is known as a reason phrase. Examples are "OK" (accompanying
a 200 status code), or "Bad Request" (accompanying a 400 status code). The HTTP/1.1 specification (RFC 2616) defines a recommended
reason phrase for each status code, but you do not have to use these.