|
You can write an analyzer program in C, COBOL, or PL/I.
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".
The full range of functions which an analyzer program can perform is as follows:
| • | Determine whether processing should continue for the request, or whether XCICS 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 XCICS resources are needed to carry out each stage. (The EXEC XCICS 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 request is passed to the converter program in a 32K block of storage indicated by a pointer in the COMMAREA. "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 |
| • | 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 XCICS WEB API commands. |
XCICS supplies the default analyzer program DFHWBAHX, which is described in "XCICS-supplied default analyzer program DFHWBAHX". If this analyzer does not meet your requirements, you might be able to use it as an example.
Input to an analyzer program
Input parameters are passed to the analyzer program in a COMMAREA, giving information about the nature and content of the request, and any input supplied by a URIMAP definition. The analyzer program can choose to accept these values and pass them on as output parameters, or it can dynamically override them based on its analysis of the content of the request.
The input parameters include the following items, or a pointer to them:
| • | An eye-catcher for an analyzer parameter list. |
| • | The dotted decimal IP address of the client and of the server (XCICS as an HTTP server). |
| • | An indicator of whether the request is an HTTP request. |
| • | An indicator of whether a matching URIMAP definition was found for the request. If this indicator is positive, the URIMAP definition might have passed additional input parameters to the analyzer program. |
| • | The host name specified for the request, taken from the Host header or (for an absolute URI) from the request URL. For HTTP/1.1 requests, a host name is required, so this parameter is always passed to the analyzer. For HTTP/1.0 requests, a host name might not be supplied. |
| • | The path component of the URL. |
| • | Any query string that was specified for the request. |
| • | The HTTP headers for the request. |
| • | The request body, or as much of the request body as will fit into a 32K block of storage. |
For HTTP requests received on a connection using SSL client authentication, the following parameter is also passed:
| • | The user ID obtained from the client certificate. |
If a matching URIMAP definition was found for the request and has invoked the analyzer program, the following parameters from the URIMAP definition are passed to the analyzer program, if they were present in the URIMAP definition:
| • | The name of the recommended converter program to process the request before it is passed to an application program (CONVERTER attribute in the URIMAP definition). |
| • | The name of the recommended user-written application program to process the request and provide the response (PROGRAM attribute in the URIMAP definition). |
| • | The transaction ID of the recommended alias transaction to cover the remaining stages of processing (TRANSACTION attribute in the URIMAP definition). |
| • | The recommended user ID that is to be associated with the alias transaction (USERID attribute in the URIMAP definition). This can be overridden if a user ID is supplied by the client. |
The wbra_urimap input parameter can be used to test whether or not a URIMAP definition was used in the processing path for the request.
You can also use the EXEC CICS WEB API commands to examine the HTTP request, if preferred. Using the EXEC CICS WEB commands can increase the accuracy and completeness of your analysis of the request, particularly when examining the HTTP headers, which are subject to wide variation in content and usage. The EXEC CICS WEB commands also simplify the process of locating and extracting query string or formfield information from a request, which can be a key determinant of subsequent processing.
You can use the EXTRACT TCPIP command to obtain the following information about the client request which is being processed:
| • | The Web client's IP address |
| • | The Web client's host name, as known by the DNS server |
| • | The number of the port on which the Web client sent its connection request |
| • | The server's (that is, XCICS as an HTTP server's) IP address |
| • | The type of authentication in use |
| • | The level of SSL support in use |
| • | The TCPIPSERVICE definition associated with the request |
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.
The analyzer program must provide the following output in its COMMAREA:
| • | 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, XCICS returns an error response to the Web client. |
The analyzer program may also provide the following outputs:
| • | 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 XCICS 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 XCICS default user ID is used. |
| • | An eight byte user token, used to share information between the analyzer and converter programs. |
| • | 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. |
|
