You can use a CICS® document template or a z/OS® UNIX System
Services HFS file to provide a static response to an HTTP request
from a Web client.
The following task-specific components of CICS Web
support are used for this task:
- TCPIPSERVICE resource definitions
- URIMAP resource definitions
- Files in HFS
- CICS document template support
- Security facilities
- Web error programs
Figure 1 shows
the architecture elements for this CICS Web
support task.
Figure 1. Static
HTTP responses
HTTP request and response processing for CICS as an HTTP server explains
how the process elements work together.
- 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.
- If you want to use a z/OS UNIX System
Services HFS file to provide a response, create the file and place
it in an appropriate location of your choice in the HFS file system. When this response is identified by a URIMAP definition that
matches the Web client's request, CICS retrieves
the file and carries out appropriate code page conversion.
- Do not include any HTTP headers or status line information
in the HFS file. CICS generates the required information
when the response is sent. The HFS file only provides the body of
the response.
- The location of the file is significant if you want
to use path matching, as described later in this topic. If you do
not want to use path matching, the location of the file does not need
to have any relationship to the URL of the request.
- The CICS region must have permissions
to access z/OS UNIX, and it must have permission
to access the HFS directory containing the file, and the file itself. Java™ Applications
in CICS explains how to grant these permissions.
- If you want to use a CICS document
template to provide the response, create the document template, following
the instructions in the CICS Application Programming Guide. The document template is defined using a DOCTEMPLATE resource
definition. The document template can be held in a partitioned data
set, a CICS program, a file, a temporary storage queue,
a transient data queue, an exit program or a z/OS UNIX System
Services HFS file. When this response is identified by
a URIMAP definition that matches the Web client's request, CICS creates
a document using the template, retrieves the document, and carries
out appropriate code page conversion.
- Do not include any HTTP headers or status line information
in the document template. CICS generates
the required information when the response is sent. The document template
only provides the body of the response.
- A query string that consists of name and value pairs
can be used as a symbol list and substituted into a document template. (The query string cannot be used in this way if it has already
been used for URIMAP matching, as part of the PATH attribute in the
URIMAP definition.) The recommended way to get the client
to send a query string of the expected format in the URL, is to send
an HTML form with the GET method for the user to fill in. Any of the names in the query string can be coded in the
document template as a symbol, and when the template is used, CICS substitutes
each symbol for the value specified in the query string. For example,
if you have obtained a query string that includes a name and value
pair username=Peter, you can use this in your document
template by coding username as a symbol:
Welcome to the finance system, &username;.
The resulting static response delivered to the user reads Welcome to the finance system, Peter.
Note: Symbols in document templates are case-sensitive.
Specify the name using the same case as is present in the original
query string.
Any name and value pairs that
do not correspond to symbols in the document template are ignored.
- Identify the media type (type of data content) that is
provided by the HFS file or CICS document template. (See IANA media types and character sets for more information about
media types.) Note that when you use a URIMAP definition
to send a static response, the use of quality factors (the "q" parameter)
is not supported. Quality factors can be used to choose among a client's
list of acceptable media types or character sets, as specified in
Accept headers. If you want to carry out this type of analysis, an
application-generated response can be used instead.
- Identify the information that CICS requires
for code page conversion of the static response. Code page conversion only takes place where a
text media type is specified. Code page conversion for CICS Web support explains
the processes for code page conversion.
- Identify the character set into which CICS should
convert the static response before sending it to the Web client. The IANA character sets supported by CICS for
code page conversion are listed in HTML coded character sets.
- Identify the IBM code page (EBCDIC) in which
the document template or HFS file providing the response body is encoded.
For a static response, this information is specified in the
URIMAP definition for the request.
- 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 whether you want to use path matching
in the URIMAP definition. If so, plan your request URLs, and arrange
the names of your CICS document templates or the
locations of your HFS files to support this. In path matching,
a wildcard character is used in the path component of the URIMAP definition,
and also in the name of the CICS document template or HFS file
that is specified by the URIMAP definition. The portion of the path
that is covered by the wildcard character is used to select the document
template or HFS file to provide the response.
- For CICS document templates, the portion
of the path that is covered by the wildcard character is substituted
as the last part of the template name. You can create a collection
of document templates whose names begin in the same way, and access
them using request URLs whose paths begin in the same way, through
a single URIMAP definition.
- For HFS files, the portion of the path that is covered
by the wildcard character is substituted as the last part of the HFS
file name. You can store a number of HFS files in the same directory,
and access them using request URLs whose paths begin in the same way,
through a single URIMAP definition. Bear in mind that because
a URIMAP definition must specify a type of data content (the MEDIATYPE
attribute), a single URIMAP definition can only handle a group of
HFS files that produce the same type of data content.
- 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.
- 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.
- 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 a static response to an HTTP request for CICS as an HTTP server. The URIMAP definition can identify either a HFS file or a document
template.
- 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. If the port is used only for static responses,
the CICS-supplied default analyzer program DFHWBAAX provides suitable
error handling. Otherwise, the choice of analyzer program is likely
to depend on the requirements of user application programs, and you
might need to customize it to provide suitable error handling for
static responses. 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.