Start of change

WEB SEND (Server)

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

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

>>-WEB--SEND---------------------------------------------------->

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

>--+-----------------------+--+------------------+-------------->
   '-MEDIATYPE(data-value)-'  '-SERVERCONV(cvda)-'   

>--+--------------------------+--+--------------------------+--->
   +-CHARACTERSET(data-value)-+  '-HOSTCODEPAGE(data-value)-'   
   '-CLNTCODEPAGE(data-value)-'                                 

>--+------------------------+----------------------------------->
   '-STATUSCODE(data-value)-'   

>--+-------------------------------------------------+---------->
   '-STATUSTEXT(data-area)-+-STATUSLEN(data-value)-+-'   
                           '-LENGTH(data-value)----'     

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

Conditions: IOERR, INVREQ, NOTFND

This command is threadsafe.

Description

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

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, CICS starts a new task to process the request.

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. For message sends that do not use chunked transfer-coding, EVENTUAL is the default, which sends the response at end of task.
EVENTUAL
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 CICS Web support had in releases before CICS Transaction Server for z/OS, Version 3 Release 1, and it is the default for CICS as an HTTP server.
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. The CICS Internet Guide lists the IANA character sets that are supported by CICS 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 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 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 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 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.
CLNTCODEPAGE(data-value)
This option is supported for migration purposes only. CHARACTERSET replaces it. The action taken by CICS 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.
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 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.

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.
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 (EXEC CICS DOCUMENT CREATE, INSERT, and SET commands), as described in the CICS 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 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 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 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. 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. 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 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.

LENGTH(data-value)
This option is supported for migration purposes only. STATUSLEN replaces it.
MEDIATYPE(data-value)
specifies the data content of the message body, 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. 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 SERVERCONV(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:
  1. If the Web client's request has a Content-Type header naming a character set supported by CICS, that character set is used.
  2. 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.
  3. 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 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. 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.

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.

The CICS Internet Guide 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

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 SERVERCONV(NOSRVCONVERT).
81
HOSTCODEPAGE cannot be specified with SERVERCONV(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.
Start of change90End of change
Start of changeSTATUSCODE and STATUSTEXT options not allowed for second or subsequent chunks.End of change
Start of change91End of change
Start of changeCHARACTERSET and CLNTCODEPAGE options not allowed for second or subsequent chunks.End of change
Start of change92End of change
Start of changeHOSTCODEPAGE option not allowed for second or subsequent chunks.End of change
Start of change93End of change
Start of changeMEDIATYPE option not allowed for second or subsequent chunks.End of change
Start of change94End of change
Start of changeCLOSESTATUS option not allowed for second or subsequent chunks.End of change
Start of change95End of change
Start of changeSERVERCONV option not allowed for second or subsequent chunks.End of change
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.
NOTFND
RESP2 values are:
1
The document has not been created or the name is incorrectly specified.
7
Client code page (character set) not found.
83
Host code page (for server) not found.
IOERR
RESP2 values are:
42
Socket error.
End of change