HTTP requests for CICS® as an HTTP server are initiated by a Web client
that makes a request to CICS. CICS provides the Web client with responses to the requests
it makes. The responses can be created from a static document identified by
a URIMAP resource definition, or they can be created dynamically by a user
application program.
Figure 1 shows
the processing that is carried out by CICS Web support to receive a request from
a Web client and provide a response.Figure 1. Processing for CICS as an HTTP server
Processing for CICS as an HTTP server takes place as follows:
- CICS receives
a TCP/IP connection request. The CICS Sockets domain uses the TCPIPSERVICE
resource definition for the port to determine that the request should be processed
by CICS Web
support. The TCPIPSERVICE definition specifies security
attributes to be applied to the request, specifies the timeout setting for
receiving the request message, and limits the maximum amount of data that
can be received for a single request.
- CICS matches
the URL for the request to a URIMAP definition, if available. CICS tries
to match the URL specified in the HTTP request to any URIMAP resource definitions
that are related to the TCPIPSERVICE definition and apply to CICS as an HTTP
server. If a successful match is made, the URIMAP definition tells CICS how
to process the request. If no match is found, CICS continues
with the default process, which begins at processing stage 5 with the analyzer
program.
- If the URIMAP definition specifies redirection, CICS redirects the Web client to the specified
URL. CICS composes
the redirection message and transmits it to the Web client. This
completes the processing for that HTTP request.
- If the URIMAP definition specifies a static response, CICS forms and
supplies the response. CICS uses a document template or a z/OS® UNIX System Services
HFS file, together with appropriate HTTP headers, to form an HTTP response.
The response undergoes appropriate code page conversion, and CICS then transmits
the response to the Web client. This completes the
processing for that HTTP request.
- An analyzer program may be run, if the URIMAP definition
specifies its use, or if no matching URIMAP definition is found. The analyzer
program can interpret the request dynamically, or it can be used for monitoring
or audit purposes.
The analyzer program for the TCPIPSERVICE
definition must be used in the request processing path if no URIMAP definition
has been set up for the request. It might also be needed if you are using
a non-Web-aware application program that has special requirements, for code
page conversion or for pre-CICS TS Version 3 compatibility processing. (Analyzer programs explains these situations.) Otherwise,
the use of an analyzer program is optional, but note that the analyzer program
is called to process the request if the URIMAP definition is not found.
If an analyzer program is being used, the HTTP request
and the HTTP headers are passed to the analyzer program. The analyzer program
can interpret the request to determine:
- Which CICS resources
are to be used to service the request.
- Which user ID is to be associated with the request.
- Which of the remaining processing stages are required.
- A converter program may be used to decode the request
and construct input to the application program. Web-aware application
programs should accept an HTTP request without any decoding. However, if you
want to service an HTTP request using a non-Web aware application program
that requires COMMAREA input, you can use a converter program to decode the
request and construct input that fits the requirements of your application
program. A converter program can be specified using a URIMAP definition, or
it can be selected by an analyzer program.
- An application program is executed to service the request. You
can specify the application program using a URIMAP definition, or using an
analyzer program. A Web-aware application program, using the EXEC
CICS WEB and EXEC CICS DOCUMENT application programming
interfaces, can be used to handle the request and construct a response. A
non-Web-aware application program can be enabled for the Web using either
a converter program (which translates the Web client's request into acceptable
input, and composes an HTTP response based on the program's output), or a
Web-aware application program that calls the non-Web aware program and uses
its output.
The application program runs under an alias
transaction.
The application program can perform
the following tasks:
- If the application program is Web-aware, it can examine the HTTP headers
on the request, extract information (such as a query string) from the request
line, receive the body of the request into a buffer for processing, select
a status code and text for the status line of the response, and write HTTP
headers for the response. EXEC CICS WEB API commands such
as WEB SEND and WEB WRITE HTTPHEADER are used to construct the response.
- Whether or not the application is Web-aware, it can produce output that
forms the body of the response. Web-aware application programs can produce
an entity body formed from a CICS document template or from a buffer of data. Application
programs that are not Web-aware can produce output that can be converted by
a Web-aware application program or a converter program into an entity body.
- A converter program may be used to encode the output
from the application program and construct an HTTP response. If the application
program is not Web-aware and its output is not in the correct form to send
to a Web client, you can use a converter program to produce an appropriate
HTTP response including a status line and HTTP headers. The converter program
can also perform other types of processing on the output, if desired.
The
converter program can specify that processing stages 6 (decoding or other
processing using converter program), 7 (application program) and 8 (encoding
or other processing using converter program) should be repeated. Because the
converter program can change the name of the application program, you can
use this facility to allow more than one application program to work on the
same request in sequence, and provide a single response.
- If a request error or an abend occurs in the CICS Web
support process, an error response is sent to the Web client, which can be
customized using the user-replaceable Web error programs. DFHWBEP or DFHWBERX
receives information about the error situation, and the default HTTP response
(including status code and status text) that CICS plans to send to the Web client. The
user-replaceable programs can customize the response or build a new one, and
return it to CICS for
sending.
The Web error programs are not used in all error situations. They
are used when problems occur in initial processing of requests, and for abends
or failures in subsequent processing. They are not used for situations where
processing (such as processing by a user-written application program) completes
correctly and an error or redirection response is the designed outcome.
- CICS generates
some required HTTP headers and adds them to the message. Appropriate headers
are generated depending on the HTTP version for the response. If
the response is HTTP/1.1, CICS adds headers that are required for HTTP/1.1 messages.
If the response is HTTP/1.0, CICS adds the Connection: Keep-Alive header if the client
has requested a persistent connection, and a small number of other headers. The
values for some of these headers are generated directly by CICS (such as
the Date header), and the values of others are based on information provided
by a Web-aware application program (using the WEB SEND command) or by a URIMAP
definition. The headers can be added both to output from a Web-aware application,
and to output from a converter program.
- CICS transmits
the complete HTTP response to the Web client. If the Web client supports
persistent connections, CICS keeps the connection open for further possible
HTTP requests, until the user application or Web client requests closure or
the timeout period is reached.
During this process, code page conversion is usually needed when messages
enter and leave the CICS environment, so that CICS Web support processing and user-written
applications (which typically use an EBCDIC encoding) can communicate with
Web clients (which typically use an ASCII encoding). Code page conversion for CICS Web support explains when and how this
takes place. The type of code page conversion that is required can be specified
using options on the WEB SEND or WEB RECEIVE commands.