Giving web clients access to COMMAREA applications

You can use CICS® web support to enable web clients to interact with CICS applications that use a COMMAREA interface to communicate with other programs. A web-aware application program can link to the application and use its output to provide HTTP responses. Alternatively, a converter program can convert the input from the web client into a suitable COMMAREA and convert the output from the application into an HTTP response.

Before you begin

Configure the base components of CICS web support, as described in Configuring CICS web support components.

About this task

This task involves the following components of CICS web support and includes a number of subtasks.
  • TCPIPSERVICE resource definitions
  • URIMAP resource definitions
  • COMMAREA application programs
  • Either: Web-aware application programs, using the EXEC CICS WEB programming interface, that link to the COMMAREA application programs and use their output
  • Or: Converter programs that can provide suitable COMMAREA input and convert the output from the application programs into an HTTP response
  • Alias transactions to cover the user application programs involved in this process
  • Analyzer program
  • Security facilities
  • Web error programs
Figure 1 shows the architecture elements for this CICS web support task. HTTP request and response processing for CICS as an HTTP server explains how the process elements work together.
Figure 1. HTTP responses from a COMMAREA application
HTTP responses from a COMMAREA application. The elements used in the architecture are described in the text following the figure. The topic linked to before the figure explains how they work together.

Procedure

  1. You can write a web-aware application program that handles the HTTP request and links to the COMMAREA application program. Or you can write a converter program to convert the input from the web client into a suitable COMMAREA and then convert the output from the application into an HTTP response. Converter programs can either use the EXEC CICS WEB API commands to read the web client request and produce the response, or they can work with the request and response in blocks of storage.
    1. If you want to use a web-aware application program, follow the steps in Providing dynamic HTTP responses with web-aware application programs. Code your web-aware application program to link to the COMMAREA application and use its output. A web-aware application program cannot receive information that an analyzer program has created to pass to the next processing stage (in a user token or shared work area). You have to use a converter program. This limitation is not a concern when you are developing a new CICS web support application.
    2. If you want to use a converter program, follow the steps in this task.
  2. Consider security issues for this CICS web support task. CICS can implement HTTP basic authentication for a connection, where the user must supply an ID and password. You can use the user ID to control access to individual resources used for application-generated responses or static responses. If you need to protect information that is passed over the Internet (including the user IDs and passwords that are used for basic authentication), consider using Secure Sockets Layer (SSL). For more information, see Security for CICS web support.
  3. Decide how the analyzer program associated with the TCPIPSERVICE definition is used, and select an appropriate program. Refer to Analyzer programs. You can use URIMAP definitions or analyzer programs to map requests from web clients to appropriate converter programs and user-written application programs. Using URIMAP definitions (without an analyzer program) the listener task can directly attach user transactions for fast arriving HTTP requests. The web attach task is bypassed, and performance enhancement is gained by saving the CPU time needed for processing requests. For more information, see Bypassing the web attach task with the CSOL socket listener task. For non-web-aware applications, even if you have URIMAP definitions, you must use a customized analyzer program in the processing path for the request in the following circumstances:
    1. If the converter program is working with the request and response in blocks of storage, and you require nonstandard code page conversion. Converter programs do not have a mechanism for specifying code page conversion for blocks of storage containing HTTP requests and responses. In the absence of an analyzer program, CICS uses the standard settings described in Writing a converter program to convert the message body supplied in the block of storage on both input and output. If this behavior is not suitable, you either use an analyzer program in the processing path to specify alternative settings, or use the EXEC CICS WEB API commands instead of working with the blocks of storage. See Code page conversion for CICS Web support for more information.
    2. If you need to communicate any information to a converter program in addition to the standard input. A user token is provided, which the analyzer and converter programs can use to exchange either a small amount of information, or the address of a shared work area containing more information.
    3. If you require monitoring or audit actions, which can be carried out by an analyzer program.
    4. If you need to make dynamic changes to elements of the process such as the converter program that is used, the application program that handles the request, or the alias transaction and user ID used for the request.
    If you do not need any of these functions, you can use the CICS-supplied default analyzer program, DFHWBAAX, or the CICS-supplied sample analyzer program, DFHWBADX, to provide basic error handling. DFHWBAAX is suitable where all the requests using this port are handled using URIMAP definitions. DFHWBADX provides basic support for both requests using URIMAP definitions and requests following the same process that CICS web support used before CICS TS 3.1.
  4. Use the information in Converter programs to create a suitable converter program. The converter program is called twice, first for the decode function, which examines the web client request and any additional information supplied by the URIMAP definition or analyzer program, and creates a suitable COMMAREA to pass to the application program. Next, the converter program is called for the encode function, which receives the application program output and creates an HTTP response. If more than one application program is to supply data, the converter program can call the decode function repeatedly. Refer to Calling more than one program.
  5. Decide on the URL that the web client uses for each request, including the scheme, host and path components, and any query string. See The components of a URL. URLs for CICS web support explains the factors and limitations to consider in choosing a URL.
  6. Decide on the port that is used for the requests, referring to Reserving ports for CICS web support. For HTTP, the default port number is 80, and, for HTTPS (with SSL), the default port number is 443. Port numbers that are not the default for a scheme are specified explicitly in the URL of requests. If you prefer, you can allow a request to use any port that is associated with CICS web support.
  7. Select an alias transaction ID for the relevant user application programs. The default alias transaction is CWBA. To create your own alias transaction, see Creating TRANSACTION resource definitions for CICS web support. You can use the URIMAP definition or an analyzer program to specify an alias transaction for each HTTP request. If you are implementing resource level security using the user IDs of web clients, the user IDs are applied to this transaction and need permission to access protected CICS resources and commands that are used by the transaction.
  8. Set up a URIMAP definition to handle each request. Follow the procedures in Creating a URIMAP resource for CICS as an HTTP server. You can pass HTTP requests directly to an analyzer program without using URIMAP definitions, following the same process that CICS web support used before CICS TS 3.1. However, using URIMAP definitions can make it easier to manage HTTP requests. Without URIMAP definitions, if you want to change how CICS responds to a particular HTTP request, you need to change the logic in the analyzer program. With URIMAP definitions, you can perform these changes dynamically as a system management task. Using URIMAP definitions (without an analyzer program) the listener task can directly attach user transactions for fast arriving HTTP requests. The web attach task is bypassed, and performance enhancement is gained by saving the CPU time needed for processing requests. For more information, see Bypassing the web attach task with the CSOL socket listener task.
  9. If you do not yet have a TCPIPSERVICE definition for the port on which the requests are received, follow the procedure in Creating TCPIPSERVICE resource definitions for CICS web support. Use this definition to specify the security measures that you have selected for the port (such as the use of SSL and basic authentication). The name of the relevant TCPIPSERVICE definition is specified in the URIMAP definition for the request. Specifying no TCPIPSERVICE definition means that requests matched by the URIMAP definition can use any port for which a TCPIPSERVICE definition exists.
  10. Check the error handling procedures for this CICS web support task.
    1. Check the behavior of the analyzer program associated with the TCPIPSERVICE definition for the port on which the requests are received. If URIMAP matching fails for a request, the request is passed on to the analyzer program. For more information, see Analyzer programs.
    2. Ensure that the user-replaceable web error programs provide appropriate responses to the web client. Refer to Web error programs.


dfhtl_archcommarea.html | Timestamp icon Last updated: Sunday, 4 June 2017