You can create a URIMAP resource that specifies the components
of the URI for an HTTP client request (scheme, host, and path) and
an SSL client certificate to be used with the request, if required.
When
you use a URIMAP resource to open a client HTTP connection,
administrators
can manage any changes to the server's URI, and you can also
specify that the opened connection is pooled after use for reuse by
other applications.
About this task
You can name a URIMAP resource on the
WEB OPEN
command,
to provide a scheme and host name and a default path for the
connection.
You can also name the resource on a
WEB SEND
command,
to provide a path for the relevant request. Alternatively, you can
use the
WEB EXTRACT URIMAP
command to extract information
from the URIMAP resource and use it directly in the application program
that makes the HTTP client request. URIMAP resources can also be
used
with the
INVOKE SERVICE
command to call a service.
By
default, after a
CICS®
application
has finished using its client HTTP connection,
CICS
closes the connection. When you specify
the SOCKETCLOSE attribute in the URIMAP resource, instead of closing
the connection,
CICS
can place
the connection in a pool in a dormant state. The dormant connection
can be reused by the same application or by another application that
connects to the same host and port, to save opening a new
connection.
The application program uses a pooled connection in exactly the same
way as it uses a new connection. For a client HTTP connection to be
eligible for connection pooling, the
CICS
application
program must specify the URIMAP resource on the
INVOKE SERVICE
or
WEB
OPEN
command.
Procedure
- Identify the URL that you plan to use for the HTTP client
request. The URL represents a resource that you plan to
access on a server.
- Identify whether a client certificate might be required
for the request and obtain a suitable certificate label. If
the scheme used for the request is HTTPS, the server might request
an SSL client certificate. In this case,
CICS
supplies the certificate label that is
specified in the URIMAP resource.
- Divide the URL for the request into its scheme, host, and path
components. See
The components of a URL
. Also use a port number if it has been specified
explicitly in the URL. For example, in the URL
http://www.example.com:1030/software/index.html
- The scheme component is
http
- The host component is
www.example.com
- The port number is
1030
- The path component is
/software/index.html
If you want to provide a query string in the URL for the
request, you can specify it on the
WEB SEND command using the QUERY option.
- Create a
URIMAP
resource
with a name and group of your choice:
- Specify the USAGE attribute as CLIENT because
CICS
is the HTTP client.
- Specify the SCHEME attribute as the scheme component
of the URL for the request. Use HTTP or HTTPS. Do not include
the delimiters
://
following the scheme component.
- Specify the HOST attribute as the host component of
the URL for the request.
The host component can be an
explicit IPv4 or IPv6 address, or it can be a character host name. If you want to specify a port number in the URL for the
request
to the server, include it in the HOST attribute, together with the
colon preceding it. You only have to specify the port number if
it
is not the default for the scheme (80 for HTTP without SSL, or 443
for HTTPS, HTTP with SSL).
- Specify the PATH attribute as the path component of
the URL for the request. Do not include a query string
in the path component; you can specify it on the
WEB SEND
command
using the QUERY option. Do not use a wildcard character (an asterisk)
in a URIMAP resource when
CICS
is
the HTTP client. You can either include or omit the forward slash
at the beginning of the path component. If you omit it,
CICS
adds it at run time.
If the
URIMAP resource is referenced on a
WEB OPEN
command,
this path becomes the default path for
WEB SEND
commands
for that connection. If the URIMAP resource is referenced on a WEB
SEND command, the path is used for that
WEB SEND
command,
but note that the host attribute for that URIMAP resource must match
the host specified on the
WEB OPEN
command for
the connection.
- Optional: If SSL is being used, specify
the CERTIFICATE attribute as the label of the certificate that is
to be used as the SSL client certificate for this request.
- Optional: If SSL or TLS is being used, specify
the CIPHERS attribute as the cipher code that is to be used for this
request.
- Optional: If you want connections that were
opened using this URIMAP resource to be pooled for reuse, specify
the SOCKETCLOSE attribute as the length of time for which
CICS
keeps the connection in the
pool after the application program has finished using it.
See
Connection pooling for HTTP client performance
for information about how
CICS
manages pooled connections
and how connection pooling improves application performance.
This example shows the URL
http://www.example.com:1030/software/index.html
specified
as a URIMAP resource:
Urimap: softw
Group: MYGROUP
Description: Client request for software page
Status: Enabled
Usage: Client
Scheme: HTTP
Host: www.example.com:1030
Path: /software/index.html
Socketclose: 001500
Results
You have created a URIMAP resource so that
CICS
can act as an HTTP client and send HTTP
requests. If you have any problems installing the resource, check
that you do not have an enabled URIMAP that points to the same URI.
You cannot have more than one enabled URIMAP resource pointing to
the same URI in a
CICS
region.