CICS-supplied sample analyzer program DFHWBADX

CICS® supplies a working sample analyzer program, DFHWBADX. If you need to provide request handling through your analyzer program, as well as or instead of through URIMAP definitions, you can use DFHWBADX as a starting point for writing your own analyzer program.

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

CICS supplies the source code in several languages:

DFHWBADX (Assembler)
DFHWBAHX (C)
DFHWBALX (PL/I)
DFHWBAOX (COBOL)

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, and if the result is positive, returns without performing any analysis on the request URL. If you write your own analyzer program and want it to interact with a URIMAP definition, do not copy this aspect of DFHWBADX's processing. You may want to test the wbra_urimap input parameter in order to modify your analyzer program's processing in other ways. For example, you could test the parameter to decide whether to perform analysis based on the input parameters from the URIMAP definition, or to perform analysis directly on the request URL.

How DFHWBADX interprets a request URL

DFHWBADX interprets HTTP requests in which the path component of the URL has the following syntax:

Figure 1. Syntax of path component interpreted by DFHWBADX


>>-/--converter--/--alias--/--program--+------------+----------->
                                       '-/--ignored-'   

>--+----------+------------------------------------------------><
   '-?--token-'

All fields processed by the analyzer program are translated to uppercase. After translation:

converter: Specifies the name of the converter program to be used for the request. It can be up to eight characters in length.
As a special case, the four character value 'CICS' denotes that no converter program is used. See Converter programs for information on how to use converter programs with URIMAP definitions.
alias: Specifies the transaction ID of the alias transaction for subsequent request processing. It can be up to four characters in length.
program: Specifies the name of the CICS application program that is to be used to service the request. It can be up to eight characters in length.
ignored: This part of the path is ignored by DFHWBADX (but may be used by the converter program or the application program).
token: The initial eight bytes specify the user token that is passed to the converter program. Data following the first eight bytes of the token is ignored by DFHWBADX (but may be used by the converter program or the application program).

In the example path /cics/cwba/dfh$wb1a:

No converter program is used.
The alias transaction is CWBA.
The CICS application program is DFH$WB1A.

In addition to the outputs derived from the original HTTP request, DFHWBADX sets the following outputs:

The code page conversion template is DFHWBUD. This template is defined in sample conversion table DFHCNVW$, and converts data between the ASCII Latin-1 character set (code page ISO 8859–1) and the EBCDIC Latin character set (code page 037). The sample conversion table can be used without any configuration, but note that the output parameters wbra_characterset and wbra_hostcodepage can be used in place of the wbra_dfhcnv_key output parameter to provide greater control and avoid the use of a conversion table.
DFHWBADX passes the request in escaped form, and sets WBRA_UNESCAPE_NOT_REQUIRED.

Responses from DFHWBADX

The meanings of the responses produced by DFHWBADX are as follows:

URP_OK

The analyzer found that the request conformed to the default HTTP request format, and generated the appropriate outputs for the alias.

URP_EXCEPTION

The analyzer found that the request did not conform to the default format. A reason code is supplied as follows:

1: The length of the resource was less than 6. (With the URL format recognized by DFHWBADX, the shortest possible resource specification is /A/B/C, asking for program C to be run under transaction B with converter A.) This response and reason are the ones used when the incoming request is not an HTTP request.
2: The resource specification did not begin with a /.
3: The resource specification contained one /, but fewer than three of them.
4: The length of the converter name in the resource specification was 0 or more than 8.
5: The length of the transaction name in the resource specification was 0 or more than 4.
6: The length of the CICS application program name in the resource specification was 0 or more than 8.

The response and reason codes are displayed in message DFHWB0723. An error response with a 400 (Bad Request) status code is returned to the web client. This can be modified with the user-replaceable web error program DFHWBEP.

URP_INVALID

The eye-catcher was invalid. This indicates an internal error.

dfhtl1s.html | Timestamp icon

Last updated: Thursday, 27 June 2019