Writing a converter program

To write a converter program, you need to construct decode and encode functions, and consider code page conversion.

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

You can write a converter program in Assembler, C, COBOL, or PL/I. Language-dependent header files, include files, and copy books are described in Reference information for converter programs.

Decode function: viewing and processing the HTTP request

The decode function of the converter program receives the HTTP request from the web client, together with a parameter list giving more information about the request. The HTTP request is passed to the converter program in a 32K block of storage, which is indicated by a pointer in the parameter list. The request 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.) If an analyzer program is used in the processing path, the analyzer program might have modified the content of the request.

In a converter program for CICS web support, you can use EXEC CICS WEB API commands to examine the HTTP request, if you prefer. The WEB EXTRACT command retrieves information about the request (such as the method and version). The WEB READ HTTPHEADER command or the HTTPHEADER browsing commands can be used to read the HTTP headers. The WEB RECEIVE command can be used to receive the body of the request. If you use any of the EXEC CICS WEB API commands, note that these commands return the original information from the web client's request, and you cannot use them to see any modifications that an analyzer program has made. Changes by an analyzer program are only visible in the parameter list and block of storage passed directly to the converter program.

The name of the user-written application program that should provide data for the response is supplied in the parameter list, 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 directly to the converter program in a user token.

Using the information which you have obtained about the web client's request, the decode function of the converter program needs to:
  • Determine whether processing should continue for the request, or whether CICS® should return an error response to the web client.
  • Specify 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.
  • Construct 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 block of storage containing the HTTP request can be reused, or a new COMMAREA can be specified.

Encode function: producing the response

When the user-written application program has carried out its processing using the input supplied by the converter program, the encode function of the converter program receives an output COMMAREA from the application program. Using this data, the encode function of the converter program needs to:
  • Invoke further application programs, if more than one application program is needed to supply data. To do this, the encode function 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. Calling more than one application program from a converter program has more information about this.
  • Construct an HTTP response to be sent to the web client.

In a converter program for CICS web support, you can use EXEC CICS WEB API commands to produce and send the response to the web client. The WEB WRITE HTTPHEADER command can be used to write HTTP headers for the response. The WEB SEND command can be used to assemble and send the response.

Alternatively, the converter program can construct the HTTP response manually in a buffer of storage, and return this to CICS for sending to the web client. The response must contain an HTTP version, status code, status text, any HTTP headers that are required, and the message body. The format of the response should be compliant with the HTTP protocol specification to which you are working (HTTP/1.0 or HTTP/1.1). To obtain a buffer of storage for the HTTP response, you can:
  • Issue a GETMAIN command to obtain storage.
  • Use storage acquired in an earlier stage of processing (such as the analyzer program).
  • Construct the response in the COMMAREA returned by the user-written application program.
The first word of the area used for the response must contain the length of the area (that is, the length of the HTTP response plus 4). On exit from the encode function of the converter program, the data pointer in the parameter list must point to this block of storage. (If you use EXEC CICS WEB API commands to send the response instead, CICS ignores and discards any block of storage indicated by this pointer.)

Whichever method you use to construct the HTTP response, CICS normally inserts some HTTP headers suitable for an HTTP/1.0 or HTTP/1.1 response, which are listed in HTTP header reference for CICS web support. If the response produced by the converter program already contains these headers, CICS does not replace them. If the response has been flagged by an analyzer program for pre-CICS TS Version 3 compatibility processing, because a web client requires a response identical with the response it would have received before CICS TS Version 3, only the headers that were sent to clients before CICS Transaction Server for z/OS®, Version 3 Release 1 are used. This flag only works if the converter program produces the response manually in a block of storage. If the converter program uses the EXEC CICS WEB API commands to send the response, the flag has no effect.

Code page conversion

When you use EXEC CICS WEB API commands in a converter program to view the HTTP request and produce the response, code page conversion takes place as you specify in the commands, in the same way as for any other program which uses the EXEC CICS WEB API commands.

A converter program is not able to specify code page conversion settings for the HTTP request passed to it in the 32K block of storage. 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, either use an analyzer program in the processing path to specify alternative code page conversion settings, or use the EXEC CICS WEB API commands to handle the request.

If your converter program constructs the HTTP response manually in a buffer of storage, CICS mirrors the code page conversion that was carried out for the request passed in the 32K block of storage. The response is sent to the web client using the character set and host code page settings specified by the analyzer program, or in the absence of an analyzer program, the standard settings described in this topic. If the analyzer program suppressed code page conversion for the request, no code page conversion is carried out for the response body. If this outcome is not suitable, use the EXEC CICS WEB API commands to produce the response instead.

Converter programs for the CICS business logic interface

When you use a converter program with the CICS business logic interface, there are restrictions which might affect how you construct the COMMAREA that is passed to the user-written application program, and the buffer of storage containing the response. For more information, see Offset mode and pointer mode.

Do not use EXEC CICS WEB API commands in a converter program which is written for the CICS business logic interface.