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.

Converter programs are not used when XCICS is an HTTP client, or for Web service processing; they can only be invoked when XCICS is an HTTP server. The role of converter programs in the XCICS Web support process for XCICS as an HTTP server is described in "HTTP request and response processing for XCICS 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 XCICS 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 associated with a TCPIPSERVICE definition in the same way as an analyzer program. You can use any converter program that is local to the XCICS system, to process any HTTP request. For a given request, the same converter program is called for both the decode and encode functions.

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 XCICS 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.

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.