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.

By default, after a CICS® application finishes by 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 the same way as it uses a new connection.

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

When you are using INVOKE SERVICE, the CICS PIPELINE code either uses a named URIMAP supplied on the command or it attempts to locate a matching client URIMAP based on the host and path. If a matching URIMAP is found, then it is passed to DFHWBCL OPEN_SESSION. Outbound connection pooling is then in use, depending on the URIMAP definition.

Note: If the URIMAP is still installed and has a non-zero SOCKETCLOSE value, then outbound connection pooling is still taking place.

The PIPELINE behavior is slightly different from using WEB OPEN and WEB CONVERSE. The WEB OPEN command just passes the URIMAP to DFHWBCL if specified by the application on the command. The initial reason for this is it is the only way to set a client certificate or set of ciphers to use for outbound SSL connections in the PIPELINE. However, it also allows the system programmer to set up use of connection pooling without requiring any application changes.

Procedure

  1. 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.
  2. 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.
  3. Divide the URL for the request into its scheme, host, and path components.
    See The components of a URL. Also, use a port number that is 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 by using the QUERY option.
  4. 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 must 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 by 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 that is 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 by 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 finishes using it.
      For more information, see Connection pooling for HTTP client performance 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 created a URIMAP resource so that CICS can act as an HTTP client and send HTTP requests. If you have any problems when 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 that is pointing to the same URI in a CICS region.