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.

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 the user application must 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 have 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 must 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 must be accompanied by a message body giving special information, create an appropriate entity body.
      You typically need special information 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, you cannot use the DOCTOKEN option.
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.
   MEDIATYPE has no default. If you do not specify it, 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 you do not have to make this choice.

   Only one response can be sent during a task. It 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 that no more requests can 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 you specify another code page conversion option but not SERVERCONN. 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 original request from the web client. 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, your application must analyze the header, which might include quality values to indicate the web client 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, use the HOSTCODEPAGE option to identify the code page for your application, 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 nontext 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, follow the special instructions in Sending an HTTP request or response with chunked transfer-coding.
   You must 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.