Start of change

Providing dynamic HTTP responses with Web-aware application programs

You can use Web-aware application programs to provide application-generated responses to HTTP requests from a Web client.

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. Dynamic HTTP responses with Web-aware application programs
Application-generated HTTP responses. The elements used in the architecture are described below 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. Design and code one or more Web-aware application programs to provide a response to each request by the Web client, using the information in Writing Web-aware application programs for CICS as an HTTP server. Web-aware application programs can use EXEC CICS WEB and EXEC CICS DOCUMENT commands to receive and analyze an HTTP request, and to write and send a response to the request. Each program handles a single request and response.
    Note: Web-aware application programs that use the EXEC CICS WEB commands must run in the CICS region where the Web client's request is received. However, they may link to application programs in other CICS regions, for example to perform business logic.
  2. 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
  3. 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.
  4. 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.
  5. 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.
  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. 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. For Web-aware applications, you can choose between the following strategies:
    1. Use the CICS-supplied default analyzer program DFHWBAAX to provide error handling. DFHWBAAX is suitable where all of the requests using this port are handled using URIMAP definitions. DFHWBAAX takes no action if a matching URIMAP definition is found. If no match is found, it gives control to the user-replaceable Web error program DFHWBERX to produce an error response.
    2. Use the CICS-supplied sample analyzer program DFHWBADX to provide basic support for both requests using URIMAP definitions, and requests following the same process that CICS Web support used before CICS TS 3.1. DFHWBADX takes no action if a matching URIMAP definition is found. If no match is found, it analyzes URLs in the format that was required before CICS TS 3.1. If the analysis fails, DFHWBADX gives control to the user-replaceable Web error program DFHWBEP to produce an error response. (If the URLs specified in your URIMAP definitions do not fit the format that was required before CICS TS 3.1, you should customize DFHWBADX or DFHWBEP so that a more meaningful response is provided.)
    3. Use your own analyzer program to provide customized support. This might include:
      • Making dynamic changes to processing for requests using URIMAP definitions.
      • Providing monitoring or audit actions during processing for requests.
      • Supporting requests following the same process that CICS Web support used before CICS TS 3.1.
      • Providing error responses using either or both of the user-replaceable Web error programs, DFHWBEP and DFHWBERX.
      A customized analyzer program can be specified using the ANALYZER(YES) attribute in a URIMAP definition, and is then involved in the processing path for requests. As supplied, DFHWBAAX and DFHWBADX take no action if they are invoked from a URIMAP definition.
  8. Decide how you want code page conversion to take place, for the HTTP requests, and for the responses that the user application programs provide to them. Code page conversion typically consists of converting the Web client's request, made using an ASCII character set, into an EBCDIC code page for use by the application program; and then reversing this process to return the application program's output to the Web client. Code page conversion for CICS Web support explains the processes for code page conversion. You can specify code page conversion settings in the EXEC CICS WEB API commands issued by a Web-aware application program.
  9. 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.
  10. Ensure that the user-replaceable Web error programs which are involved in your architecture provide appropriate responses to the Web client. The Web error programs are used if an error in initial processing, or an abend or failure situation, occurs in the CICS Web support processThey are not used in all error situations. 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