Start of change

Sending an HTTP response from CICS as an HTTP server

Use the WEB SEND command to make CICS® assemble the HTTP headers, entity body, status code and reason phrase for an HTTP response, carry out code page conversion, and transmit the response to the Web client.

Write any additional HTTP headers for the response using the WEB WRITE HTTPHEADER command before issuing the WEB SEND command, as described in Writing HTTP headers for a response. Also produce any entity body that is needed for the message, as described in Producing an entity body for an HTTP message.

You need to specify a status code and reason phrase on the WEB SEND command. Status codes and reason phrases explains what these are. HTTP status code reference for CICS Web support provides an overview of the status codes that your application might use. To plan your use of status codes and find further information about them, you should consult the HTTP specification to which you are working. See The HTTP protocol for more information about the HTTP specifications.

If wanted, the response can be sent in chunks (chunked transfer-coding). You cannot send pipelined responses back to a Web client (you must send a single response to each request sent by the Web client).

The CICS Application Programming Reference has full reference information and descriptions of the options available on the WEB SEND command. When you issue the command:

  1. Specify the STATUSCODE option to select an appropriate status code for the response, depending on the situation, and the STATUSTEXT and STATUSLEN options to provide the reason phrase. CICS does not validate your choice of status code, and it is the user application's responsibility to ensure that the value is valid and conforms to the rules for HTTP status codes. Depending on the status code that you select, you might need to complete some or all of the following steps before issuing the WEB SEND command:
    1. Check the HTTP version of the Web client's request, to ensure that the status code can be understood. The HTTP/1.1 specification includes more status codes than the HTTP/1.0 specification.
    2. If the HTTP specification states that the status code should be accompanied by certain HTTP headers, use the WRITE HTTPHEADER command to create those headers.
    3. If the HTTP specification states that the status code should be accompanied by a message body giving special information, create an appropriate entity body. This is normally the case when the status code indicates an error or requests further action from the client. Message bodies are not allowed with status codes 204, 205, and 304. If you have selected a status code that does not allow a message body, and attempt to use a message body, CICS gives an error response to the WEB SEND command.
  2. Identify the source of any entity body for the response by specifying either the DOCTOKEN option, for a CICS document that you have created, or the FROM option, for a body of data that you have assembled. If you are using the FROM option, specify the FROMLENGTH option to give the length of the entity body, or of the chunk if chunked transfer-coding is in use. For chunked transfer-coding, the DOCTOKEN option cannot be used.
  3. Specify the media type for the body of the response, using the MEDIATYPE option. CICS does not check the validity of the specification against the data content. There is no default. If you do not specify this, CICS does not build a Content-Type header for the response.
  4. If you want the message to be sent immediately, rather than at the end of the task (which is the default), specify IMMEDIATE for the ACTION option. If you are using chunked transfer-coding, IMMEDIATE is the default, so there is no need to make this choice.
    Note: 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.
  5. If you want to close the connection after sending the response, specify CLOSE for the CONNECTION option. CICS writes a Connection: close header on the response, which notifies the Web client that the connection is closed and no more requests should be sent. (For a Web client at HTTP/1.0 level, CICS achieves the same effect by omitting the Connection: Keep-Alive header.)
  6. Specify the appropriate settings for code page conversion of the message body.
    1. The SERVERCONV option provides overall control of code page conversion. Use it to specify whether or not code page conversion takes place. For CICS as an HTTP server, for compatibility with Web-aware applications coded in earlier releases, code page conversion is assumed if SERVERCONV is not specified but another code page conversion option is specified. If you want to prevent code page conversion, either specify SERVERCONV(NOSRVCONVERT), or omit all the code page conversion options.
    2. If you want code page conversion, but the character set selected by CICS is not suitable, use the CHARACTERSET option to specify an alternative. By default, CICS uses the character set specified in the Content-Type header of the Web client's original request. If that character set was unsupported or not stated, CICS uses the ISO-8859-1 character set instead.

      A Web client might specify alternative acceptable character sets in an Accept-Charset header. If you want to specify one of these, it is up to your application to analyze the header (which might include quality values to indicate the Web client's preference), and select an appropriate supported character set.

      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.
    3. If you want code page conversion, and are using the FROM option to specify the message body, you need to use the HOSTCODEPAGE option to identify your application's code page, if this is not the default code page for the local CICS region (as specified in the LOCALCCSID system initialization parameter). If you are using a CICS document (DOCTOKEN option), CICS identifies the host code page from the CICS document domain's record of the host code pages for the document.
    Code page conversion does not take place for messages that specify a non-text media type (unless you do not specify SERVERCONV, in which case for compatibility purposes, the media type is not taken into account). The HTTP headers and status line are always converted into the ISO-8859-1 character set by CICS.
  7. If you are using chunked transfer-coding (or chunking), in addition to the basic instructions in this topic, you need to follow the special instructions in Using chunked transfer-coding to send an HTTP request or response. You need to ensure that the procedure described in that topic is followed correctly, so that the chunked message is acceptable to the recipient. Chunked messages are sent using several instances of the WEB SEND command, with particular options.
End of change