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
upper case. 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 first 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.