URIMAP attributes

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.

A-Z 0-9 $ @ #

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 .

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. 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.

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.

A-Z 0-9 $ @ #

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.

A-Z 0-9 $ @ #

The GROUP name can be up to 8 characters in length. Lowercase characters are treated as uppercase characters.

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. Up to 255 characters can be used.

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 relative path for example, facts/images/bluefish.jpg.

• For a static response file for a URIMAP resource defined by online resource definition, the file path is either fully qualified, if prefixed with a forward slash (/), or is relative to the HOME directory of the CICS region user ID.
• For a static response file for a URIMAP resource defined in a CICS bundle, the file path is relative to the root directory of the CICS bundle. The zFS file must be packaged in the CICS bundle with the URIMAP resource. The MEDIATYPE and HOSTCODEPAGE attributes must be specified, to inform CICS of the file type and the code page with which the file is encoded. When the file is defined in a CICS bundle and exported to zFS using CICS Explorer®, the code page with which the file is encoded is the same as the one used by CICS Explorer. For more information, see Referencing zFS artifacts in a bundle.

A-Z a-z 0-9 . / _ # @ -

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 remain 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/*

/u/facts/images/*

http://www.example.com/findout/pictures/bluefish.jpg

/u/facts/images/bluefish.jpg

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 the zFS file contents, although you can 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. 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 .

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 https://www.iana.org/assignments/media-types/media-types.xhtml/. 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 https://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. 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. describes these resource definitions.

A-Z 0-9 $ @ #

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.

A-Z 0-9 $ @ #

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.

• NONE means that requests are not redirected. Any URL specified by the LOCATION attribute is ignored.
• TEMPORARY means that requests are redirected on a temporary basis. The URL specified by the LOCATION attribute is used for redirection, and the status code used for the response is 302 (Found).
• PERMANENT means that requests are redirected permanently. The URL specified by the LOCATION attribute is used for redirection, and the status code used for the response is 301 (Moved Permanently).

You can use the SET URIMAP command to change the REDIRECTTYPE attribute and the LOCATION attribute.

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.

0

CICS closes each client HTTP connection when the CICS application has finished using it. CICS does not place the connection in a pool for reuse.

hhmmss

When a CICS application has finished using its client HTTP connection, CICS checks the state of the connection and places it in a pool for reuse. A dormant connection that is not reused is discarded after the length of time that you specify here.

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 .

STATUS specifies whether the URIMAP definition is to be installed in an enabled or disabled state. The default is enabled.

This attribute is ignored for URIMAP resources that are dynamically generated by a CICS bundle. The initial status of a URIMAP resource is derived from the initial status of the bundle that defines the resource.

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.

A-Z 0-9 $ @ #

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 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 .

A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >

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 remain 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/*

templates.facts.*

http://www.example.com/findout/about/fish.html

templates.facts.fish.html

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.

A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >

The default alias transaction is different for each type of URIMAP:

• USAGE(SERVER) uses the CWBA transaction
• USAGE(PIPELINE) uses the CPIH transaction
• USAGE(ATOM) uses the CW2A transaction
• USAGE(JVMSERVER) uses the CJSA transaction

• For USAGE(SERVER), the program is DFHWBA, which links to the application program named in the PROGRAM attribute of the URIMAP definition or named by the analyzer program.
• For USAGE(PIPELINE), the program is DFHPIDSH, which starts the pipeline that is named in the PIPELINE attribute and the web service that is named in the WEBSERVICE attribute, if specified.
• For USAGE(ATOM), the program is DFHW2A, the W2 domain alias program.
• For USAGE(JVMSERVER), the program is DFHSJTHP, which runs tasks in the JVM server for an application request.

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.

• When you specify SERVER, you create 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.
• When you specify CLIENT, you create 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.
• When you specify PIPELINE, you create 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.
• When you specify ATOM, you create a URIMAP definition for an Atom feed. This type of URIMAP definition is used for an incoming request for data that CICS makes available as an Atom feed. The URIMAP definition maps the request URI to an ATOMSERVICE resource definition, which defines an Atom document.
• When you specify JVMSERVER, you create a URIMAP for a web application that is running in a JVM server. This type of URIMAP is used to map incoming application requests to a CICS transaction. If no URIMAP matches the URI of the incoming request, CICS uses the CJSA transaction.

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 .

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.

A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >

A WEBSERVICE resource defines aspects of the runtime environment for a CICS application program deployed in a web services setting, where the mapping between application data structure and SOAP messages is generated by using the CICS tools.

This attribute is optional. However, if you do not specify a WEBSERVICE resource for USAGE(PIPELINE), the WEBSERVICE name must be resolved by a handler program in the pipeline, or you must use an alternative application or terminal handler in place of a WEBSERVICE resource.