>>-URIMAP(name)--GROUP(groupname)--+-------------------+--------> '-DESCRIPTION(text)-' .-STATUS(ENABLED)--. .-SCHEME(HTTP)--. >--+------------------+--PATH(path)--+---------------+----------> '-STATUS(DISABLED)-' '-SCHEME(HTTPS)-' .-USAGE(SERVER)-| SERVER attributes |----. >--+-----------------------------------------+----------------->< +-USAGE(CLIENT)-| CLIENT attributes |----+ '-USAGE(PIPELINE)-| PIPELINE attributes |-' SERVER attributes |--+-HOST(hostname)-+--+--------------------+-------------------> '-HOST(*)--------' '-TCPIPSERVICE(name)-' >--+--------------------------------------------------------------------------------------------------+--> +-MEDIATYPE(type)--CHARACTERSET(characterset)--HOSTCODEPAGE(codepage)--+-TEMPLATENAME(name)-+------+ | '-HFSFILE(name)------' | | .-ANALYZER(YES)-. | '-+---------------+--+-----------------+--+-------------------+--+---------------+--+------------+-' '-ANALYZER(NO)--' '-CONVERTER(name)-' '-TRANSACTION(name)-' '-PROGRAM(name)-' '-USERID(id)-' >--+--------------------------------------------+---------------| | .-REDIRECTTYPE(NONE)------. | '-+-------------------------+--LOCATION(url)-' +-REDIRECTTYPE(TEMPORARY)-+ '-REDIRECTTYPE(PERMANENT)-' CLIENT attributes |--HOST(hostname)--+--------------------+--+----------------+---| '-CERTIFICATE(label)-' '-CIPHERS(value)-' PIPELINE attributes |--+-HOST(hostname)-+--PIPELINE(name)--+------------------+-----> '-HOST(*)--------' '-WEBSERVICE(name)-' >--+--------------------+--+-------------------+----------------> '-TCPIPSERVICE(name)-' '-TRANSACTION(name)-' >--+------------+-----------------------------------------------> '-USERID(id)-' >--+--------------------------------------------+---------------| | .-REDIRECTTYPE(NONE)------. | '-+-------------------------+--LOCATION(url)-' +-REDIRECTTYPE(TEMPORARY)-+ '-REDIRECTTYPE(PERMANENT)-'
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
If an analyzer program is used, you can still specify the CONVERTER, TRANSACTION, USERID, and PROGRAM attributes. The values that you specify for these attributes are used as input to the analyzer program, but they can be overridden by it. Alternatively, you can leave these attributes blank and let the analyzer program specify them.
You can reorder the cipher codes or remove them from the initial list. However, you cannot add cipher codes that are not in the default list for the specified encryption level. To reset the value to the default list of codes, delete all of the cipher suite codes and the field will automatically repopulate with the default list.
See Cipher suites for more information.
CHARACTERSET must be specified if a static response is being provided and the MEDIATYPE attribute specifies a text type.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
If the ANALYZER attribute is specified as YES, the CONVERTER attribute is used as input to the analyzer program, but it can be overridden by the analyzer program. If a converter program is used, you can still specify the PROGRAM attribute of the URIMAP definition, but the values that you specify for this attribute can be overridden by the converter program. Alternatively, you can leave this attribute blank and let the converter program specify it.
Acceptable characters:
Any
lower case characters you enter are converted to upper case. |
The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters. Do not use group names beginning with DFH, because these characters are reserved for use by CICS.
Acceptable characters:
For information about entering mixed case information,
see Entering mixed case attributes. |
If TEMPLATENAME or HFSFILE is specified, ANALYZER must be set to NO, and the other attributes relating to application-generated responses (TRANSACTION, CONVERTER, PROGRAM, and USERID) must be left blank.
If you want to use path matching, include an asterisk as a wildcard character at the end of the path for the HFS file, and also at the end of the path specified by the PATH attribute. CICS takes the portion of each HTTP request's path that is covered by the wildcard character, and substitutes this as the last part of the file path.
findout/pictures/*
and the HFSFILE
attribute specified as:/u/facts/images/*
The
URIMAP definition is used to process an incoming HTTP requesthttp://www.example.com/findout/pictures/bluefish.jpg
CICS
appends bluefish.jpg to the HFS file path specified
in the URIMAP definition in place of the asterisk, so that the HFS
file/u/facts/images/bluefish.jpg
is used as
the static response.A query string cannot be substituted into an HFS file (unless you define the HFS file as a CICS document template, and specify it using the TEMPLATENAME option instead of the HFSFILE option).
The HOST attribute must be present, and must contain only alphanumeric characters, hyphens (-) or periods (.). Hexadecimal escape sequences cannot be used in a host name. CICS validates this at define time. The host name can be entered in any case, but it is converted to lower case in the URIMAP definition.
An IPv4 address can be used as a host name, but IPv6 addresses are not supported.
When USAGE(SERVER) or USAGE(PIPELINE) is specified, a single
asterisk can be used as the HOST attribute. This makes the URIMAP
definition match any host name. An asterisk cannot be used as a wildcard
in the HOST attribute along with any other characters.
For URIMAP definitions relating to CICS as an HTTP client, USAGE(CLIENT), if you need 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 need to specify the port number if it is other than the default for the scheme (80 for HTTP without SSL, or 443 for HTTPS, HTTP with SSL).
HOSTCODEPAGE must be specified if a static response is being provided and the MEDIATYPE attribute specifies a text type.
The
description for the PATH attribute lists the characters that should
be excluded from a URL. These characters must not be used in the LOCATION
attribute. The exception is the # character, which can be used in
the LOCATION attribute as a separator before a fragment identifier
which follows the URL.
The REDIRECTTYPE attribute 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 no redirection is specified, the URL in the LOCATION attribute is ignored. You can use the SET URIMAP command to change the REDIRECTTYPE attribute and the LOCATION attribute.
The name for each formally recognized type of data content is defined by IANA. A list is available at http://www.iana.org/assignments/media-types/. CICS creates a Content-Type header for the response using the value of this attribute.
There is no default for this attribute, and it must be specified. If the MEDIATYPE attribute specifies a text type (such as a type that begins with text/, or a type that contains +xml), the CHARACTERSET and HOSTCODEPAGE attributes must also be specified so that code page conversion can take place. Text media types are identified by RFC 3023, which is available at http://www.ietf.org/rfc/rfc3023.txt.
For a dynamic (application-generated) response, this attribute is not used. The media type for the response is specified by the WEB SEND command.
The PATH attribute is specified in mixed case, and the case is preserved in the URIMAP definition. The PATH attribute must contain only the characters allowed in URIs. Specifically, the characters < > # % “ { } | \ ^ [ ] ` and imbedded blanks should be excluded (except that % should be allowed when it introduces a valid hexadecimal escape sequence: that is, when it is followed by two valid hexadecimal digits in upper or lower case). The tilde character (~) cannot be specified in CICS and must be replaced by the corresponding hexadecimal escape sequence (%7E). CICS validates the use of characters at define time.
For URIMAP definitions relating to CICS as an HTTP server and Web services, 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 to the left of the asterisk. Specifying a path of /* makes the URIMAP definition match any requests directed to the host named in the HOST attribute. If an HTTP request is matched by more than one URIMAP definition, the most specific match is taken.
If a query component is present, and you want to apply the URIMAP definition to that specific query alone, you can include this as part of the path component. Include the question mark at the beginning of the string. The query string must contain only the characters allowed in URIs. A query string may not itself include an asterisk as a wildcard, but it may follow a path that includes an asterisk as a wildcard. If you do not include a query string in the URIMAP definition, any query string that is present in the HTTP request is automatically ignored for matching purposes.
For URIMAP definitions for CICS as an HTTP client, you cannot use an asterisk as a wildcard; you must specify the complete path for the request. If the URIMAP definition is referenced on a WEB OPEN command, this path becomes the default path for WEB SEND commands relating to that connection. If the URIMAP definition 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 definition must match the host specified on the WEB OPEN command for the connection.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
If the ANALYZER attribute is specified as YES, or a converter program is specified using the CONVERTER attribute, the PROGRAM attribute is used as input to the analyzer or converter program, but it can be overridden by those programs. Alternatively, you can leave this attribute blank and let the analyzer or converter program specify it.
You can use the SET URIMAP command to change the REDIRECTTYPE attribute and the LOCATION attribute.
If REDIRECTTYPE(TEMPORARY) or REDIRECTTYPE(PERMANENT) is specified when creating a URIMAP definition, the following attributes are optional: ANALYZER, CONVERTER, HFSFILE, PIPELINE, PROGRAM, TEMPLATENAME, TRANSACTION, USERID, and WEBSERVICE. If you use a CEMT or EXEC CICS command to set the REDIRECTTYPE attribute to NONE after the URIMAP definition is installed, any of the listed attributes that were specified in the URIMAP definition are activated.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters you enter are converted
to uppercase. |
When a URIMAP definition with HTTPS 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.
Acceptable characters:
For information about entering mixed case information,
see Entering mixed case attributes. |
If TEMPLATENAME or HFSFILE is specified, ANALYZER must be set to NO, and the other attributes relating to application-generated responses (TRANSACTION, CONVERTER, PROGRAM, and USERID) must be left blank.
If you want to use path matching, include an asterisk as a wildcard character at the end of the name of the CICS document template, and also at the end of the path specified by the PATH attribute. CICS takes the portion of each HTTP request's path that is covered by the wildcard character, and substitutes this as the last part of the template name.
findout/about/*
and the TEMPLATENAME
attribute specified as:templates.facts.*
The
URIMAP definition is used to process an incoming HTTP requesthttp://www.example.com/findout/about/fish.html
CICS
appends fish.html to the template name specified
in the URIMAP definition in place of the asterisk, so that the templatetemplates.facts.fish.html
is
used to form the static response.When the TEMPLATENAME attribute is specified, if a query string is present on the URI, but is not used in the PATH attribute, CICS automatically passes the content of the query string into the named CICS document template as a symbol list. If you want to use the content of the query string in the document template, you need to include appropriate variables in your document template to be substituted for the content of the query string.
Acceptable characters:
For information about entering mixed case information,
see Entering mixed case attributes. |
For USAGE(SERVER), if the ANALYZER attribute is specified as YES, the TRANSACTION attribute is used as input to the analyzer program, but the analyzer program can override it. Alternatively, you can leave this attribute blank and let the analyzer program specify it. (For USAGE(PIPELINE), the analyzer is not used.)
Acceptable characters:
For information about entering mixed case information,
see Entering mixed case attributes. |
Specifying SERVER creates a URIMAP definition for CICS as an HTTP server. This type of URIMAP definition is used to map the URI of an incoming HTTP request from a Web client, to CICS resources. An application-generated response or a static response can be provided.
Specifying CLIENT creates a URIMAP definition for CICS as an HTTP client. This type of URIMAP definition is used when CICS makes a request for an HTTP resource on a server, so that you can avoid identifying the URI in your application program.
Specifying PIPELINE creates a URIMAP definition for a Web service. This type of URIMAP definition is used for an inbound Web service request (that is, a request by which a client invokes a Web service in CICS). The URI of the incoming request is associated with WEBSERVICE and PIPELINE resources, which specify the processing that is to be performed on the message.
USERID specifies a 1- to 8-character default user ID that can be used by any client. For an application-generated response or a web service, the alias transaction is attached under this user ID.
When
authentication is required for the connection, so that CICS requests
an authenticated user ID directly from the client, the default user
ID that you specify in the URIMAP definition is not used. The authenticated
user ID of the client is used instead, or if authentication fails,
the request is rejected. Authentication procedures are specified by
the AUTHENTICATE attribute of the TCPIPSERVICE definition for the
connection.
If ANALYZER(YES) is specified, a user ID from a URIMAP definition or from the client can be changed by the analyzer program, or the analyzer program can set a user ID. If no user ID is specified by any of these means, the default user ID is the CICS default user.
For USAGE(SERVER), if the ANALYZER attribute is specified as YES, the USERID attribute is used as input to the analyzer program, but the analyzer program can override it. Alternatively, you can leave this attribute blank and let the analyzer program specify it. (For USAGE(PIPELINE), the analyzer is not used.)
If surrogate user checking is enabled in the CICS region (with XUSER=YES specified as a system initialization parameter), CICS checks that the user ID used to install the URIMAP definition, is authorized as a surrogate of the user ID specified for the USERID attribute. Where surrogate user checking applies explains surrogate user checking.
Acceptable characters:
For information about entering mixed case information,
see Entering mixed case attributes. |