- ACTION(cvda)
- This
option is used to specify how the message should be sent out. The CVDA value
that applies for CICS as an HTTP client is:
- EXPECT
- makes CICS send
an Expect header along with the request line and headers for the request,
and await a 100-Continue response before sending the message body to the server.
If a response other than 100-Continue is received, CICS informs the application program and
cancels the send. If no response is received after a period of waiting, CICS sends
the message body anyway.
This option must only be used if your request has
a message body.
- CHARACTERSET(data-value)
- specifies
the character set into which CICS translates the entity body of the request 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.
For conversion of the entity body to take place,
the CLIENTCONV option must be specified as (or allowed to default to) CLICONVERT.
Specifying NOCLICONVERT suppresses conversion of the entity body. If conversion
is requested, ISO-8859-1 is used as the default if the CHARACTERSET attribute
is not specified.
- 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.
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 end the chunked message.
If
your application program is informed of an error at any point in the chunking
process, use the WEB CLOSE command to stop the process and close the connection.
The recipient of the chunked message will not receive the final empty chunk,
and so should ignore and discard the data that you have sent so far.
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.
Note: - The method (METHOD option) must be compatible with chunked transfer-coding.
- When you have begun sending the parts of a chunked message, the application
program cannot send any different messages or receive any items until the
final empty chunk is sent and the chunked message is complete.
- CLOSESTATUS(cvda)
- specifies
whether or not a Connection header with the "close" connection option (Connection:
close) should be included on the message. The default is that the header is
not included. The CVDA values are:
- CLOSE
- makes CICS write
a Connection: close header for this request. The header notifies the server
that the connection should be closed after the server has sent its response
to the request. (For a server 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 server that the connection should be closed after the chunked
message is complete and a response has been sent.
If chunked transfer-coding
is not in use, and the CLOSESTATUS(CLOSE) option is specified on a WEB SEND
command, no further messages can be sent to the server until a new connection
is made.
- NOCLOSE
- means
that the Connection: close header is not used for this request. If the server
is identified as HTTP/1.0, CICS sends a Connection header with the "Keep-Alive"
connection option (Connection: Keep-Alive), to notify that a persistent connection
is desired.
- CLIENTCONV(cvda)
- specifies
whether or not CICS translates
the entity body of the HTTP request before sending, from the code page used
by the application, to a character set suitable for the recipient. If this
option is omitted, the default is that any entity body is converted,
unless a non-text media type is specified. CVDA values are:
- CLICONVERT
- CICS converts the entity body of the HTTP
request from the code page used by the application, into the character set
that you identify for the server. You can use the CHARACTERSET option on this
command to specify the character set that is used. If conversion is requested
but you do not specify a character set, the default is that CICS converts
the entity body to the ISO-8859-1 character set. (The code page used by the
application was identified on the WEB OPEN command for the connection.)
Note: For non-text media types, CICS does not convert the message
body, even if CLICONVERT is specified.
- NOCLICONVERT
- 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, as identified on the WEB OPEN command for the connection.
- DOCTOKEN(data-value)
- specifies
the 16-byte binary token of a document to be sent as the message body. The
document must be created using the CICS Document interface (EXEC CICS DOCUMENT
CREATE, INSERT, and SET commands), as described in the CICS Application
Programming Guide. You do not need to retrieve
the document before sending it. 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 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 (the message body). It is important to state this value correctly,
because an incorrect data length can cause problems for the recipient of the
message.
- MEDIATYPE(data-value)
- specifies
the data content of any message body provided, 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 uses this information to produce the
Content-Type header for the message.
For requests which require a body, you must specify the MEDIATYPE
option. There is no default. However, if the required Content-Type header
needs to contain spaces or more than 56 characters, the application can provide
it using the WEB WRITE HTTPHEADER command. In this case, do not specify the
MEDIATYPE option.
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.
- METHOD(cvda)
- specifies
the HTTP method for the request.
The GET, HEAD, POST, PUT, TRACE, OPTIONS,
and DELETE methods are supported by this command. However, some HTTP servers,
particularly HTTP/1.0 servers, might not implement all of these methods.
The CICS
Internet Guide has more information about the correct use of methods,
including the HTTP versions that apply to each.
CICS bars the sending
of a message body for methods where it is inappropriate, and requires it for
methods where it is appropriate. Chunked transfer-coding is not relevant for
methods that do not have a request body.
The CVDA values are: - GET
- Obtain
a resource from the server. A request body is not allowed.
- HEAD
- Obtain
the HTTP headers, but not the response body, for a resource. A request body
is not allowed.
- POST
- Send
data to a server. A request body is required.
- PUT
- Create
or modify a resource on the server. A request body is required.
- TRACE
- Trace
the route of your request to the server. A request body is not allowed.
- OPTIONS
- Obtain
information about the server. A request body is allowed, but there is no defined
purpose for the body. If you do use a request body, then you must specify
a media type.
- DELETE
- Delete
a resource on the server. A request body is not allowed.
- PATH(data-area)
- specifies
the path information for the specific resource within the server that the
application needs to access.
If the URIMAP option was used to specify an
existing URIMAP definition on the WEB OPEN command for this connection, the
path specified in that URIMAP definition is the default path for the WEB SEND
command. In these circumstances, if you do not specify path information on
the WEB SEND command, the path from the URIMAP definition is used. If you
specify a different path from that given in the URIMAP definition, this overrides
the path from the URIMAP definition.
If the URIMAP option was not used
on the WEB OPEN command, there is no default path, and you must provide path
information. Path information can be extracted from a known URL using the
WEB PARSE URL command.
As an alternative to using the PATH option to
provide the path information, you can use the URIMAP option on the WEB SEND
command to specify a URIMAP definition from which the path information is
taken directly.
- PATHLENGTH(data-value)
- specifies
the length of the path, as a fullword binary value. If you are providing path
information using the PATH option, you need to specify the PATHLENGTH option.
Path length information is returned if you use the WEB PARSE URL command to
parse a URL.
- QUERYSTRING(data-area)
- specifies
a query string that is to be supplied to the server as part of the request.
You do not need to include a question mark (?) at the beginning of the query
string; if you do not include it, CICS supplies it for you automatically
when constructing the request. If you include escaped characters in the query
string, CICS passes
them to the server in their escaped format.
- QUERYSTRLEN(data-value)
- specifies
the length of the query string supplied on the QUERYSTRING option, as a fullword
binary value.
- SESSTOKEN(data-value)
- 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.
- URIMAP(data-value)
- specifies
the name (up to eight characters, in mixed case) of a URIMAP definition that
provides the path information for the specific resource within the server
that the application needs to access. The URIMAP definition must be for CICS as
an HTTP client (with USAGE(CLIENT) specified). Its HOST attribute must be
the same as the HOST attribute of the URIMAP definition that was specified
on the WEB OPEN command for this connection, or the same as the host name
specified in the HOST option on the WEB OPEN command for this connection.
A URIMAP definition specified on the WEB SEND command applies only to this
request.
If the URIMAP option is specified, do not specify the PATH or PATHLENGTH
options.