Changes to user-replaceable programs

Changes to analyzer programs

Use of an analyzer program for CICS® Web support processing for individual HTTP requests is now optional. URIMAP definitions can be used to match the URLs of requests to the application program that processes them, and they can specify the use of a converter program and an alias transaction. If these are the only tasks performed by an analyzer program in your existing CICS Web support architecture, you can replace its function in request processing paths with a URIMAP definition.

You might have an existing analyzer program from an earlier CICS release that provides additional functions which you require during request processing, such as passing data to a converter program, or modifying code page conversion for non-Web-aware application programs that use a converter program. If this is the case, you can continue to use an analyzer program instead of a URIMAP definition for the relevant requests, or you can combine it with a URIMAP definition (by specifying the ANALYZER(YES) option).

When an analyzer program is used with a URIMAP definition, elements of the URIMAP definition (such as the name of the application program that handles the request) are passed to the analyzer program as input. An existing or new analyzer program can be used to make dynamic changes to these elements. You can also use an analyzer program to introduce monitoring or audit actions into the process.

An analyzer program must still be specified for each TCPIPSERVICE resource definition that is used for CICS Web support. The analyzer program specified for a TCPIPSERVICE definition is invoked to handle an HTTP request if CICS does not find a matching URIMAP definition for the request. This could be caused by a user error in typing a request URL, or because the appropriate URIMAP definition is not installed. (If the URIMAP definition exists but is disabled, the request is handled by the Web error program, not the analyzer program.)

A new CICS-supplied default analyzer program is provided to supply this error handling function for TCPIPSERVICE resource definitions that are used for CICS Web support. DFHWBAAX takes no action if a matching URIMAP definition is found. If no match is found, it gives control to the new user-replaceable Web error program DFHWBERX to produce an error response. DFHWBAAX is suitable for use where all of the requests using the port are handled using URIMAP definitions. It does not provide support for requests using the URL format that CICS Web support used before CICS TS 3.1.

The CICS-supplied sample analyzer program DFHWBADX is still provided. DFHWBADX, or your own customized version of it, is suitable for use if you need to provide basic support for both requests using URIMAP definitions, and requests using the URL format that CICS Web support used before CICS TS 3.1.

As supplied, DFHWBADX does not perform any analysis of a request when a matching URIMAP definition has been found for the request, even if the URIMAP specifies ANALYZER(YES). This means that the settings specified in the URIMAP definition for the alias transaction, converter program and application program are automatically accepted and used to determine subsequent processing stages. DFHWBADX uses the wbra_urimap input parameter to test for the presence of a URIMAP definition.

There are several changes to the input and output parameters specified in an analyzer program's COMMAREA:
  • A new input parameter wbra_urimap is provided to identify when a matching URIMAP definition is involved in the processing path for the request.
  • New input parameters wbra_hostname_ptr, wbra_hostname_length, wbra_querystring_ptr, and wbra_querystring_length provide the host name and query string specified on the Web client's request. An analyzer program can examine this information in addition to the path component of the URL to decide on subsequent processing stages, and to distinguish between virtual hosts (multiple hosts at the same IP address).
  • The parameters wbra_alias_tranid, wbra_converter_program, wbra_server_program and wbra_userid are now input parameters as well as output parameters. When a URIMAP definition is used, the TRANSACTION, CONVERTER, PROGRAM, and USERID attributes (respectively) of the URIMAP definition are passed to the analyzer program as these input parameters, and the analyzer program can choose to override these.
  • Two new output parameters are provided for code page conversion. The character set used by the Web client can be specified by the wbra_characterset parameter, and the wbra_hostcodepage parameter specifies the host code page suitable for the application program. CICS uses these parameters to carry out code page conversion before passing the request to the converter program (if used) or to the application. The output parameters are functionally equivalent to the existing wbra_dfhcnv_key parameter, with the important difference that using the new parameters means you do not have to create entries in the code page conversion table (DFHCNV). You can simply specify the character set and host code page, and CICS determines the appropriate conversion template. If your existing analyzer program uses the wbra_dfhcnv_key parameter, then until you change to the new parameters or remove the analyzer program from the processing path for requests, you need to retain the relevant DFHCNV entries for migration purposes.
  • A new output parameter wbra_commarea is provided to indicate where an application that does not use the EXEC CICS WEB API commands requires pre-CICS TS Version 3 compatibility processing. This flag is for existing applications in the specific circumstance where the Web client needs a response that is identical with the response it would have received before CICS TS Version 3. Setting this flag means that:
    • CICS does not add any response headers that would not have been used before CICS TS Version 3.
    • If error processing is required, CICS sends an error response that is suitable for, and labeled as, an HTTP/1.0 response, regardless of the HTTP version of the Web client. CICS would normally reply to a HTTP/1.1 client with an HTTP/1.1 error response, but this might mislead the client into thinking that the application would normally send a response at HTTP/1.1 level.
    A URIMAP definition may be set up for the request, but it must specify the analyzer program.

Analyzer programs cannot be invoked when CICS is an HTTP client, or for Web service processing; they can only be invoked when CICS is an HTTP server.

Changes to invocation of the converter program

Use of the converter program for CICS Web support processing for HTTP requests is still optional. Converter programs are primarily for use with application programs which were not originally coded for use with the Web, and need to receive input in the form of a COMMAREA. They can be used to convert output from one or more of these application programs into an HTTP message. 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.

The URIMAP definition can specify that a converter program is to carry out relevant processing for HTTP requests. The PROGRAM attribute of the URIMAP definition is passed to the converter program, and the converter program can choose to override it. If an analyzer program is used in CICS Web support processing, the analyzer program can also specify a converter program, and can pass data to the converter program in a COMMAREA or user token. If your existing analyzer program passes data to a converter program in this way, note that this function cannot be replicated by a URIMAP definition.

A converter program is not able to specify code page conversion settings for a request that it receives in a COMMAREA. If a converter program is specified in 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 COMMAREA 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.

The converter program cannot be invoked when CICS is an HTTP client, or for Web service processing; it can only be invoked when CICS is an HTTP server.

Changes to the Web error program

When a request error or an abend occurs in the CICS Web support process for CICS as an HTTP server, a user-replaceable Web error program provides an error response to the Web client. A Web error program receives or obtains information about the error situation. The program can customize the default HTTP response (including status code and status text) that CICS plans to send to the Web client, or build its own HTTP response, and return it to CICS for sending.

A new user-replaceable Web error transaction program, DFHWBERX, is supplied. DFHWBERX is used when the new CICS-supplied default analyzer DFHWBAAX is specified as the analyzer program on the TCPIPSERVICE definition, and no matching URIMAP definition is found for a request. In this situation, DFHWBAAX specifies DFHWBERX as the application program to handle the request. DFHWBERX could also be specified in another analyzer program, or as the PROGRAM attribute in a URIMAP definition if an error response is always wanted for the request.

DFHWBERX provides error handling as follows:
  • If the request is a POST request with media type text/xml, it is assumed to be a SOAP 1.1 request, and a SOAP 1.1 fault response is returned.
  • If the request is a POST request with media type application/soap+xml, it is assumed to be a SOAP 1.2 request, and a SOAP 1.2 fault response is returned.
  • All other requests are assumed to be a standard HTTP request, so a suitable HTTP response is composed and returned with a 404 (Not Found) status code.
The EXEC CICS WEB and DOCUMENT application programming interfaces are available from DFHWBERX. It does not use information provided in a COMMAREA, but instead uses the EXEC CICS commands to obtain information about the Web client's request and create and send the error response.

The Web error program DFHWBEP, which was available before CICS TS 3.1, is used in all other situations where a Web error program is required. You might have customized the Web error program DFHWBEP in an earlier CICS release. CICS now uses additional status codes, and uses some existing status codes in a wider range of situations. You should be aware of this if you have made modifications to DFHWBEP to customize the responses associated with each status code. The EXEC CICS WEB and DOCUMENT application programming interfaces are not available from DFHWBEP. DFHWBEP uses a COMMAREA-based interface where a complete HTTP response is created as a buffer of data.

In the COMMAREA passed to a Web error program, there is a new input parameter wbep_activity, which specifies the type of processing that was in progress when the error occurred. 0 indicates server processing, and 2 indicates pipeline processing.