Send an HTTP request by CICS® as an HTTP client, using CICS Web support.
WEB SEND (CICS as an HTTP client) >>-WEB SEND--SESSTOKEN(data-value)--+-GET----------+------------> +-HEAD---------+ +-POST---------+ +-PUT----------+ +-TRACE--------+ +-OPTIONS------+ +-DELETE-------+ '-METHOD(cvda)-' >--+-----------------------------------------+------------------> +-PATH(data-area)--PATHLENGTH(data-value)-+ '-URIMAP(data-value)----------------------' >--+-------------------------------------------------+----------> '-QUERYSTRING(data-area)--QUERYSTRLEN(data-value)-' >--+----------+--+------------------+---------------------------> '-| Body |-' +-CLICONVERT-------+ +-NOCLICONVERT-----+ '-CLIENTCONV(cvda)-' >--+--------------------------+--+--------------+---------------> '-CHARACTERSET(data-value)-' +-EXPECT-------+ '-ACTION(cvda)-' .-NOCLOSE-----------. >--+-------------------+----------------------------------------> +-CLOSE-------------+ '-CLOSESTATUS(cvda)-' >--+---------------------------------------------+------------->< | .-NONE---------------. | '-+--------------------+--+-----------------+-' +-BASICAUTH----------+ '-| Credentials |-' '-AUTHENTICATE(cvda)-'
Body |--MEDIATYPE(data-value)----------------------------------------> >--+-------------------------------------------------------------+--| | .-NODOCDELETE-----. | +-DOCTOKEN(data-value)-+-----------------+--------------------+ | +-DOCDELETE-------+ | | '-DOCSTATUS(cvda)-' | | .-CHUNKNO--------. | +-FROM(data-area)--FROMLENGTH(data-value)--+----------------+-+ | +-CHUNKYES-------+ | | +-CHUNKEND-------+ | | '-CHUNKING(cvda)-' | '-CONTAINER(data-value)-+---------------------+---------------' '-CHANNEL(data-value)-'
Credentials |--USERNAME(data-value)--+-------------------------+------------> '-USERNAMELEN(data-value)-' >--PASSWORD(data-value)--+-------------------------+------------| '-PASSWORDLEN(data-value)-'
Conditions: CHANNELERR, CONTAINERERR, INVREQ, IOERR, LENGERR, NOTAUTH, NOTFND, NOTOPEN, TIMEDOUT, TOKENERR
This command is threadsafe.
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.
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.
If the CONTAINER option is specified, CHANNEL is optional.
If the CHANNEL option is not specified, CICS assumes the current channel.
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.
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:If you are using the CONTAINER option, do not specify the CHUNKING option. A chunked response cannot be sent from a container.
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.
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.
The body of a chunked message cannot be formed from CICS documents, so the DOCTOKEN option cannot be used for chunked transfer-coding.
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.
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 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: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.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.
If the URIMAP option is specified, do not specify the PATH or PATHLENGTH options.
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.