Creating a URIMAP resource for CICS as an HTTP client

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. If you do not specify the name of the URIMAP on the INVOKE SERVICE command, CICS® will search, at run time, for a URIMAP that has USAGE(CLIENT) and a matching host and path. This mechanism allows the system programmer to install a URIMAP to control attributes such as CERTIFICATE, CIPHERS, and SOCKETCLOSE without requiring application changes.

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.

Outbound HTTP connection pooling is controlled entirely by the SOCKETCLOSE attribute in the client URIMAP.

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
1. The scheme component is http
2. The host component is www.example.com
3. The port number is 1030
4. 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:
1. Specify the USAGE attribute as CLIENT because CICS is the HTTP client.
2. 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.
3. 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).
4. 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.
5. 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.
6. Optional: If SSL or TLS is being used, specify the CIPHERS attribute as the cipher code that is to be used for this request.
7. 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.