URIMAP attributes

Describes the syntax and attributes of the URIMAP resource.

Read syntax diagramSkip visual syntax diagramURIMAP( name)GROUP( groupname)DESCRIPTION( text)STATUS(ENABLED)STATUS(DISABLED)PATH( path)SCHEME(HTTP)SCHEME(HTTPS)USAGE(SERVER)SERVER attributes USAGE(CLIENT)CLIENT attributes USAGE(PIPELINE)PIPELINE attributesUSAGE(ATOM)ATOM attributes USAGE(JVMSERVER)JVMSERVER attributes
SERVER attributes
Read syntax diagramSkip visual syntax diagramHOST( hostname)HOST(*)TCPIPSERVICE( name)SERVER attributes for static responseSERVER attributes for application response
Read syntax diagramSkip visual syntax diagramREDIRECTTYPE(NONE)REDIRECTTYPE(TEMPORARY)REDIRECTTYPE(PERMANENT)LOCATION( url)

SERVER attributes for static response

Read syntax diagramSkip visual syntax diagram MEDIATYPE( type) CHARACTERSET( characterset) HOSTCODEPAGE( code page) TEMPLATENAME( name)HFSFILE( name)

SERVER attributes for application response

Read syntax diagramSkip visual syntax diagram ANALYZER(NO)ANALYZER(YES) CONVERTER( name) TRANSACTION( name) PROGRAM( name) USERID( id)
CLIENT attributes
Read syntax diagramSkip visual syntax diagramHOST( hostname)PORT(NO)PORT( port)CERTIFICATE( label)CIPHERS( value)AUTHENTICATE(NO)AUTHENTICATE(BASIC)SOCKETCLOSE(0)SOCKETCLOSE( hhmmss)
PIPELINE attributes
Read syntax diagramSkip visual syntax diagramHOST( hostname)HOST(*)PIPELINE( name)WEBSERVICE( name)TCPIPSERVICE( name)TRANSACTION( name)USERID( id)REDIRECTTYPE(NONE)REDIRECTTYPE(TEMPORARY)REDIRECTTYPE(PERMANENT)LOCATION( url)
ATOM attributes
Read syntax diagramSkip visual syntax diagramHOST( hostname)HOST(*)ATOMSERVICE( name)TCPIPSERVICE( name)TRANSACTION( name)USERID( id)REDIRECTTYPE(NONE)REDIRECTTYPE(TEMPORARY)REDIRECTTYPE(PERMANENT)LOCATION( url)
JVMSERVER attributes
Read syntax diagramSkip visual syntax diagramHOST( hostname)HOST(*)PORT(NO)PORT( port)TRANSACTION( name)USERID( id)PIPELINE( name)WEBSERVICE( name)
ANALYZER({NO|YES})
This attribute is for USAGE(SERVER), where an application-generated response is to be provided. For other usage types, the attribute is forced to NO.
Setting ANALYZER to NO is required for HTTP requests to be processed by directly attaching the user transaction. For more information, see HTTP requests are processed by directly attached user transactions.

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.

ATOMSERVICE(name)
This attribute is for USAGE(ATOM).

When a client makes a request to CICS for an Atom feed by 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:
A-Z 0-9 $ @ #
Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.
AUTHENTICATE({NO|BASIC})
This attribute is for USAGE(CLIENT).

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 that is specified in the URIMAP resource.

CERTIFICATE(label)
This attribute is for USAGE(CLIENT).

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 that is made by CICS as a client. It is up to the server to request an SSL client certificate, and, if it does, CICS supplies the certificate label that is specified in the URIMAP definition. If this attribute is omitted, the default certificate that is 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. The certificate that is specified, or the default certificate, must have a private key available to it or the URIMAP cannot install. If you do not want to use a certificate, leave this field blank and ensure that the key ring used by the CICS region does not have a default certificate. For more information, see Building a key ring manually.

CHARACTERSET(characterset)
This attribute is for USAGE(SERVER), where a static response is to be provided.

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 of the character sets that are 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.

CIPHERS(value)
This attribute is for USAGE(CLIENT).
The CIPHERS attribute can be specified in either of two ways:
  • Recommended: The name of the SSL cipher suite specification file, which is a z/OS® UNIX file in the security/ciphers subdirectory of the directory that is specified by the USSCONFIG system initialization parameter. For example, if USSCONFIG is set to /var/cicsts/dfhconfig and CIPHERS is set to strongciphers.xml, the fully qualified file name is /var/cicsts/dfhconfig/security/ciphers/strongciphers.xml. For more information, see Creating an SSL cipher suite specification file.
  • A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.

When you use the CEDA transaction to define the resource, CICS automatically initializes the attribute with a default list of acceptable codes. For CICS to initialize the attribute, the KEYRING system initialization parameter must be specified in the CICS region where you are running CEDA. If KEYRING is not set, CICS does not initialize the attribute. The default list of 2-digit ciphers is 3538392F3233.

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.

When you use DFHCSDUP to define the resource, the CIPHERS attribute is not populated with a default value. If the resource is used to establish a secure connection and the CIPHERS attribute is empty, CICS uses the default list of 2-digit ciphers. An INQUIRE on the resource that is created in this manner, returns an empty string for the CIPHERS value.

Any unsupported ciphers are removed at run time. A list of the removed ciphers is reported in messages DFHSO0145 and DFHSO0146.

For more information, see Cipher suites and cipher suite specification files.

CONVERTER(name)
This attribute is for USAGE(SERVER), where an application-generated response is to be provided.

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:
A-Z 0-9 $ @ #
Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.
Unlike the relationship between the analyzer program and the TCPIPSERVICE definition, the converter program and the TCPIPSERVICE definition have no association.

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.

DESCRIPTION(text)
You can provide a description of the resource that you are defining in this field. The description text can be up to 58 characters in length. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right parenthesis. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.
GROUP(groupname)
Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.
Acceptable characters:
A-Z 0-9 $ @ #
Any lowercase characters you enter are converted to uppercase.

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

HFSFILE(name)
This attribute is for USAGE(SERVER), where a static response is to be provided.

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 that is 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 that is 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 by 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.
The value specified must be a valid name for a UNIX file:
  • It must not contain embedded space characters.
  • It must not contain consecutive instances of the / character.
  • It is case-sensitive.
Acceptable characters:
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 that is 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.

For example, you can create a URIMAP definition with the PATH attribute specified as:
findout/pictures/*
and the HFSFILE attribute that is specified as:
/u/facts/images/*
The URIMAP definition is used to process an incoming HTTP request
http://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. 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(hostname|*)
This attribute is for all USAGE options.

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 you are 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(CLIENT) and when Transport Layer Security (TLS) is used in the connection to an HTTP server, CICS passes the host name in the Server Name Indication (SNI) extension during the TLS handshake. This allows CICS to use a TLS communication to a virtual host where the server supports multiple virtual hosts using a single IP address. See also CICS web support fundamentals: Virtual hosting.

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. For more information about address formats, see IP addresses.

If CICS is an HTTP client and you specify USAGE(CLIENT), you can specify a port number in the request to the server:
  • Use the PORT attribute to specify the port number. PORT replaces the use of the HOST attribute for specifying a port number.
  • For compatibility purposes in existing programs that use native IPv4 addresses and host names, you can use the HOST attribute when you specify the port number. Native IPv4 addresses and host names are the only formats in which you can specify the port number, together with a preceding colon; for example, 1.2.3.4:80 or hostname.com:443.
  • If you specify an IPv6 address (or a host name that resolves to an IPv6 address), ensure that you are operating in a dual-mode (IPv4 and IPv6) environment and that the client or server that you are communicating with is also operating in a dual-mode (IPv4 and IPv6) environment. For more information about IPv6, see Understanding IPv6 and CICS.
  • For native IPv6 addresses, you must use the PORT attribute to specify the port number. IPv6 addresses require square brackets to separate the address from the port number, and, because square brackets are not fixed values in all EBCDIC character sets, square brackets are not supported in the HOST attribute.
  • 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.
HOSTCODEPAGE(code page)
This attribute is for USAGE(SERVER), where a static response is to be provided.

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 by 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(url)
This attribute is for USAGE(SERVER), USAGE(PIPELINE), and USAGE(ATOM).

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(type)
This attribute is for USAGE(SERVER), where a static response is to be provided.

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/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(path)
This attribute is for all USAGE options.

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 that begin with the string to the left of the asterisk. Specifying a path of /* makes the URIMAP definition match any requests that are 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 that relate 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.

PIPELINE(name)
This attribute is for USAGE(PIPELINE). This attribute is deprecated for USAGE(JVMSERVER).

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:
A-Z 0-9 $ @ #
Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.
PORT({NO|port})
This attribute applies to the USAGE(CLIENT) and USAGE(JVMSERVER) options only.

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.

PROGRAM(name)
This attribute is for USAGE(SERVER), where an application-generated response is to be provided.
PROGRAM specifies the 1- to 8-character name of the user application program that composes the HTTP response. For CICS as an HTTP server, this attribute is required unless an analyzer or converter program is specified, or a template name or zFS file is specified, or redirection is specified.
Acceptable characters:
A-Z 0-9 $ @ #
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({NONE|TEMPORARY|PERMANENT})
This attribute is for USAGE(SERVER), USAGE(PIPELINE), and USAGE(ATOM).

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 that is 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 that is used for the response is 301 (Moved Permanently).

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 you are 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({HTTP|HTTPS})
This attribute is for all USAGE options.

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 by using either the HTTP scheme or the HTTPS scheme. A URIMAP specifying the HTTPS scheme accepts only web client requests made by 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 by using either the HTTP scheme or the HTTPS scheme.

Inbound HTTP requests that arrive on SSL(ATTLSAWARE) TCPIPSERVICEs must use secure connections so they are always treated as HTTPS.

SOCKETCLOSE({0|hhmmss})
This attribute is for USAGE (CLIENT).

SOCKETCLOSE specifies whether, and for how long, CICS keeps a client HTTP connection open after the CICS application finishes 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 finishes using it. CICS does not place the connection in a pool for reuse.
hhmmss
When a CICS application finishes 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 Connection pooling for HTTP client performance.

STATUS({ENABLED|DISABLED})
This attribute is for all USAGE options.

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(name)
This attribute is for USAGE(SERVER), USAGE(PIPELINE), and USAGE(ATOM).

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:
A-Z 0-9 $ @ #
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(name)
This attribute is for USAGE(SERVER), where a static response is to be provided.

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 by 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:
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 that is 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.

For example, you can create a URIMAP definition with the PATH attribute specified as:
findout/about/*
and the TEMPLATENAME attribute that is specified as:
templates.facts.*
The URIMAP definition is used to process an incoming HTTP request
http://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 template
templates.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(name)
This attribute is for USAGE(SERVER), USAGE(PIPELINE) USAGE(ATOM), and USAGE(JVMSERVER).

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:
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
You can select a different transaction name for the purposes of security, monitoring and accounting, or transaction class limitation. Whatever name you choose for the alias transaction, it must always run the same program, which is determined by the USAGE attribute, and which overrides any program specified in the transaction definition:
  • 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.

URIMAP(name)
Specifies the name of this URIMAP definition. The name can be up to 8 characters in length. The attribute is specified in mixed case, and the case is preserved in the URIMAP definition.
Acceptable characters:
A-Z a-z 0-9 $ @ # . / - _ % & ? ! : | " = ¬ , ; < >
USAGE({SERVER|CLIENT|PIPELINE|ATOM|JVMSERVER})
Specifies whether this URIMAP definition is for CICS as an HTTP server (SERVER), CICS as an HTTP client (CLIENT), a web service (PIPELINE), an Atom feed (ATOM), or a JVM server (JVMSERVER). The USAGE attribute governs which other attributes in the URIMAP definition can be used.
  • 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. Requests that require an application-generated response might qualify for being processed by directly attached user transactions, and bypassing the web attach task. For more information, see HTTP requests are processed by directly attached user transactions.
  • 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. Requests might qualify for being processed by directly attached user transactions, and bypassing the web attach task. For more information, see HTTP requests are processed by directly attached user transactions.
  • 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. Requests might qualify for being processed by directly attached user transactions, and bypassing the web attach task. For more information, see HTTP requests are processed by directly attached user transactions.
  • 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(id)
This attribute is for USAGE(SERVER), where an application-generated response is to be provided, USAGE(PIPELINE), USAGE(JVMSERVER), and USAGE(ATOM).

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 the methods that are mentioned, 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 by 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 .

WEBSERVICE(name)
This attribute is for USAGE(PIPELINE). This attribute is deprecated for USAGE(JVMSERVER).

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 that represents a web service that is generated by the CICS web services assistant.

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

A WEBSERVICE resource defines aspects of the runtime environment for a CICS application program that is 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.