Start of change

Starting a URIMAP resource definition for any requests for CICS as an HTTP server

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.

If you have not already planned how to provide a response to the HTTP request for CICS as an HTTP server, Providing dynamic HTTP responses with Web-aware application programs and Providing static HTTP responses with a CICS document template or HFS file tell you how to do this.
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.
  1. 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.
  2. 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.
  3. 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.
  4. Begin a URIMAP definition with a name and group of your choice, using one of the methods listed in the CICS Resource Definition Guide.
  5. Use the STATUS attribute to specify whether the URIMAP definition should be installed in an enabled or disabled state.
  6. Specify a USAGE attribute of SERVER (CICS as an HTTP server).
  7. 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.
  8. 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.
  9. 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.
  10. 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.
  11. Now complete your definition:
    1. 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.
    2. 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.
End of change