Start of change

Converter programs

Converter programs are primarily for use with application programs that were not originally coded for use with the Web. They can also be used to combine output from several application programs into a single HTTP message.

Attention: This topic contains Product-sensitive Programming Interface and Associated Guidance Information.

Converter programs are not used when CICS® is an HTTP client, or for Web service processing; they can only be invoked when CICS is an HTTP server. The role of converter programs in the CICS Web support process for CICS as an HTTP server is described in HTTP request and response processing for CICS as an HTTP server. Planning your CICS Web support architecture for CICS as an HTTP server has information to help you plan your architecture for CICS as an HTTP server.

A URIMAP definition can invoke a converter program to carry out relevant processing for HTTP requests. If an analyzer program is used in CICS Web Support processing, the analyzer program can also invoke a converter program. A converter program can be useful in the following circumstances:
  • When application programs that were not originally coded for use with the Web need to receive input in the form of a COMMAREA, or need their output to be converted into an HTTP response. Web-aware application programs, which are coded using the EXEC CICS WEB and EXEC CICS DOCUMENT application programming interfaces, should not require this conversion to take place. You can use a converter program to perform this conversion or other processing on the content of the request.
  • When you want to make more than one application program work on the same request data in sequence, and return a single HTTP response to the Web client.

If a converter program is invoked directly from a URIMAP definition, the PROGRAM attribute of the URIMAP definition (which specifies the name of the application program to process the request) can be passed to the converter program, and the converter program can choose to override it.

A converter program is not able to specify code page conversion settings for a request that it receives from an analyzer program (through a pointer in the COMMAREA indicating a 32K block of storage that contains the request). If a converter program is invoked directly from a URIMAP definition, and the headers for the Web client's request indicate that the message body is text, CICS converts the message body supplied in the block of storage using the following standard settings:
  • For the character set, if the Web client's request has a Content-Type header naming a character set supported by CICS, that character set is used. 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.
  • For the host code page, CICS uses the default code page for the local CICS region, as specified in the LOCALCCSID system initialization parameter.
If these standard settings are not suitable, or if code page conversion is not wanted, an analyzer program must be used in the processing path to specify alternative settings.

For the response sent to the Web client, 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.

A converter program is not associated with a TCPIPSERVICE definition in the same way as an analyzer program. You can use any converter program that is local to the CICS system, to process any HTTP request. For a given request, the same converter program is called for both the decode and encode functions.

The converter program has two functions:
Decode
The HTTP request is passed to the decode function of the converter program in a 32K block of storage, which is indicated by the user_data pointer in the COMMAREA. It has already been divided into separate elements, such as the method, request headers and body. (Note that if the request is too long to fit into the block of storage, the remainder of the data is not passed to the converter program.) The name of the application program that should handle the request is also supplied, either taken from the URIMAP definition for the request, or set by the analyzer program. If an analyzer program is used, it can provide additional information in a user token. Using this information, the decode function:
  • Determines whether processing should continue for the request, or whether CICS should return an error response to the Web client.
  • Specifies the name of the user-written application program that is to process the request and provide the response. If the name has already been input from a URIMAP definition or by an analyzer program, the converter program can accept or change this.
  • Constructs the COMMAREA that is passed to the user-written application program. The COMMAREA includes data from the Web client's request which has been converted into an acceptable input format for the application program. The storage containing the HTTP request can be reused, or a new COMMAREA can be specified.

Start of changeIf a converter program does not use the decode function to create a COMMAREA for the application program, the 32 767 byte buffer used to receive the HTTP request is passed to the application program.End of change

Encode
Using the COMMAREA returned by the user-written application program, the encode function:
  • If more than one application program is to supply data, sets the loop response, to call the decode function again. The decode function changes the name of the application program and supplies appropriate input in a COMMAREA. The output is returned to the encode function again.
  • Constructs an HTTP response in a COMMAREA, which is to be sent to the Web client.
Converter programs are used by CICS Web support and by the CICS business logic interface. The role of the converter program in the CICS business logic interface is described in Using the CICS business logic interface to call a program. The caller of the CICS business logic interface determines whether a converter is required, and which converter program should be called. For a given request, the same converter program is called for both the decode and encode functions.

For more information about writing user-replaceable programs, see the CICS Customization Guide.

All the user-replaceable programs must be local to the system in which CICS Web support is operating. If you do not use autoinstall for programs, you must define and install program definitions for all user-replaceable programs used by CICS Web support, including the analyzer and converter programs. If you use autoinstall for programs, you must ensure that user-replaceable programs are installed with the correct attributes.

For detailed information about the converter, see Reference information for converter programs.

End of change