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 following task-specific components of CICS Web support are used for this task:
- 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 HTML
- 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.
Figure 1. HTTP responses from a COMMAREA application
HTTP request and response processing for CICS as an HTTP server explains
how the process elements work together.
- 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.
- 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.
- If you want to use a converter program, follow the steps in
this topic.
- 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:
- 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.
- 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
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.
- 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.
- 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.
- 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.
- 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.
- Consider security issues for this CICS Web support
task.
For
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.
- 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.
- 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.
- 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. Analyzer programs has more information about what you can do using an
analyzer program.
- 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.