URLs for XCICS Web Support

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

URLs for application-generated responses

In XCICS Transaction Server for z/OS, Version 3 Release 1, 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 XCICS-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 XCICS 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 XCICS Web support, the URL does not need to have any direct relationship to the XCICS 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 flat 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 the file system. If all the files provided by XCICS Web support are located in subdirectories of the same directory, such as the HOME directory of the XCICS 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 /var/www/html, and you want to provide the following HFS files as static responses:

/var/www/html/FAQs/ordering.html
/var/www/html/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 file names. URLs are normally specified in lower case. 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 lower case.

You might want to make your request URLs match your HFS directory structure:

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 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 file. In the example above, 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 file attribute as /var/www/html/FAQs/*.

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, XCICS automatically passes the content of the query string into the named XCICS 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.