Writing an analyzer program
You can write an analyzer program in Assembler, C, COBOL, or PL/I.
About this task
Input and output parameters for an analyzer program are passed in a COMMAREA. Language-dependent header files, include files, and copy books which map the COMMAREA are described in Reference information for analyzer programs.
- Determine whether processing should continue for the request, or whether CICS® should return an error response to the web client.
- Analyze the content of the request, and any parameters that have been passed to the converter program from a URIMAP definition, to determine which of the subsequent processing stages are required, and which CICS resources are needed to carry out each stage. (The EXEC CICS WEB API commands may be used during this analysis.)
- Specify the name of a converter program to process the request before it is passed to an application program. Converter programs are normally used with application programs that are not web-aware. A user token is provided for the analyzer program to communicate with the converter program, if required. The web client's request is passed to the converter program in a 32K block of storage indicated by a pointer in the parameter list. Converter programs explains the functions of a converter program.
- Specify the name of the user-written application program that is to process the request and provide the response.
- Specify the transaction ID of the alias transaction that handles the remaining stages of processing.
- Specify a user ID that is to be associated with the alias transaction.
- Specify or suppress code page conversion for the request passed to the converter program in the block of storage, and any response that the converter program constructs manually in a block of storage. This does not affect converter programs or user-written applications which use the EXEC CICS WEB API commands to view the HTTP request and produce the response; they request code page conversion directly from CICS. Code page conversion for CICS Web support explains the code page conversion process.
- Specify the flag wbra_commarea, provided for upgrade purposes, that indicates where a non-web-aware application requires pre-CICS TS Version 3 compatibility processing. This does not affect converter programs or user-written applications which use the EXEC CICS WEB API commands to view the HTTP request and produce the response.
- Modify the request body. Any changes made are visible in the data passed to the converter program in the block of storage, but not to the EXEC CICS WEB API commands.
CICS supplies the default analyzer program DFHWBAAX, which is described in CICS-supplied default analyzer program DFHWBAAX, and the sample analyzer program DFHWBADX, which is described in CICS-supplied sample analyzer program DFHWBADX. If these analyzers do not meet your requirements, you need to write your own. You might be able to use DFHWBADX as an example.
All the user-replaceable programs must be local to the system in which CICS web support is operating. If you do not use autoinstall for programs, you must define and install program definitions for all user-replaceable programs used by CICS web support, including the analyzer and converter programs. If you use autoinstall for programs, you must ensure that user-replaceable programs are installed with the correct attributes. Note that your analyzer programs must be defined with EXECKEY(CICS).
For more information about writing user-replaceable programs, see Customizing with user-replaceable programs.