Analyzer programs

Attention: This topic contains Product-sensitive Programming Interface and Associated Guidance Information.
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.

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. Enabling CICS web support 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 this release, URIMAP resources are the strategic method for controlling 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: As 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).

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 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 programs 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, 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 might be needed 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.) 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.
  • You are producing a response using a non-web-aware application and a converter program, and either the copy of the web client's request which is passed to the converter program in a block of storage, or an HTTP response which the converter program produces manually in a block of storage, requires nonstandard code page conversion. A converter program is not able to specify code page conversion settings for HTTP requests or responses that are passed in a block of storage. The standard settings used by CICS for code page conversion if no analyzer program is present in the processing path are described in Writing a converter program. If these standard settings are not suitable, or if code page conversion is not wanted, you can use an analyzer program in the processing path to specify alternative code page conversion settings. As an alternative to using an analyzer program, you could use the EXEC CICS WEB API commands in the converter program to examine the web client's request or to produce the response, instead of using the block of storage. In this case, code page conversion can be specified as usual on the EXEC CICS WEB API commands.
If you require an analyzer program to handle one of 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 upgrading 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.

Subtopics


dfhtl1q.html | Timestamp icon Last updated: Thursday, 27 June 2019