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.
/u/cts/CICSHome
, and you want to provide the following z/OS UNIX files as static responses:/u/cts/CICSHome/FAQs/ordering.html
/u/cts/CICSHome/help/directory/viewing.html
you could use
request URLs such as:http://www.example.com/faqs/ordering.html
http://www.example.com/help/directory/viewing.html
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.- 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
- 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
- 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.