SET URIMAP

Enables or disables a URIMAP resource, and applies or removes redirection for a URIMAP resource.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

SET URIMAP

Read syntax diagramSkip visual syntax diagramSET URIMAP( data-area)ENABLESTATUS(cvda)DISABLEDENABLEDREDIRECTTYPE(cvda)NONEPERMANENTTEMPORARYLOCATION( data-area)

Conditions: INVREQ, NOTAUTH, NOTFND

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations. For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

This command is threadsafe.

Description

The SET URIMAP command allows you to:
  • Enable or disable a URIMAP resource.
  • Set redirection for matching HTTP requests, and specify a URL to which the requests are redirected. You can use this command to apply redirection to an existing URIMAP resource, for example if the application that would normally respond to the HTTP request is unavailable. You can also use this command to remove redirection from a URIMAP resource.
You cannot use the SET URIMAP command for URIMAP resources that are defined and installed in a CICS bundle. If you attempt to modify a dynamically generated URIMAP resource that was installed by a CICS bundle, an INVREQ response with a RESP2 value of 300 is issued.
  • You can control the status of dynamically generated URIMAP resources by enabling or disabling the BUNDLE resources that installed them.
  • You can modify the definition of dynamically generated URIMAP resources by updating the URI map in the CICS bundle project in CICS Explorer®, as follows:
    1. Export the new version of the CICS bundle to z/OS UNIX.
    2. Disable and discard the BUNDLE resource that points to the previous version.
    3. Edit the BUNDLE resource definition to point to the updated bundle directory.
    4. Reinstall the updated BUNDLE resource definition.

    For instructions for working with resources defined in CICS bundles, see the help in the CICS Explorer.

Options

ENABLESTATUS(cvda)
Sets the URIMAP definition to enabled or disabled status. CVDA values are:
ENABLED
The URIMAP definition can be accessed by applications.
DISABLED
The URIMAP definition cannot be accessed by applications. A URIMAP definition has to be disabled before it can be reinstalled or discarded.

For a URIMAP with USAGE(CLIENT), any cached IP address and server HTTP version information are deleted.

If a URIMAP resource associated with the current HTTP request is disabled, error message DFHWB0763 is issued.

LOCATION(data-area)
Specifies a URL of up to 255 characters, to which matching HTTP requests from Web clients can be redirected. This must be a complete URL, including scheme, host, and path components, and appropriate delimiters. CICS does not check that the URL is valid, so you must ensure that the destination exists and that the URL is specified correctly.

The REDIRECTTYPE option is used to specify the type of redirection. If temporary or permanent redirection is specified, the URL in the LOCATION attribute is used for redirection. If NONE is specified, the URL in the LOCATION option is ignored.

REDIRECTTYPE(cvda)
Specifies the type of redirection for requests that match this URIMAP definition. The URL for redirection is specified by the LOCATION option. CVDA values are:
NONE
Requests are not redirected. Any URL specified by the LOCATION option is ignored.
TEMPORARY
Requests are redirected on a temporary basis. The HTTP status code used for the response is 302 (Found).
PERMANENT
Requests are redirected permanently. The HTTP status code used for the response is 301 (Moved Permanently).

Conditions

INVREQ
RESP2 values are:
8
No location specified for redirection (LOCATION option).
9
Invalid REDIRECTTYPE or ENABLESTATUS value.
12
The URIMAP has USAGE(CLIENT) or USAGE(JVMSERVER), so redirection does not apply and the LOCATION option cannot be set.
300
A SET URIMAP SPI command was issued against a URIMAP resource that was created by a CICS bundle (BUNDLE).
NOTAUTH
RESP2 values are:
100
The user associated with the issuing task is not authorized to use this command.
NOTFND
RESP2 values are:
3
The URIMAP cannot be found.