Code page conversion for CICS as an HTTP server

When CICS® as an HTTP server exchanges messages with a Web client, code page conversion is normally required for the message bodies. The method of specifying this depends on whether you are making an application-generated response or a static response, and whether you are using a Web-aware application or a non-Web-aware application.

Request line and HTTP headers

Code page conversion for a request line or status line and for HTTP headers is handled as follows:
  • Start of changeSoon after receiving a request, CICS converts the request line (including any query string) and HTTP headers, from their character set, into the EBCDIC code page specified by the LOCALCCSID system initialization parameter (which applies to the whole of the local CICS region, and has a default of 037). For a successful conversion, you should set the LOCALCCSID system initialization parameter to any EBCDIC code page into which the ASCII Latin-1 character set ISO-8859-1 (code page 819) can be converted. If LOCALCCSID is set to an unsuitable code page, CICS uses the default EBCDIC code page 037 instead.End of change
  • Start of changeWhen a Web-aware application uses the WEB EXTRACT, WEB READ HTTPHEADER or WEB READ FORMFIELD commands to extract information from the request line (including any query string) and HTTP headers, the information is presented in its converted form, in the EBCDIC code page specified by the LOCALCCSID system initialization parameter (or the default 037). End of change
  • When CICS is preparing to send out a response, the status line and HTTP headers may be generated by CICS, or specified by the application using the WEB WRITE HTTPHEADER command. Before sending, all the headers and the status line are converted from the EBCDIC code page in which they were specified, into the US-ASCII character set.

Message bodies: application-generated response

If the request is to have a dynamic response from a user-written application, code page conversion for message bodies is handled as follows:
  • If a Web-aware application receives the request, CICS carries out code page conversion if any of the code page conversion options are used to specify conversion on the WEB RECEIVE command. If none of the options are present, code page conversion does not take place. You can either supply, or allow CICS to identify, the character set, and request a code page if the default is not suitable.
  • If an analyzer program is used in the processing path for the request, the analyzer program can specify or suppress code page conversion for the request body that is passed to subsequent processing stages in a COMMAREA. You supply both the character set and the application code page that are used. CICS still holds the original version of the request body, and Web-aware applications using the EXEC CICS WEB API commands access the original body, not the COMMAREA.
  • If a converter program needs the request in a COMMAREA, and there is no analyzer program in the processing path, CICS converts the request body in the COMMAREA, identifying the character set and converting to the default code page.
  • To identify the character set that the Web client used for the request body, CICS examines the request headers. If the request headers do not provide this information, or the specified character set is unsupported, CICS assumes as a default that the message body is in the ISO-8859-1 character set. If the message body is not in that character set, and there is no information in the headers, you need to identify the correct character set.
  • By default, CICS converts the request body into the EBCDIC code page specified by the LOCALCCSID system initialization parameter. If your application requires a different code page (which could be EBCDIC or ASCII), you can specify this.
  • If a Web-aware application sends the response, CICS carries out code page conversion if any of the code page conversion options are used to specify conversion on the WEB SEND command. If none of the options are present, code page conversion does not take place. For Web-aware applications, note that CICS documents and document templates cannot be converted to the UTF-8 and UTF-16 character encodings. If you want to send an outbound message in these character encodings, use the FROM option on the WEB SEND command to specify a buffer of data to form the message body, rather than using the DOCTOKEN option to specify a CICS document.
  • If a converter program using a COMMAREA sends the response, CICS mirrors the code page conversion that was carried out for the request. The character set and host code page settings from the analyzer program, or the default settings in the absence of an analyzer program, are used. If the analyzer program suppressed code page conversion for the request, no code page conversion is carried out for the response body.

Message bodies: static response

If the request is to have a static response determined by a URIMAP definition, code page conversion for message bodies is handled as follows:

  • For a static response, CICS does not examine any message body that is present on a Web client's request, so no code page conversion is required.
  • You specify code page conversion for the body of the response in the URIMAP definition that produces the static response. If the response contains text, the URIMAP definition needs to specify all of the following:
    • A text media type, using the MEDIATYPE attribute. There is no default for this attribute.
    • A character set for the Web client, using the CHARACTERSET attribute. (Note that CICS documents and document templates cannot be converted to the UTF-8 and UTF-16 character encodings.)
    • The code page in which the CICS document template or HFS file for the response is encoded, using the HOSTCODEPAGE attribute.
CICS retrieves the HFS file, or retrieves the CICS document template and creates the document, and then carries out appropriate code page conversion.