WEB SEND (Server)

Send an HTTP response, or a non-HTTP message.

WEB SEND

Conditions: CHANNELERR, CONTAINERERR, IOERR, INVREQ, LENGERR, NOTFND

This command is threadsafe.

Description

When the CICS® application is in the server role, the WEB SEND command specifies a response to be sent using CICS Web support or the CICS business logic interface. Here are the possible responses:

A response to an HTTP request that was made by a Web client, to CICS as an HTTP server. For guidance on the correct use of the WEB SEND command for this purpose, see Sending an HTTP response from CICS as an HTTP server.
A non-HTTP message handled by CICS Web support facilities, with the user-defined (USER) protocol on the TCPIPSERVICE definition. For guidance on non-HTTP messages, see CICS web support and non-HTTP requests.
A response to a request from another application that has used the CICS business logic interface to contact the program directly, rather than going through the CICS HTTP listener. For guidance on the CICS business logic interface, see Introduction to the CICS business logic interface.

One response only can be sent during a task. This can be a standard response using one WEB SEND command, or a chunked response using a sequence of WEB SEND commands.

If you attempt to send a second response during the same task, the result depends on whether the IMMEDIATE option or the EVENTUAL option was specified on the WEB SEND command for the first response.

If the IMMEDIATE option was used for the first response, an error is returned when you attempt the second response.
If the EVENTUAL option was used for the first response, the second response overwrites the components of the previous response (status line, HTTP headers and message body). The first response is lost, and the second response is sent.

Each time a request from a Web client is received, CICS starts a new task to process the request.

If the body of the server HTTP request is held in a container before it is sent to the server, CICS keeps the body in, and sends it from, 64-bit storage. If the body of the server HTTP request is held in an application buffer and needs to be copied or converted before it is sent, CICS keeps the body in, and sends it from, 64-bit storage. However, when a document is sent, the document is processed in 31-bit storage.

Options

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.
EVENTUAL: sends the response to the Web client at end of task. If CHUNKING is specified, the EVENTUAL option is ignored. For message sends that do not use chunked transfer-coding, EVENTUAL is the default.

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 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. HTML coded character sets lists the IANA character sets that are supported by CICS for code page conversion.

When the CHARACTERSET option is specified, SRVCONVERT is assumed, so code page conversion of the entity body takes place. As an alternative to selecting the character set yourself, specifying either 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 the CHUNKYES option 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 the CHUNKEND option 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 the CHUNKEND option, the transaction is abended with abend code AWBP. An incomplete chunked message should be ignored and discarded by the recipient.

Sending an HTTP request or response with chunked transfer-coding 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.

If you are using the CONTAINER option, do not specify the CHUNKING option. A chunked response cannot be sent from a container.

CLNTCODEPAGE(data-value)

This option is supported for upgrade purposes only. CHARACTERSET replaces it. The action taken by CICS is the same for both keywords.

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 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.

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.

When CONTAINER is specified, CICS stores the HTTP body in, and sends it from, 64-bit storage.

DOCSTATUS(cvda)

indicates whether the document should be deleted or not deleted during processing of the WEB SEND command. The CVDA values are:

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, these generate a NOTFND response.
NODOCDELETE: CICS does not delete the document during processing of the WEB SEND command. This is the default value for DOCSTATUS.

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 using the EXEC CICS DOCUMENT CREATE, INSERT, and SET commands. 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.

When DOCTOKEN is specified, the document is processed in 31-bit storage.

FROM(data-area)

Specifies a buffer of data that 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.

When FROM is specified, if CICS needs to copy or convert the HTTP body before it is sent, the body is copied or converted in, and sent from, 64-bit storage.

There is no set maximum limit for the size of the data-area, but its size is limited in practice by storage considerations. Producing an entity body for an HTTP message 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.

The standard CICS form of a host code page name consists of the code page number (or more generally CCSID) written using 3 to 5 decimal digits as necessary then padded with trailing spaces to 8 characters. For code page 37, which is fewer than 3 digits, the standard form is 037. CICS now also accepts any decimal number of up to 8 digits (padded with trailing spaces) in the range 1 to 65535 as a code page name, even if it is not in the standard form.

When the HOSTCODEPAGE option is specified, SRVCONVERT is assumed, so code page conversion of the entity body takes place. Specifying either 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.

If you are using the CONTAINER option, do not specify the HOSTCODEPAGE option.

LENGTH(data-value)

This option is supported for upgrade purposes only. STATUSLEN replaces it.

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 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 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 the CONTAINER option is used, CICS identifies the host code page as the code page that was used for data encoding, when the HTTP body was stored in the container.

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, and an INVREQ RESP2 code is issued. 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.

BIT containers contain non-text media, and therefore do not support code page conversion. As a result, if you code either the SRVCONVERT or CHARACTERSET options with a BIT container, an INVREQ RESP2 error is produced.

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.

HTTP status code reference for CICS web support 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.

Conditions

122 CHANNELERR

RESP2 values are:

2: The channel specified by the CHANNEL option could not be found.

110 CONTAINERERR

RESP2 values are:

2: The container specified by the CONTAINER option could not be found.

16 INVREQ

RESP2 values are:

1: The command is being issued in a non-CICS Web support application.
11: Action code invalid.
13: Close status invalid.
14: Invalid code page combination.
32: Media type invalid.
41: The connection has been closed.
46: The SERVERCONV option is invalid.
72: Status code does not support a message body.
75: Invalid send sequence.
77: Chunk incomplete.
80: CHARACTERSET cannot be specified with NOSRVCONVERT.
81: HOSTCODEPAGE cannot be specified with NOSRVCONVERT.
85: Chunking cannot be used with non-HTTP messages.
86: Chunking cannot be used with HTTP/1.0 clients.
87: Status code not allowed.
88: Host code page not allowed.
89: Previous send over this connection failed. No further sends permitted.
90: STATUSCODE and STATUSTEXT options not allowed for second or subsequent chunks.
91: CHARACTERSET and CLNTCODEPAGE options not allowed for second or subsequent chunks.
92: HOSTCODEPAGE option not allowed for second or subsequent chunks.
93: MEDIATYPE option not allowed for second or subsequent chunks.
94: CLOSESTATUS option not allowed for second or subsequent chunks.
95: SERVERCONV option not allowed for second or subsequent chunks.
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.
143: The DOCSTATUS value specified is invalid.
145: Channel was not specified, and there is no current channel.
147: Internal conversion error.
148: User protocol is not supported for containers.
150: Conversion requested, but data to be sent is in a DATATYPE BIT container.
151: Chunking is invalid during Web error processing.
152: ACTION(EVENTUAL) is invalid during Web error processing.

17 IOERR

RESP2 values are:

42: Socket error.

22 LENGERR

RESP2 values are:

50: The FROMLENGTH option value was not greater than zero.

13 NOTFND

RESP2 values are:

1: The document has not been created, or has been deleted, or the name is incorrectly specified.
7: Client code page (character set) not found.
83: Host code page (for server) not found.