Start of change

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. You can write a Web-aware application program that links to the application and uses its output to provide HTTP responses. Alternatively, you can use a converter program to convert the input from the Web client into a suitable COMMAREA, and convert the output from the application into HTML to provide the response.

The base components of CICS Web support must be configured before you start, as described in Configuring CICS Web support base components.
The following task-specific components of CICS Web support are used for this task:
Figure 1 shows the architecture elements for this CICS Web support task.
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.

HTTP request and response processing for CICS as an HTTP server explains how the process elements work together.

  1. Decide whether you want to write a Web-aware application program that handles the HTTP request and links to the COMMAREA application program; or whether you want to write a converter program to convert the input from the Web client into a suitable COMMAREA, and convert the output from the application into HTML to provide the response.
    Note: For COMMAREA applications that use a converter program, CICS cannot provide the fullest possible assistance with structuring responses and with HTTP protocol compliance. To take advantage of all the available CICS Web support facilities, it is recommended that you use Web-aware applications to handle requests where possible.
    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. The only task that cannot be performed by a Web-aware application program, but can be performed by a converter program, is receiving information that an analyzer program has created to pass to the next processing stage (in a user token or shared work area). This is unlikely to be a consideration when you are developing a new CICS Web support application.
    2. If you want to use a converter program, follow the steps in this topic.
  2. Decide how the analyzer program associated with the TCPIPSERVICE definition should be used, and select an appropriate program. Analyzer programs has more information about what you can do using an analyzer program. URIMAP definitions or analyzer programs can be used to map requests from Web clients to appropriate converter programs and user-written application programs. For non-Web-aware applications, even if you have URIMAP definitions, you need to use a customized analyzer program in the processing path for the request in the following circumstances:
    1. If you require nonstandard code page conversion. Non-Web-aware application programs and converter programs do not have a mechanism for specifying code page conversion for HTTP requests and responses. In the absence of an analyzer program, CICS converts the message body supplied in the COMMAREA on both input and output, using the default code page for the CICS system (specified by the LOCALCCSID system initialization parameter), and any supported character set that is specified in the Web client's request (or the ISO-8859-1 character set). If this behavior is not suitable, an analyzer program must be used in the processing path to specify alternative settings.Code page conversion for CICS Web support has more information about the processes for code page conversion.
    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 of 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.
  3. Use the information in Converter programs to create a suitable converter program. CICS passes the Web client's request to the converter program in a 32K block of storage. (If the request does not fit, it is truncated.) The converter program is called twice, first for the decode function, which receives the request and passes it to the application program, and next for the encode function, which receives the application's output and creates an HTTP response. The tasks carried out by a converter program are:
    Decode function
    • Receive the HTTP request in a storage area, along with any additional information supplied by the URIMAP definition or analyzer program in a COMMAREA.
    • Process the HTTP request and convert relevant elements into suitable COMMAREA input for the application program (in the same storage area or a new one).
    Encode function
    • Receive the output from the application program.
    • If more than one application program is to supply data, set the loop response, to call the decode function again. Calling more than one CICS application program explains how this is achieved.
    • Construct the HTTP response in a COMMAREA.
    • Pass the HTTP response to CICS for sending to the Web client.
  4. Decide on the URL that the Web client will use for each request, including the scheme, host and path components, and any query string. The components of a URL explains each of these components and how they are delimited. URLs for CICS Web support explains the factors and limitations to consider in choosing a URL for CICS Web support.
  5. Decide on the port that will be used for the requests. Reserving ports for CICS Web support has more information about ports that can be used by 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 need to be 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.
  6. Select an alias transaction ID for the user application programs that are involved with this task. The default alias transaction is CWBA. You can create your own alias transaction following the instructions in 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.
  7. Consider security issues for this CICS Web support task. Start of changeFor application-generated responses, CICS can implement HTTP basic authentication for a connection, where the user must supply an ID and password. (Basic authentication does not operate for items delivered as a static response.) You can use the user ID to control access to individual resources. If you need to protect information passed over the Internet (including the user IDs and passwords used for basic authentication), consider using Secure Sockets Layer (SSL). For more information, see Security for CICS Web support.End of change
  8. Set up a URIMAP definition to handle each request. Follow the procedures in Starting a URIMAP resource definition for any requests for CICS as an HTTP server and Completing a URIMAP definition for an application response to an HTTP request for CICS as an HTTP server. It is possible to 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 the way in which 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.
  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 to set up a TCPIPSERVICE definition. 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. Analyzer programs has more information about what you can do using an analyzer program.
    2. Ensure that the user-replaceable Web error programs which are involved in your architecture provide appropriate responses to the Web client. Web error program explains the situations in which DFHWBEP and DFHWBERX are used, and tells you how to customize the responses that they provide.
End of change