Installing URIMAP resource definitions

This procedure uses the CEMT and CEDA transactions to install a URIMAP resource definition. If the URIMAP resource already exists, it has to be disabled before it can be reinstalled.

Procedure

  1. If the URIMAP resource already exists, ensure that it is disabled.
    Use the following command:
    CEMT SET URIMAP(name) DISABLED
    While the URIMAP resource is disabled, if a web client makes an HTTP request that requires the resource, CICS® issues error message DFHWB0763, and returns an HTTP 503 response (Service Unavailable) to the web client through a web error program. You can tailor this response by changing the web error program.
  2. Install the URIMAP definition.
    Use the following command:
    CEDA INSTALL GROUP(groupname) URIMAP(name)
    When you install a URIMAP definition, CICS carries out the following security checks:
    • If the URIMAP definition specifies SCHEME(HTTPS), CICS checks at installation time that SSL and TCP/IP are active in the CICS region. This is indicated by the use of the KEYRING system initialization parameter to specify the key ring that is used by the CICS region. If SSL or TCP/IP is not active in the CICS region, CICS issues message DFHAM4905, and the URIMAP definition is not installed.
    • If the URIMAP definition specifies the CIPHERS attribute, CICS validates the list of ciphers against the ciphers supported in the running system. If no valid ciphers are found in the list, CICS issues message DFHAM4918 and the URIMAP definition is not installed. However, if some but not all of the ciphers in the list are supported, CICS issues message DFHAM4917 and the URIMAP is installed with the reduced set of cipher codes.
    • If the URIMAP definition specifies the CERTIFICATE attribute, CICS validates the certificate against those specified in the key ring. If the specified certificate is not valid, then CICS issues messages DFHAM4889 and DFHAM4928, and the URIMAP definition is not installed.
      Tip: CICS validates the certificate against the information held in the key ring for the CICS region in the external security manager’s database. When the CICS region carries out SSL handshakes, it uses information from the cache of certificates in the SSL environment for the CICS region, which is managed by z/OS® System SSL. If you have added this certificate to the key ring, or renewed it, since the last build or rebuild of the SSL environment for the CICS region, issue the PERFORM SSL REBUILD command for the CICS region. The command refreshes the cache of certificates and ensures that the correct information for this certificate is present in the cache.
  3. Optional: When you have successfully installed the URIMAP definition, use CEMT to enable the resource.
    Perform this step only if the URIMAP resource is not already defined as ENABLED, and you want to make the resource available for web clients or web services. Use the following command:
    CEMT SET URIMAP(name) ENABLED