Start of change

WEB SEND (Client)

Send an HTTP request by CICS® as an HTTP client, using CICS Web support.

Read syntax diagramSkip visual syntax diagram
WEB SEND (CICS as an HTTP client)

>>-WEB--SEND--SESSTOKEN(data-value)--METHOD(cvda)--------------->

>--+-----------------------------------------+------------------>
   +-PATH(data-area)--PATHLENGTH(data-value)-+   
   '-URIMAP(data-value)----------------------'   

>--+-------------------------------------------------+---------->
   '-QUERYSTRING(data-area)--QUERYSTRLEN(data-value)-'   

>--+----------------------------------------------------------------------------------------+-->
   '-MEDIATYPE(data-value)--+-------------------------------------------------------------+-'   
                            +-DOCTOKEN(data-value)----------------------------------------+     
                            '-FROM(data-area)--FROMLENGTH(data-value)--+----------------+-'     
                                                                       '-CHUNKING(cvda)-'       

>--+------------------+--+--------------------------+----------->
   '-CLIENTCONV(cvda)-'  '-CHARACTERSET(data-value)-'   

>--+--------------+--+-------------------+---------------------><
   '-ACTION(cvda)-'  '-CLOSESTATUS(cvda)-'   

Conditions: IOERR, INVREQ, LENGERR, NOTFND, NOTAUTH, NOTOPEN, 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" in the CICS Internet Guide.

Tip: For CICS as an HTTP client, the WEB SEND command cannot be used after the connection to the server has been closed. This happens 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.
Tip: 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, bear in mind that the WEB CONVERSE command does not support chunked transfer-coding, because this requires a sequence of send actions, and the WEB CONVERSE command provides a single send action.

Options

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:
  1. The method (METHOD option) must be compatible with chunked transfer-coding.
  2. 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, Start of changebut not spacesEnd of change. 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. Start of changeCICS uses this information to produce the Content-Type header for the message.End of change

Start of changeFor 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.End of change

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.

Conditions

NOTOPEN
RESP2 values are:
27
Invalid session token.
INVREQ
RESP2 values are:
11
Action code invalid.
12
Start of changeURIMAP and PATH specified. Only one allowed. OR: URIMAP option not allowed for second or subsequent chunks.End of change
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.
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 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.
76
MEDIATYPE option required.
79
Pipelining is in progress. Expect header cannot be sent.
120
The CHUNKING option is invalid.
121
FROMLENGTH option required.
122
FROM option required.
123
No message body specified. Use FROM, DOCTOKEN or CHUNKING(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 CHUNKING(CHUNKEND).
130
FROMLENGTH option not allowed with CHUNKING(CHUNKEND).
131
FROMLENGTH option specified as zero.
132
METHOD option not allowed for second or subsequent chunks.
133
Start of changeMEDIATYPE option not allowed for second or subsequent chunks, or when Content-Type header already provided.End of change
Start of change135End of change
Start of changePATH option not allowed for second or subsequent chunks.End of change
Start of change136End of change
Start of changeMETHOD option required.End of change
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.
NOTFND
RESP2 values are:
61
The URIMAP object specified was not found.
TOKENERR
RESP2 values are:
47
The document token specified is invalid.
IOERR
RESP2 values are:
42
Socket error.
NOTAUTH
RESP2 values are:
100
Path barred by security exit.
End of change