Describes the syntax and attributes of the URIMAP resource.
>>-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 |----+ +-USAGE(ATOM)-| ATOM attributes |-----------+ '-USAGE(JVMSERVER)-| JVMSERVER attributes |-'
SERVER attributes |--+-HOST(hostname)-+--+--------------------+-------------------> '-HOST(*)--------' '-TCPIPSERVICE(name)-' >--+--------------------------------------------------------------------------------------------------+--> +-MEDIATYPE(type)--CHARACTERSET(characterset)--HOSTCODEPAGE(codepage)--+-TEMPLATENAME(name)-+------+ | '-HFSFILE(name)------' | | .-ANALYZER(NO)--. | '-+---------------+--+-----------------+--+-------------------+--+---------------+--+------------+-' '-ANALYZER(YES)-' '-CONVERTER(name)-' '-TRANSACTION(name)-' '-PROGRAM(name)-' '-USERID(id)-' >--+--------------------------------------------+---------------| | .-REDIRECTTYPE(NONE)------. | '-+-------------------------+--LOCATION(url)-' +-REDIRECTTYPE(TEMPORARY)-+ '-REDIRECTTYPE(PERMANENT)-'
CLIENT attributes |--HOST(hostname)--+-PORT(NO)---+--+--------------------+-------> '-PORT(port)-' '-CERTIFICATE(label)-' .-AUTHENTICATE(NO)----. >--+----------------+--+---------------------+------------------> '-CIPHERS(value)-' '-AUTHENTICATE(BASIC)-' .-SOCKETCLOSE(0)------. >--+---------------------+--------------------------------------| '-SOCKETCLOSE(hhmmss)-'
PIPELINE attributes |--+-HOST(hostname)-+--PIPELINE(name)--+------------------+-----> '-HOST(*)--------' '-WEBSERVICE(name)-' >--+--------------------+--+-------------------+----------------> '-TCPIPSERVICE(name)-' '-TRANSACTION(name)-' >--+------------+-----------------------------------------------> '-USERID(id)-' >--+--------------------------------------------+---------------| | .-REDIRECTTYPE(NONE)------. | '-+-------------------------+--LOCATION(url)-' +-REDIRECTTYPE(TEMPORARY)-+ '-REDIRECTTYPE(PERMANENT)-'
ATOM attributes |--+-HOST(hostname)-+--ATOMSERVICE(name)------------------------> '-HOST(*)--------' >--+--------------------+--+-------------------+----------------> '-TCPIPSERVICE(name)-' '-TRANSACTION(name)-' >--+------------+-----------------------------------------------> '-USERID(id)-' >--+--------------------------------------------+---------------| | .-REDIRECTTYPE(NONE)------. | '-+-------------------------+--LOCATION(url)-' +-REDIRECTTYPE(TEMPORARY)-+ '-REDIRECTTYPE(PERMANENT)-'
JVMSERVER attributes |--+-HOST(hostname)-+--+-PORT(NO)---+--+-------------------+----> '-HOST(*)--------' '-PORT(port)-' '-TRANSACTION(name)-' >--+------------+-----------------------------------------------| '-USERID(id)-'
ANALYZER specifies whether an analyzer program is to be used in processing the HTTP request. The analyzer must be associated with the TCPIPSERVICE definition or definitions to which this URIMAP definition relates. (An analyzer program must be in the local CICS® region.) YES runs the analyzer. NO means that the analyzer is not used.
The default analyzer DFHWBAAX and sample analyzer DFHWBADX do not analyze a request when a matching URIMAP definition is found for the request, even if the URIMAP specifies ANALYZER(YES).
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.
When a client makes a request to CICS for an Atom feed using the URI specified by this URIMAP definition, ATOMSERVICE specifies the 1- to 8-character name of the ATOMSERVICE resource definition for the Atom feed. The ATOMSERVICE resource definition defines an Atom service, feed, collection, or category document, and identifies the Atom configuration file, CICS resource or application program, and XML binding that are used to supply the data for the feed.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters that you
enter are converted to uppercase. |
AUTHENTICATE specifies whether to send HTTP basic authentication information to the HTTP server. AUTHENTICATE(BASIC) requires a user ID and password to be provided by the XWBAUTH global user exit, or as values on the API commands such as WEB SEND or WEB CONVERSE. The XWBAUTH global user exit is not called if USERNAME and PASSWORD are specified on the API command. If you specify an authentication value on the API command, this value is used instead of the AUTHENTICATE value specified in the URIMAP resource.
CERTIFICATE specifies the label of the X.509 certificate that is to be used as the SSL client certificate during the SSL handshake. Certificate labels can be up to 32 characters long. This attribute is used only when the URI specified by the URIMAP definition is to be used for an HTTPS request made by CICS as a client. It is up to the server to request an SSL client certificate, and, if this happens, CICS supplies the certificate label that is specified in the URIMAP definition. If this attribute is omitted, the default certificate defined in the key ring for the CICS region user ID is used. The certificate must be stored in a key ring in the external security manager database. For more information, see Building a key ring manually.
CHARACTERSET specifies the 1- to 40-character name of the character set into which CICS converts the entity body of the response that is sent to the web client. CICS does not support all the character sets named by IANA. HTML coded character sets lists the IANA character sets that are supported by CICS. The value of this attribute is included in the Content-Type header of the response.
You must specify CHARACTERSET if a static response is being provided and the MEDIATYPE attribute specifies a text type.
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. The field is automatically repopulated with the default list.
For more information, see Cipher suites.
CONVERTER specifies the 1- to 8-character name of a converter program that converts the request and response. Typically, a converter program transforms the HTTP request into a COMMAREA that can be used by an application program and transforms the output into an HTTP response. The converter program can be any converter program that is available in the local CICS region.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters that 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
lowercase characters that you enter are converted to uppercase. |
The GROUP name can be up to 8 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.
HFSFILE specifies the fully qualified (absolute) or relative name of a z/OS UNIX System Services zFS file that forms the body of the static response that is sent to the HTTP request from the web client. You can specify the name as an absolute path, including all directories and beginning with a slash; for example, /u/facts/images/bluefish.jpg. Alternatively, you can specify it as a path relative to the HOME directory of the CICS region user ID; for example, facts/images/bluefish.jpg. Up to 255 characters can be used.
The value specified must be a valid name for a UNIX file:
|
If TEMPLATENAME or HFSFILE is specified, ANALYZER must be set to NO. Other attributes that relate only to application-generated responses (TRANSACTION, CONVERTER, and PROGRAM) 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 zFS file and also at the end of the path specified by the PATH attribute. CICS takes the portion of the path of each HTTP request that is covered by the wildcard character and substitutes it 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 zFS file path specified
in the URIMAP definition in place of the asterisk, so that the zFS
file/u/facts/images/bluefish.jpg
is used as
the static response.You cannot use an asterisk alone in the HFSFILE specification. At least one level of the directory structure must be specified.
If you are using IRIs (Internationalized
Resource Identifiers) containing Unicode characters, the Unicode characters
must be escaped to their percent-encoded representations in the zFS
file name and in the corresponding path. Tools are available on the
web to help you do this. Search the web for unicode percent escaped
.
A query string cannot be substituted into an zFS file (unless you define the zFS file as a CICS document template and specify it using the TEMPLATENAME attribute instead of the HFSFILE attribute).
HOST specifies the host name of the URI to which the URIMAP definition applies, or its IPv4 or IPv6 address. The name can be up to 116 characters long. The components of a URL explains each of the components and how they are delimited.
The HOST attribute must be present. The HOST attribute must contain only alphanumeric characters, hyphens (-), colons (:), or periods (.), although you cannot use colons when specifying a character host name instead of an IP address. CICS validates the host name at define time. A host name can be entered in any case, but if a character host name is specified instead of an IP address, the host name is converted to lowercase in the URIMAP definition.
When you specify USAGE(SERVER), USAGE(PIPELINE), USAGE(ATOM), or USAGE(JVMSERVER) you can use a single asterisk in the HOST attribute, making the URIMAP definition match any host name. You cannot use an asterisk as a wildcard in the HOST attribute with any other characters. Do not set a port number in this attribute for these usage types.
URIMAP resources support Internationalized Resource Identifiers (IRIs), which can contain Unicode characters. If you specify a host name that contains Unicode characters, you must convert the host name to Punycode format, which is described by RFC 3492. CICS does not provide a tool to carry out this conversion, but free applications are available on the Internet to support the conversion of Unicode to Punycode. If you use an asterisk as the host name, you do not need to use Punycode. For more information about IRIs, see Internationalized Resource Identifiers (IRIs).
You can specify IPv4 and IPv6 addresses in a number of acceptable formats. See IP addresses for more information about address formats.
HOSTCODEPAGE specifies the 1- to 10-character name of the IBM® code page (EBCDIC) in which the text document that forms the static response is encoded. CICS needs this information to convert the code pages for the entity body of the static response.
The standard CICS form of a host code page name consists of the code page number (or more generally CCSID) written using 3 - 5 decimal digits as necessary then padded with trailing spaces. For code page 37, which is fewer than 3 digits, the standard form is 037. CICS accepts any decimal number, padded with trailing spaces, in the range 1 - 65535 as a code page name, even if it is not in the standard form.
You must specify HOSTCODEPAGE if a static response is being provided and the MEDIATYPE attribute specifies a text type.
LOCATION specifies a URL of up to 255 characters to which the client request is redirected. The URL must be complete, including scheme, host, 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 description for the PATH attribute lists the characters that must 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 that 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.
MEDIATYPE specifies the media type (data content) of the static response that CICS provides to the HTTP request; for example, image/jpg, text/html or text/xml. Up to 56 characters can be used. The media type must contain exactly one forward slash (/). The media type can be entered in uppercase or lowercase, but it is converted to lowercase in the URIMAP definition.
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 by using the value of this attribute.
This attribute has no default, 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, you must also specify the CHARACTERSET and HOSTCODEPAGE attributes 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.
PATH specifies the path component of the URI to which the URIMAP definition applies, which can be up to 255 characters, including the forward slash (/) at the beginning of the path component. If you do not include the forward slash, you can use only 254 characters to specify the path. The minimum possible path is a forward slash, which represents the root of the URL structure for the specified host name. You can include or omit the forward slash at the beginning of the path component; however, if you omit it, CICS adds it at runtime. An example of a path is software/htp/cics/index.html. The components of a URL explains each of the components and how they are delimited.
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 that are allowed in URIs. Specifically, the characters < > # % “ { } | \ ^ [ ] ` and embedded blanks must be excluded (except that % is allowed when it introduces a valid hexadecimal escape sequence; that is, when it is followed by two valid hexadecimal digits in uppercase or lowercase). 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.
URIMAP resources support Internationalized Resource Identifiers (IRIs), which can contain Unicode characters. If you specify a path that contains Unicode characters, any Unicode characters must be escaped to the percent-encoded representation of the Unicode character. If you do not have an application that can convert Unicode characters to percent-encoded representations, free applications are available on the Internet to do this task. The path must still be 255 characters or less, and a character in this context means a single ASCII character, not the original Unicode character. For example, the Cyrillic character that has the percent-encoded representation %D0%B4 counts as 6 characters from the 255–character limit.
For URIMAP definitions that relate to CICS as an HTTP server and web services, if you want the URIMAP definition to match more than one path, you must use an asterisk as a wildcard character at the end of the path. For example, specifying the path /software/htp/cics/* makes the URIMAP definition match all requests with paths beginning 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 it as part of the path component. Include the question mark at the beginning of the string. The query string must contain only the characters that are allowed in URIs. A query string cannot itself include an asterisk as a wildcard, but it can 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 Atom feeds, you must use an asterisk as a wildcard character at the end of the path. The part of the path that you specify in the URIMAP definition is the part that is common to the Atom feed and Atom entry URLs. CICS matches the remainder of the URL to the URLs specified in all the <atom:link> elements in the Atom configuration file for the feed.
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. However, the host attribute for that URIMAP definition must match the host that is specified on the WEB OPEN command for the connection.
When a client makes an inbound web service request to CICS with the URI specified by this URIMAP definition, PIPELINE specifies the 1- to 8-character name of the PIPELINE resource definition for the web service. The PIPELINE resource definition provides information about the message handlers, which act on the service request from the client. PIPELINE resources describes these resource definitions.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters that you
enter are converted to uppercase. |
For USAGE(CLIENT), the PORT attribute specifies the decimal number of the port that is used by a CICS application when it communicates with a server. The value must be a number in the range 1 - 65535.
The port number is combined with the HOST value to determine the destination for outbound requests for this URIMAP. Specify the port number only if it is different from the default for the scheme: 80 for HTTP without SSL, or 443 for HTTPS and HTTP with SSL.
If you specify a port number in the HOST attribute and a different port number in the PORT attribute, an error is returned. If you do not specify a port number in either the HOST or the PORT attribute, the default port number for the scheme is used.
For USAGE(JVMSERVER), the PORT attribute specifies the port number that is used to receive requests to access an application that is running in a Liberty profile server.
If you do not specify a value for the PORT attribute, PORT is set to NO to indicate that the attribute is not being used.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters that you
enter are converted to uppercase. |
If the ANALYZER attribute is specified as YES, or a converter program is specified in 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.
REDIRECTTYPE specifies the type of redirection for requests that match this URIMAP definition. The URL specified by the LOCATION attribute is used for redirection when required.
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 are specified in the URIMAP definition are activated.SCHEME specifies the scheme component of the URI to which the URIMAP definition applies, which is either HTTP (without SSL) or HTTPS (with SSL). Do not include the delimiters :// (colon and two forward slashes) that follow the scheme component in the URI.
A URIMAP specifying the HTTP scheme accepts web client requests made using either the HTTP scheme or the HTTPS scheme. A URIMAP specifying the HTTPS scheme accepts only web client requests made using the HTTPS scheme. However, if the transport is WebSphere MQ, a URIMAP specifying either the HTTP scheme or the HTTPS scheme accepts web client requests made using either the HTTP scheme or the HTTPS scheme.
SOCKETCLOSE specifies if, and for how long, CICS keeps a client HTTP connection open after the CICS application has finished using it. After use, CICS checks the state of the connection and then places it in a pool in a dormant state. A dormant connection can be reused by the same application or by another application that connects to the same host and port.
Connection pooling can provide performance benefits for the HTTP EP adapter for CICS event processing, or where multiple invocations of CICS web support applications make connection requests for the same host and port, or where a web services application makes multiple requests and responses. To activate connection pooling, your application programs must specify the URIMAP resource on the INVOKE SERVICE or WEB OPEN command. For more information about connection pooling, see Connection pooling for HTTP client performance.
STATUS specifies whether the URIMAP definition is to be installed in an enabled or disabled state. The default is enabled.
TCPIPSERVICE specifies the 1- to 8-character name of a TCPIPSERVICE resource definition, with PROTOCOL(HTTP), that defines an inbound port to which this URIMAP definition relates. If this attribute is not specified, the URIMAP definition applies to a request on any inbound ports.
Acceptable characters:
Unless
you are using the CREATE command, any lowercase characters that 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.
You specify the security measures that are applied for each port in the TCPIPSERVICE resource definition. You can choose whether to use SSL, and, if you do use SSL, you need to choose the exact security measures that are applied, for example, the authentication method, the sending of certificates by client and server, and encryption of messages. Read Security for CICS web support for more information about the security features that you can use to keep your CICS web support facility safe.
TEMPLATENAME specifies the 1- to 48-character name of a CICS document template that forms the body of the static response that is sent to the HTTP request from the web client. It must be defined using a DOCTEMPLATE resource definition, and the TEMPLATENAME attribute of that definition specifies the name that is used in the URIMAP definition. For more information, see CICS documents and document templates.
Acceptable characters:
|
If you specify TEMPLATENAME or HFSFILE, you must set ANALYZER to NO. The other attributes that relate only to application-generated responses (TRANSACTION, CONVERTER, and PROGRAM) 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 requests path that is covered by the wildcard character and substitutes it 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.Specifying an asterisk alone for the TEMPLATENAME attribute means that the selected template has the same name as the part of the URL that corresponds to the wildcard character in the PATH attribute.
When you specify the TEMPLATENAME attribute, 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, include appropriate variables in your document template to be substituted for the content of the query string.
TRANSACTION specifies the 1-4 character name of an alias transaction that is to be used to run the application, or to start the pipeline.
Acceptable characters:
|
The default alias transaction is different for each type of URIMAP:
For USAGE(SERVER) only, 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. The analyzer is not used for other types of URIMAP.
Acceptable characters:
|
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.
For USAGE(JVMSERVER), the user ID is used to attach a transaction to run work in the Liberty profile server. The transaction can be specified in the URI map or use the default transaction CJSA. The user ID is not used if basic authentication is enabled; CICS expects a user ID and password in the HTTP header for the application request and rejects the request if authentication fails. If security is not enabled and no user ID is present in the HTTP header or in the URI map, the default user ID for the CICS region is used.
For other usage types, 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.
For an application-generated response, if ANALYZER(YES) is specified, 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. The analyzer is used only when USAGE(SERVER) is specified. A user ID specified by a client can also be changed by the analyzer program. If no user ID is specified by any of these means, the default user ID for an application-generated response is the CICS default user ID.
For static responses, the USERID attribute does not apply. Resource security checking for static responses can be carried out only using the authenticated user ID of a client.
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. For more information about surrogate user checking, see Where surrogate user checking applies .
When a client makes an inbound web service request to CICS with the URI specified by this URIMAP definition, WEBSERVICE specifies the name of the web service. This name can be the 1- to 8-character name of a WEBSERVICE resource definition, or a name up to 32 characters in mixed case representing a web service generated by the CICS web services assistant.
Acceptable characters:
|