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