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.
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
Procedure
- 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.
- 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.
- If you want to use a converter program, follow the steps
in this task.
- 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.
- 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:
- 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.
- 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.
- If you require monitoring or audit actions, which can be carried out by an analyzer
program.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Check the error handling procedures for this CICS web
support task.
- 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.
- Ensure that the user-replaceable web error programs provide appropriate responses to the web
client. Refer to Web error programs.