WEB SEND (Client)
Send an HTTP request by CICS® as an HTTP client, using CICS Web support.
Conditions: CHANNELERR, CONTAINERERR, INVREQ, IOERR, LENGERR, NOTAUTH, NOTFND, NOTOPEN, TIMEDOUT, TOKENERR
This command is threadsafe.
Description
WEB SEND for CICS as an HTTP client is used to make an HTTP request to a server. A session token must be included on this command. For guidance on the correct use of the WEB SEND command for CICS as an HTTP client, see HTTP client requests from a CICS application .
For CICS as an HTTP client, the WEB SEND command cannot be used after the connection to the server has been closed. You might encounter this situation if either the application program or the server sends a Connection: close header on a message. If you need to test whether the server has requested termination of the connection, use the WEB READ HTTPHEADER command to look for the Connection: close header in the last message from the server.
For CICS as an HTTP client, the CONVERSE command can be used as an alternative to issuing a WEB SEND command followed by a WEB RECEIVE command. However, note that the WEB CONVERSE command does not support chunked transfer-coding, because it requires a sequence of send actions, and the WEB CONVERSE command provides a single send action.
The request can time out when sending a message to the server. In this case, the deadlock time out interval specified in the DTIMOUT attribute of the TRANSACTION definition applies, and CICS returns a TIMEDOUT response to the application.
Options
- ACTION(cvda)
- Specifies
how the message will be sent out. This CVDA value applies for CICS as an HTTP client:
- EXPECT
- Makes CICS send an Expect header 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.
The Expect header is not supported by servers below HTTP/1.1. If CICS does not yet know the HTTP version of the server, CICS makes an additional request before sending your request, to determine the HTTP version of the server. If the Expect header is not suitable, CICS sends your request without it.
This option must be used only if your request has a message body.
- AUTHENTICATE(cvda)
- Specifies
user authentication details, to control access to restricted data.
The CVDA values that apply for CICS as
an HTTP client are as follows:
- NONE
- Specifies that there are no restrictions on accessing this data, therefore no credentials are required. This is the default value for AUTHENTICATE.
- BASICAUTH
- Specifies that HTTP Basic Authentication credentials are required for this session. These details can be supplied within the command or by using the XWBAUTH global user exit.
- CHANNEL(data-value)
- Specifies the name of the channel to which the
container belongs. The name of the channel can consist of up to 16
alphanumeric characters, including appropriate punctuation. Leading
and embedded blanks are not permitted. If the name is less than 16
characters, it is padded with trailing blanks. You can specify the
channel name DFHTRANSACTION to use the transaction
channel.
If the CONTAINER option is specified, CHANNEL is optional.
If the CHANNEL option is not specified, CICS assumes the current channel.
- 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. HTML coded character sets 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 to suit 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 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 CHUNKEND, but not the FROM and FROMLENGTH options. 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 ignores and discards the data that you have sent so far.
Using chunked transfer-coding to send an HTTP request or response has a full description of the procedure for chunked transfer-coding, which must be followed for your chunked message to be acceptable to the recipient.
CVDA values are as follows:- CHUNKNO
- Chunked transfer-coding is not used for the message. CHUNKNO 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.
Notes:- 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.
If you are using the CONTAINER option, do not specify the CHUNKING option. A chunked response cannot be sent from a container.
- CLOSESTATUS(cvda)
- Specifies
whether a Connection header with the "close" connection option (Connection:
close) will be included on the message. The default is that the header
is not included. The CVDA values are as follows:
- CLOSE
- Makes CICS write a Connection: close header for this
request. The header notifies the server that the connection will 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.) Do
not specify this option if you have implemented connection pooling
in the URIMAP resource for this connection, because a closed connection
cannot be pooled for reuse. Only specify this option if this is your
final request to the server and you are not using connection pooling.
When you specify the CLOSE option on a WEB SEND command, no further messages can be sent to the server until a new connection is made. The exception is where chunked transfer-coding is in use, when you can specify the CLOSE option on the first chunk of the message, to inform the server that the connection will be closed after the chunked message is complete and a response has been sent.
- 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 required.
- CLIENTCONV(cvda)
- Specifies
whether 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 nontext media type is specified. CVDA values are
as follows:
- 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.) For non-text media types, CICS only converts the message body under the following circumstances:
- The message body is sent from a buffer, using the FROM option, and either the CLICONVERT or CHARACTERSET options, or both, are specified.
- The message body is sent from a document, using the DOCTOKEN option.
- The message body is sent from a container and the CHARACTERSET option is specified.
BIT containers contain nontext media, and therefore do not support code page conversion. As a result, if you code either the CLICONVERT or CHARACTERSET options with a BIT container, an INVREQ RESP2 error is produced.
- 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.
- CONTAINER(data-value)
- Specifies the name of the container where the HTTP body is held, before it is sent to the server. The name of the container can consist of up to 16 alphanumeric characters, including appropriate punctuation. Leading and embedded blanks are not permitted. If the name is shorter than 16 characters, it is padded with trailing blanks.
- DOCSTATUS(cvda)
- Indicates
whether the document will be deleted or not deleted during processing
of the WEB SEND command. The CVDA values are as follows:
- DOCDELETE
- CICS deletes the document after the document contents are saved for sending. Storage allocated for the document is released immediately. If you make subsequent requests for the document, the requests generate a TOKENERR response.
- NODOCDELETE
- CICS does not delete the document during processing of the WEB SEND command. This value is the default for DOCSTATUS.
- DOCTOKEN(data-value)
- Specifies
the 16-byte binary token of a document to be sent as the message body.
You create the document using the CICS Document
interface (EXEC CICS DOCUMENT
CREATE, INSERT, and SET commands). You do not have 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.
- 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 and CONTAINER options provide an alternative
way to create the message body, but the DOCTOKEN option cannot be
used for the body of a chunked message.
The size of the data-area has no set maximum limit, but its size is limited in practice by storage considerations. Producing an entity body for an HTTP message has more information about storage considerations.
- FROMLENGTH(data-value)
- Specifies the length, as a fullword binary value, of the buffer of data supplied on the FROM option (the message body). You must 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
. You must specify a 56-byte area for MEDIATYPE. The media type is up to 56 alphanumeric characters, including appropriate punctuation, but not spaces. For more information on media types, see IANA media types and character sets . 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 that require a body, you must specify the MEDIATYPE option. There is no default. However, if the required Content-Type header must 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.
The supplied media type is used to determine whether code page conversion is required under the following circumstances:- If you are sending a message from a buffer, using the FROM option, and the CLIENTCONV and CHARACTERSET options are not specified.
- If you are sending a message from a document, using the DOCTOKEN option, and the CLIENTCONV and CHARACTERSET options are not specified.
- If you are sending a message from a named container, using the CONTAINER option, and either CLICONVERT is specified, or the CLIENTCONV and CHARACTERSET options are not specified.
- 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.
HTTP method reference for CICS Web support has more information about the correct use of methods, including the HTTP versions that apply to each.
CICS prevents the sending of a message body for methods for which 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.
CVDA values are as follows:- 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 the body has no defined purpose. 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.
- PASSWORD(data-value)
- Specifies
the password associated with the user ID or logon name that is allowed
access to this data. The PASSWORD option is required only if the USERNAME
option is used.
If you specify USERNAME and PASSWORD in the WEB SEND command and you also specify AUTHENTICATE in the URIMAP resource, the WEB SEND values are used.
If the specified password is over 8 characters long, it is treated as a password phrase when sent to z/OS® systems. - PASSWORDLEN(data-value)
- Specifies the buffer length supplied for the PASSWORD option as a fullword binary variable.
- PATH(data-area)
- Specifies
the path information for the specific resource in 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, that path 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. You can extract path information 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 must 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 have 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 explains the use of the session token.
- URIMAP(data-value)
- Specifies
the name, up to 8 characters, in mixed case, of a URIMAP definition
that provides the path information for the specific resource in the
server that the application will 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.
- USERNAME(data-value)
- Specifies
the user ID or logon name that is allowed access to this data. If
the USERNAME is specified, you must also use the PASSWORD option.
If you specify USERNAME and PASSWORD in the WEB SEND command and you also specify AUTHENTICATE in the URIMAP resource, the WEB SEND values are used.
- USERNAMELEN(data-value)
- Specifies the buffer length supplied for the USERNAME option as a fullword binary variable.
Conditions
- 122 CHANNELERR
- RESP2
values are:
- 2
- The channel specified by the CHANNEL option was not found.
- 110 CONTAINERERR
- RESP2
values are:
- 2
- The container specified by the CONTAINER option was not found.
- 16 INVREQ
- RESP2
values are:
- 11
- Action code invalid.
- 12
- URIMAP and PATH are both specified. Only one is allowed. Or, the URIMAP option is not allowed for second or subsequent chunks.
- 13
- Close status invalid.
- 15
- Code page conversion failure.
- 17
- Expect-100 request was rejected by the server.
- 22
- Invalid chunk size.
- 32
- Media type invalid.
- 33
- Method does not support a body.
- 34
- Method requires a body.
- 43
- The DOCSTATUS value specified is invalid.
- 45
- The character set specified is invalid.
- 46
- The CLIENTCONV option is invalid.
- 49
- The format of the path option is invalid.
- 54
- The HTTP method is not valid.
- 63
- URIMAP object disabled.
- 64
- Host in URIMAP definition does not match the host specified when this session was opened.
- 69
- Chunked transfer-coding not supported with this HTTP version.
- 71
- Chunked transfer-coding error.
- 74
- The connection has been closed. The server might have timed out because of inactivity on this connection.
- 76
- MEDIATYPE option required.
- 79
- Pipelining is in progress. Expect header cannot be sent.
- 80
- CHARACTERSET cannot be specified with NOCLICONVERT.
- 120
- The CHUNKING option is invalid.
- 121
- FROMLENGTH option required.
- 122
- FROM option required.
- 123
- No message body specified. Use FROM, DOCTOKEN, or CHUNKEND.
- 124
- CHUNKING option not specified, FROMLENGTH option required.
- 125
- CHUNKNO specified, FROM option required.
- 126
- CHUNKNO specified, FROMLENGTH option required.
- 127
- CHUNKYES specified, FROM option required.
- 128
- CHUNKYES specified, FROMLENGTH option required.
- 129
- FROM option not allowed with CHUNKEND.
- 130
- FROMLENGTH option not allowed with CHUNKEND.
- 131
- FROMLENGTH option specified as zero.
- 132
- METHOD option not allowed for second or subsequent chunks.
- 133
- MEDIATYPE option not allowed for second or subsequent chunks.
- 135
- PATH option not allowed for second or subsequent chunks.
- 136
- METHOD option required.
- 142
- AUTHENTICATE is invalid. The CVDA is not NONE or BASICAUTH.
- 144
- One or more of the Web command parameters is invalid.
- 145
- Channel was not specified, and there is no current channel.
- 147
- Internal conversion error.
- 150
- Conversion requested, but the data to be sent is in a DATATYPE BIT container.
- 17 IOERR
- RESP2
values are:
- 42
- Socket error.
- 22 LENGERR
- RESP2
values are:
- 5
- The PATHLENGTH option value was not greater than zero.
- 8
- The QUERYSTRLEN option value was not greater than zero.
- 50
- The FROMLENGTH option value was not greater than zero.
- 139
- USERNAMELEN is negative or is greater than 256.
- 140
- PASSWORDLEN is negative or is greater than 256.
- 70 NOTAUTH
- RESP2
values are:
- 100
- Path barred by security exit.
- 110
- XWBAUTH error. The XWBAUTH global user exit has issued a UERCERR return code because the XWBAUTH exit is required but cannot return a valid response.
- 13 NOTFND
- RESP2
values are:
- 61
- The URIMAP object specified was not found.
- 19 NOTOPEN
- RESP2
values are:
- 27
- Invalid session token.
- 124 TIMEDOUT
- 156
- Timeout on socket send.
- 112 TOKENERR
- RESP2
values are:
- 47
- The document token specified is invalid or the document has been deleted.