WEB SEND (server)

WEB SEND for CICS as an HTTP server selects an item for delivery by XCICS Web support or the XCICS business logic interface, and specifies options for sending it. The item can be:

A response to an HTTP request that was made by a Web client, to XCICS as an HTTP server. For guidance on the correct use of the WEB SEND command for this purpose, see "Writing Web-aware application programs for XCICS as an HTTP server" in the XCICS Internet Guide.

A non-HTTP message handled by XCICS Web support facilities, with the user-defined (USER) protocol on the TCPIPSERVICE definition.For guidance on non-HTTP messages, see "XCICS Web support and non-HTTP requests" in the XCICS Internet Guide.

Only one response 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 ACTION(IMMEDIATE) option or the ACTION(EVENTUAL) option was specified on the WEB SEND command for the first response.

If the ACTION(IMMEDIATE) option was used for the first response, an error is returned when you attempt the second response.

If the ACTION(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, XCICS starts a new task to process the request.

WEB

SEND
DOCTOKEN(data-value) | [FROM(data-area) [FROMLENGTH(data-value) | CHUNKING(cvda)]]
[MEDIATYPE(data-value)]
[SERVERCONV(cvda)]
[CHARACTERSET(data-value) | CLNTCODEPAGE(data-value)]
[HOSTCODEPAGE(data-value)]
[STATUSCODE(data-value)]
[STATUSTEXT(data-area) [STATUSLEN(data-value) | LENGTH(data-value)]]
[ACTION(cvda)]
[CLOSESTATUS(cvda)]

specifies how the message should be sent out. The CVDA values that apply for XCICS as an HTTP server are:

sends the response immediately to the Web client. If CHUNKING is specified, the IMMEDIATE option is assumed. For message sends that do not use chunked transfer-coding, EVENTUAL is the default, which sends the response at end of task.

sends the response to the Web client at end of task. If CHUNKING is specified, the EVENTUAL option is ignored. This option produces the same behaviour as XCICS Web support had in releases before XCICS Transaction Server for z/OS, Version 3 Release 1, and it is the default for XCICS as an HTTP server.

specifies a character set into which XCICS 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. XCICS does not support all the character sets named by IANA. The XCICS Internet Guide lists the IANA character sets that are supported by XCICS for code page conversion.

When the CHARACTERSET option is specified, SERVERCONV(SRVCONVERT) is assumed, so code page conversion of the entity body takes place. As an alternative to selecting the character set yourself, specifying either SERVERCONV(SRVCONVERT), or HOSTCODEPAGE (if allowed), or both, and omitting CHARACTERSET, lets XCICS 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.

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 XCICS 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. Specify other options for the message, such as the CLOSESTATUS option, on the first WEB SEND command of the sequence, but do not specify them on subsequent commands. 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. XCICS 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 CHUNKING(CHUNKEND), the transaction is abended with abend code AWBP. An incomplete chunked message should be ignored and discarded by the recipient.

The XCICS 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:

Chunked transfer-coding is not used for the message. This is the default if the CHUNKING option is not specified.

Chunked transfer-coding is in progress. The data specified by the FROM option represents a chunk of the message.

Chunked transfer-coding is complete. No data is specified for this send. XCICS sends an empty chunk to the recipient to complete the chunked message.

This option is supported for migration purposes only. CHARACTERSET replaces it. The action taken by XCICS is the same for both keywords. This means that code page conversion does take place when CLNTCODEPAGE is specified, even if the SERVERCONV option is not specified. Code page conversion does not take place if all the code page conversion options are omitted.

specifies whether or not XCICS closes the connection after sending the message. The default is that the connection is not closed. The CVDA values are:

XCICS 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, XCICS 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 Web client that the connection is closed after the chunked message is complete.

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), XCICS sends the same header, to notify that a persistent connection will be maintained.

specifies the 16-byte binary token of a document to be sent as the message body. The document is created using the XCICS Document interface (EXEC XCICS DOCUMENT CREATE, INSERT, and SET commands), as described in the XCICS Application Programming Guide. The FROM option provides an alternative way to create a message body.

The body of a chunked message cannot be formed from XCICS documents, so the DOCTOKEN option cannot be used for chunked transfer-coding.

XCICS documents cannot be converted to the UTF-8 and UTF-16 character encodings.

specifies a buffer of data which 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.

There is no set maximum limit for the size of the data-area, but its size is limited in practice by storage considerations. The XCICS Internet Guide has more information about these.

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.

specifies the 8-character name of the XCICS (host) code page that was used by the application program for the entity body of the response. When the HOSTCODEPAGE option is specified, SERVERCONV(SRVCONVERT) is assumed, so code page conversion of the entity body takes place. Specifying either SERVERCONV(SRVCONVERT), or CHARACTERSET, or both, and mitting HOSTCODEPAGE, lets XCICS identify the host code page.

If a XCICS document is used to form the response body (DOCTOKEN option), do not specify the HOSTCODEPAGE option, because XCICS identifies the host code page from the XCICS 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 XCICS 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.

specifies the data content of the message body, for example text/xml. The media type is up to 56 alphanumeric characters, including appropriate punctuation. See the XCICS Internet Guide for more information about media types. XCICS checks that the format of the media type is correct, but does not check the validity of the media type against the data content. XCICS 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.

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, XCICS supplies a default of 200.

The XCICS Internet Guide has information about the use of status codes for XCICS Web support. For status codes 204, 205, and 304, a message body is not allowed, and XCICS returns an error response to the command if you attempt to include one. Other than that, XCICS does not check that your use of the status code is appropriate.

specifies the length, as a fullword binary value, of the string supplied on the STATUSTEXT option.

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.