Start of change

Analyzer programs

Analyzer programs are associated with TCPIPSERVICE definitions. Their primary role is to interpret an HTTP request if a URIMAP definition specifies the use of an analyzer program, or if no URIMAP definition is present.

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

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. The role of analyzer 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.

Relationship between analyzer programs and URIMAP definitions

Before CICS Transaction Server for z/OS®, Version 3 Release 1, all HTTP requests for CICS as an HTTP server were interpreted by an analyzer program. In CICS TS Version 3, URIMAP definitions are the strategic facility to control the processing of HTTP requests. They replace key functions of the analyzer program in matching the URLs of requests to the application program that processes them, and specifying the use of a converter program and an alias transaction.

URIMAP definitions may, however, invoke an analyzer program for selected HTTP requests, to take over some of the processing stages, and to perform other actions such as monitoring or audit actions. The attributes of the URIMAP definition that reproduce analyzer functions, namely CONVERTER (converter program name), TRANSACTION (alias transaction), USERID (user ID for alias transaction), and PROGRAM (name of application program to process request), can be passed to the analyzer program, and the analyzer program can choose to override these.

You can choose to pass an HTTP request directly to an analyzer program without using a URIMAP definition, following the same process that CICS Web support used before CICS Transaction Server for z/OS, Version 3 Release 1. However, without URIMAP definitions, if you want to change the way in which CICS responds to a particular HTTP request, you need to change the logic in the analyzer program. With URIMAP definitions, you can perform these changes dynamically as a system management task. Also note that if you continue to use an analyzer program instead of a URIMAP definition to handle requests, and you need to be compliant with HTTP/1.1 in this respect, you must code your analyzer program to perform URL comparison according to the rules stated in the HTTP/1.1 specification (RFC 2616).

Note: Start of changeAs supplied, the CICS-supplied sample analyzer program DFHWBADX and the CICS-supplied default analyzer program DFHWBAAX do 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).End of change

Use of analyzer programs for error handling

Although an analyzer program is not now required in the processing path for every HTTP request, an analyzer program must still be specified for each TCPIPSERVICE resource definition that is used for CICS Web support.

The name of the analyzer program is specified in the URM attribute of the resource definition. You can specify a different analyzer in each TCPIPSERVICE definition, or you can specify the same analyzer in more than one TCPIPSERVICE definition. If you are invoking an analyzer program from a URIMAP definition, you cannot choose between different analyzer programs; you can only select whether or not to use the analyzer program specified for the TCPIPSERVICE definition.

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 a Web error program, not the analyzer program.)

Because of this, as a minimum, the analyzer program specified for each TCPIPSERVICE definition should include a procedure to handle any HTTP request that it does not recognize, and provide a suitable error response. You may also identify specific requests that should have been handled by a URIMAP definition, and provide a more relevant error response. The output from an analyzer program in an error situation is passed to a Web error program, which you can use to modify the HTTP response. Web error program explains how to tailor these.

The CICS-supplied default analyzer program DFHWBAAX is the default when a TCPIPSERVICE definition specifies PROTOCOL(HTTP). DFHWBAAX provides basic error handling when all requests on the port should be handled by URIMAP definitions. It does not provide support for requests using the URL format that CICS Web support used before CICS TS 3.1. If you need to provide handling in your analyzer program for requests that are not handled by URIMAP definitions, the analyzer program specified on your TCPIPSERVICE definition should be the CICS-supplied sample analyzer program DFHWBADX or your own customized analyzer program.

Use of analyzer programs for some non-Web-aware applications, and for non-HTTP messages

Non-Web-aware applications might function correctly when they are invoked directly from a URIMAP definition. However, because these applications do not use the EXEC CICS WEB API commands, some might be dependent on facilities that can only be provided for them by an analyzer program. The use of an analyzer program in the processing path for an HTTP request is essential in the following circumstances:
  • You are producing a response using a non-Web-aware application and a converter program, and it needs to be flagged 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. (For example, user-written clients could experience problems with new error responses or additional HTTP headers.)
  • You are producing a response using a non-Web-aware application and a converter program, and the request that is passed to the converter program in a COMMAREA requires nonstandard code page conversion. If no analyzer program is used with a non-Web-aware application, and the request headers 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.
    The same settings are used for code page conversion of the response that is produced in a COMMAREA. If these standard settings are not suitable, or if code page conversion is not wanted, an analyzer program must be used to specify alternative settings.
In these situations, a URIMAP definition may be set up for the request, but it must specify the analyzer program.

For non-HTTP requests, which use the user-defined (USER) protocol on the TCPIPSERVICE definition, an analyzer program is always required to process the requests, and URIMAP definitions cannot be used. CICS Web support and non-HTTP requests explains how non-HTTP requests are processed.

Use of analyzer programs for additional processing

In situations where the use of an analyzer program in the processing path is optional, you might choose to use an analyzer program for reasons such as the following:
  • You want to make dynamic changes to elements of the processing path, based on the content of the request. Each URL for a HTTP request is matched by a single URIMAP definition, which defines a single processing path. An analyzer program can interpret the content of the request and change elements such as the application program that handles the request, the involvement of a converter program, or the alias transaction and user ID used for the request.
  • You want to introduce monitoring or audit actions into the process. An analyzer program is an appropriate location in which to do this.
  • You are migrating an existing CICS Web support architecture from CICS TS Version 2, and your existing analyzer program provides additional functions that you want to maintain during request processing, such as passing information to a converter program.
Writing an analyzer program explains the full range of functions that an analyzer program can perform.
End of change