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.

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 input parameters include the following items, or a pointer to them:
  • An eye-catcher for an analyzer parameter list.
  • The colon hexadecimal or dotted decimal IP address of the client and of the server (CICS® 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 HTTP version.
  • The request method.
  • 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.

    If the request has been sent using chunked transfer-coding, any trailing headers are not passed to the analyzer program with the main request headers.

  • The request body, or as much of the request body as fits into a 32 KB block of storage. This request body is a pointer to the separate block of storage containing the request.
For HTTP requests received on a connection using TLS client authentication, the following parameter is also passed:
  • The user ID obtained from the client certificate.
If a matching URIMAP definition is found for the request and it invoked the analyzer program, the following parameters from the URIMAP definition are passed to the analyzer program, if they are 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 user ID 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.

If you are using an analyzer program instead of a URIMAP definition to handle requests, and you need to comply with HTTP/1.1 in this respect, you must code your analyzer program to perform URL comparison according to the rules stated in the HTTP/1.1 specification. Under these rules, scheme names and host names are compared case-insensitively, but paths are compared case-sensitively. All components are unescaped before comparison. When CICS compares URLs to URIMAP definitions, it follows these rules.

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 determine the subsequent processing.

You can use the EXTRACT TCPIP command to obtain the following information about the client request that is being processed:
  • The IP address of the web client
  • The host name of the web client, as known by the DNS server
  • The number of the port on which the web client sent its connection request
  • The IP address of the server; that is, CICS as an HTTP server
  • The type of authentication in use
  • The level of SSL support in use
  • The TCPIPSERVICE resource definition associated with the request