Output from an analyzer program
An analyzer program provides output in a COMMAREA. The output includes a response code, and a range of optional output parameters that can be used to specify further processing stages and to share information with a converter program.
Attention: This topic contains Product-sensitive
Programming Interface and Associated Guidance Information.
Parameters for analyzer programs has a listing and technical descriptions of all the parameters in the COMMAREA.
The analyzer program must provide the following output in its COMMAREA:
- A response code.
- If your analyzer program returns a response code of URP_OK, processing continues with the next step.
- If your analyzer program returns any other value, CICS® returns an error response to the web client. The response can be modified with a user-replaceable web error program. CICS web support default status codes and error responses tells you how the return codes from the analyzer map to the status codes that CICS returns to the web client.
- The name of a converter program that is to be used to process the request
before it is passed to a user-written application program.
- If a converter program name was input from a URIMAP definition, you can accept or override this.
- If the analyzer indicates that a converter program is not required, the first 32K bytes of the request is passed to the user-written application program in a block of storage. A web-aware application can ignore this and use the EXEC CICS WEB API commands to read the request.
- The name of an application program that is to process the request and
provide the response.
- If a program name was input from a URIMAP definition, you can accept or override this.
- If you are using a converter program, the converter program can specify or override the program name. A converter can be used in this way to involve more than one program in processing the request.
- The transaction ID of the alias transaction that is to cover the remaining stages of processing. If a transaction ID was input from a URIMAP definition, you can accept or override this.
- The user ID that is to be associated with the alias transaction. If a
user ID was input from a URIMAP definition, you can accept or override this.
This is how CICS determines
the user ID if you do not specify one:
- If a user ID was input from a URIMAP definition, that is used.
- If the HTTP request uses SSL with client authentication, the user ID is obtained from the client certificate.
- In other cases, the CICS default user ID is used.
- Parameters relating to code page conversion of the 32K block of storage
containing the request, and to code page conversion of the response body,
if the converter program produces it manually in a block of storage. Note: 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.You can specify the parameters for conversion of the block of storage containing the request in one of two ways:
- As a pair of parameters specifying the character set used by the web client (wbra_characterset), and the host code page suitable for the application program (wbra_hostcodepage). Specifying the parameters in this way means that an entry in the code page conversion table (DFHCNV) is not required.
- As a key for an entry in the DFHCNV code page conversion table (wbra_dfhcnv_key). This is not recommended, except for upgrade purposes.
- The flag that indicates where a non-web-aware application that uses a
converter program requires pre-CICS TS Version 3 compatibility processing
(wbra_commarea). This flag is provided for upgrade purposes.
It can be used only by applications that do not use the EXEC CICS WEB
API commands (that is, they produce the response manually in a block
of storage), in the specific circumstance where the web client needs
a response that is identical with the response it would have received before CICS TS
Version 3. Setting this flag means that:
- CICS does not add any of the response headers that are normally inserted for HTTP/1.1 messages. Only the headers that were sent to clients before CICS Transaction Server for z/OS®, Version 3 Release 1 are used.
- If error processing is required, CICS sends an error response that is suitable for, and labeled as, an HTTP/1.0 response, regardless of the HTTP version of the web client. CICS would normally reply to a HTTP/1.1 client with an HTTP/1.1 error response, but this might mislead the client into thinking that the application would normally send an HTTP/1.1 response.
- An eight byte user token, used to share information between the analyzer and converter programs. Sharing data between analyzer and converter programs explains how this works.
- A modified value for the request body length.
The analyzer can modify the contents of the request:
- The modified data can be shorter than, or of the same length as the original data. The request body cannot be lengthened.
- Any changes made are visible in the data passed to the converter program, but not to the EXEC CICS WEB API commands.