URLs for CICS web support

In a request URL for a resource that is provided by CICS® web support, the path component of the URL is up to you. In CICS web support, the URIMAP definition or the analyzer program creates the linkage between the request URL and the resource provided by CICS, so the URL does not need to have any direct relationship to the CICS resource. However, you can design the URL to provide information for processing or administrative purposes.

The components of a URL explains the different components of a request URL and their role.

A newer form of resource identifier, the IRI (Internationalized Resource Identifier), permits the use of characters and formats that are suitable for national languages other than English. An IRI can be used in place of a URI or URL where the applications involved with the request and response support this. CICS supports the use of IRIs in URIMAP resource definitions. For more information about IRIs, see Internationalized Resource Identifiers (IRIs).

URLs for application-generated responses

Information in a request URL can be used by analyzer programs and by user-written application programs.

Where an analyzer program is used in the processing path for the request, you can design a URL that tells the analyzer program which programs and transaction to specify for further processing. The CICS-supplied sample analyzer program DFHWBADX analyzes URLs with a path component in the format /converter/alias/program/other path information, where converter names the converter program (if any), alias names the alias transaction, program names the user application program, and other path information gives additional information that is not used by the analyzer.

A Web-aware application program which is providing a response can also use information from the path component of the URL. The path component can be extracted by the application using the WEB EXTRACT command, and analyzed to determine the appropriate action. For example, the path component can be used to specify a particular function provided by the application. Alternatively, if the web-aware application is providing a front end for more than one other application, the path component of the URL can identify the application to which the request applies.

For application-generated responses that are managed using URIMAP definitions, the path components of URLs can be designed to map multiple request URLs to the same application. You can do this by making the path components of the URLs begin in the same way, and creating a single URIMAP definition with a wildcard to map all the request URLs to a single resource. For example, all requests whose path begins with /staffapps/ordering/ could be mapped to a particular CICS application, by creating a URIMAP definition that specifies the path /staffapps/ordering/* and specifies the relevant application. The application can then extract and analyze information in the remainder of the URL to determine the appropriate action for each request.

URLs for static responses

In CICS web support, the URL does not need to have any direct relationship to the CICS resource. For static responses, this means that the URL does not have to contain the full path to the file that provides the response. Instead, the URIMAP definition matches the request URL to the appropriate file.

However, where z/OS® UNIX files are used as the static responses, you could decide to design the path components of the request URLs so that they match the directories used on z/OS UNIX. If all the z/OS UNIX files provided by CICS web support are located in subdirectories of the same directory, such as the HOME directory of the CICS region userid, you might want to omit this directory and make the request URLs match the remainder of the paths to the files. For example, if your HOME directory is /u/cts/CICSHome, and you want to provide the following z/OS UNIX files as static responses:
you could use request URLs such as:
Remember that the path components of URLs are case-sensitive, and so are z/OS UNIX names. URLs are normally specified in lowercase. Take care to use the correct case when specifying each item in the URIMAP definition, especially if the file name is in mixed case and the URL is in lowercase.
You might want to make your request URLs match your file directory structure:
  • To make administration of resources more straightforward.
  • To follow standard practice for web servers.
  • To reduce the number of URIMAP definitions that you need to create.

You can create a single URIMAP definition with wildcards, to deliver multiple static responses using the path matching mechanism. This is possible where the path component of the URL for all those static responses begins in the same way, and where the files for the static responses are stored in the same z/OS UNIX file directory. Wildcards are used at the end of the path component of the URL, and also at the end of the file path for the z/OS UNIX file. In the previous example, all the HTML documents stored in the FAQs directory could be provided by a single URIMAP definition that specifies the path /faqs/* and specifies the HFSFILE attribute as /u/cts/CICSHome/FAQs/*. A similar technique can be used with CICS document templates whose names begin in the same way. Note that a URIMAP definition for a static response specifies a media type (for example text/html), so if you need to provide different file types in this way, ensure that they are stored in separate directories.

Query strings

A query string in a request URL can be used to select alternative URIMAP definitions. To use a query string for URIMAP matching, the complete and exact query string must be specified in the path attribute of the URIMAP definition, together with the path itself.

For application-generated responses, the application can extract and analyze information from a query string, using the WEB EXTRACT command or the WEB READ FORMFIELD command. This can be done whether or not the query string has been used for URIMAP matching.

If you are providing a static response with a document template, CICS automatically passes the content of the query string into the named CICS document template as a symbol list. If you want to use the content of the query string in the document template, you can include appropriate variables in your document template to be substituted for the content of the query string. This happens only if the query string has not already been used for URIMAP matching.

URL length: CICS web support

CICS web support has the following limitations on URL length:
  • For the URLs of inbound HTTP requests (for CICS as an HTTP server), CICS accepts a length of up to 32K. This length is at least eight times more than that supported by some commonly-used web browser clients. If CICS does receive a URL that is longer than it can handle, it returns a 414 (Request-URI Too Long) status code.
  • For the URLs of outbound HTTP requests (made by CICS as an HTTP client), CICS supports a path component of up to 255 characters in a URIMAP resource definition. The user application program that makes the request may override the URIMAP definition (or not use one at all), and supply a longer path component. Check the URL length that can be handled by the server.

URL length: URIMAP definitions

When choosing URLs for resources provided using URIMAP definitions, note the following additional limitations on URL length:
  • CICS supports a path component of up to 255 characters in a URIMAP resource definition. Try not to use longer path components than this. The HTTP/1.1 specification says that servers should be cautious about URLs with a total length (comprising scheme, host and path components, and delimiters) that is greater than 255 characters, because older web clients and proxies might not support these properly. If you are using an IRI that contains percent-encoded Unicode characters, note that 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.
  • If you need to use a longer path component, you usually can, because you do not have to specify the complete path in the URIMAP resource definition. An asterisk (*) may be used as a wildcard character at the end of the path. The behavior of the URIMAP definition will be correct if:
    • The specified part of the URL is unique to that resource.
    • The specified part of the URL is not unique to that resource, but you are providing a static response, and using the path matching mechanism to complete the URL.
  • If you are using a query string for the purpose of URIMAP matching, and specifying it in the path attribute of the URIMAP definition, the total length must still be within the 255-character limit. (Part of the path component may be replaced by an asterisk, if the behavior will still be correct, but an asterisk cannot be used within the query string.) If you are not using the query string for this purpose, then any length of query string can be accepted, up to CICS web support's overall 32K limit on URL length.
  • For a redirection (using the LOCATION and REDIRECTTYPE attributes in the URIMAP definition), CICS supports a redirection URL of up to 255 characters. This must be a complete URL, including the scheme, host and path components, and appropriate delimiters. If you plan to use a resource as a destination for redirected clients, make sure that its complete URL fits within this 255-character limit.