URIMAP resource definitions are used to define how HTTP requests
are processed. For any HTTP request for CICS® as an HTTP server, start the URIMAP
definition by specifying the components of the expected URL for the Web client's
request (scheme, host and path) and other basic information.
The CICS Resource Definition Guide has information
about the different methods of resource definition, and full reference information
about all the URIMAP resource definition attributes that you will use during
this process.
- Identify the URL that you plan to receive
as an HTTP request from a Web client. The URL represents a resource
that you plan to make available to a Web client through CICS.
- Divide the URL for the HTTP request into
its scheme, host and path components. The components of a URL explains each of these components and how they are
delimited. For example, in the URL http://www.research.ibm.com/software/htp/cics/index.html:
- The scheme component is http
- The host component is www.research.ibm.com
- The path component is /software/htp/cics/index.html
If you want the URIMAP definition to match more than
one path, you can use an asterisk as a wildcard character at the end of the
path. For example, specifying the path /software/htp/cics/* would
make the URIMAP definition match all requests whose path begins with the string /software/htp/cics/.
If more than one wildcarded URIMAP definition matches an HTTP request, the
most specific match is taken.
- If a query component is present in the URL,
and you want to match the URIMAP definition to that specific query alone,
you can include this as part of the PATH specification. A query
string can be used after a path that includes an asterisk as a wildcard, but
the query string cannot itself include an asterisk as a wildcard. The complete
and exact query string must be specified. For a static response
with a CICS document
template, a query string can either be used to select the URIMAP definition,
or it can be substituted into the document template, but not both. If you do not include a query string in the URIMAP definition, matching
takes place only on the path, and any query string that is present in the
request is automatically ignored for matching purposes.
- Begin a URIMAP definition with a name and
group of your choice, using one of the methods listed in the CICS Resource Definition Guide.
- Use the STATUS attribute to specify whether
the URIMAP definition should be installed in an enabled or disabled state.
- Specify a USAGE attribute of SERVER (CICS as
an HTTP server).
- Specify the SCHEME attribute as the scheme
component of the URL for the HTTP request. HTTP (without SSL) or HTTPS (with
SSL) can be used. Do not include the delimiters :// following
the scheme component. A URIMAP specifying the HTTP scheme accepts
Web client requests made using either the HTTP scheme, or the more secure
HTTPS scheme. A URIMAP specifying the HTTPS scheme accepts only Web client
requests made using the HTTPS scheme.
- Specify the TCPIPSERVICE attribute as the
name of the TCPIPSERVICE definition that defines the inbound port to which
this URIMAP definition relates. If this attribute is not specified,
the URIMAP definition applies to a matching HTTP request on any inbound port.
Note: When a URIMAP definition with HTTPS (HTTP with SSL) as the scheme
matches a request that a Web client is making, CICS checks that the inbound port used
by the request is using SSL. If SSL is not specified for the port, the request
is rejected with a 403 (Forbidden) status code. When the URIMAP definition
applies to all inbound ports, this check ensures that a Web client cannot
use an unsecured port to access a secured resource. No check is carried out
for a URIMAP definition that specifies HTTP as the scheme, so Web clients
can use either unsecured or secured (SSL) ports to access these resources.
- If you need to distinguish between URLs containing
different host names, specify the HOST attribute as the host component of
the URL for the HTTP request. Do not include a port number. An IPv4 address can be used as a host name, but IPv6 addresses are not
supported. If you specify a single asterisk as the HOST attribute,
the URIMAP definition matches any host name on incoming URLs. Use this option
if you are not using multiple host names, or if you do not want to distinguish
them.
- Specify the PATH attribute as the path component
of the URL for the HTTP request, including an asterisk as a wildcard character
if required. You can either include or omit the delimiter / (forward
slash) at the beginning of the path component; if you omit it, CICS automatically
provides it. If a query component is present, and you want to
apply the URIMAP definition to that specific query alone, include this as
part of the path component (including the question mark at the beginning of
the string).
Note: Specifying the PATH attribute as /* makes the URIMAP definition
match all requests directed to the host named in the HOST attribute, unless
more specific URIMAP definitions are also installed, in which case the most
specific match is taken.
- Now complete your definition:
- For an application-generated response, follow the instructions
in Completing a URIMAP definition for an application response to an HTTP request for CICS as an HTTP server.
- For a static response, follow the instructions in Completing a URIMAP definition for a static response to an HTTP request for CICS as an HTTP server.