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:
  • Soon 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.
  • When an 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).
  • 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 copy of the request which is passed to subsequent processing stages in a block of storage. You supply both the character set and the application code page that are used. CICS still holds the original version of the request body. Applications or converter programs which use the EXEC CICS WEB API commands access the original body, not the block of storage, and they can specify code page conversion on the EXEC CICS WEB API commands.
  • When a converter program is passed the request in a block of storage, if there is no analyzer program in the processing path, CICS converts the request body in the block of storage, 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 (which applies to the whole of the local CICS region, and has a default of 037). If your application requires a different code page (which could be EBCDIC or ASCII), you can specify this.
  • If an application or converter program sends the response using the EXEC CICS WEB API commands, 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.
  • If a converter program produces the response in a block of storage and passes it to CICS for sending, 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.
    • The code page in which the CICS document template or z/OS® UNIX file for the response is encoded, using the HOSTCODEPAGE attribute.
CICS retrieves the z/OS UNIX file, or retrieves the CICS document template and creates the document, and then carries out appropriate code page conversion.

Concept Concept

Feedback


Timestamp icon Last updated: Saturday, 7 April 2018


http://publib.boulder.ibm.com/infocenter/cicsts/v4r2/topic/com.ibm.cics.ts.internet.doc//com.ibm.cics.ts.internet.doc/topics/dfhtl_cpcserver.html