Start of change

Providing static HTTP responses with a CICS document template or HFS file

You can use a CICS® document template or a z/OS® UNIX System Services HFS file to provide a static response to an HTTP request from a Web client.

The base components of CICS Web support must be configured before you start, as described in Configuring CICS Web support base components.
The following task-specific components of CICS Web support are used for this task:
Figure 1 shows the architecture elements for this CICS Web support task.
Figure 1. Static HTTP responses
Static HTTP responses. The elements used are explained in the text following the figure. The topic linked to before the figure explains how they work together.

HTTP request and response processing for CICS as an HTTP server explains how the process elements work together.

  1. Consider security issues for this CICS Web support task. Start of changeFor application-generated responses, CICS can implement HTTP basic authentication for a connection, where the user must supply an ID and password. (Basic authentication does not operate for items delivered as a static response.) You can use the user ID to control access to individual resources. If you need to protect information passed over the Internet (including the user IDs and passwords used for basic authentication), consider using Secure Sockets Layer (SSL). For more information, see Security for CICS Web support.End of change
  2. If you want to use a z/OS UNIX System Services HFS file to provide a response, create the file and place it in an appropriate location of your choice in the HFS file system. When this response is identified by a URIMAP definition that matches the Web client's request, CICS retrieves the file and carries out appropriate code page conversion.
    1. Do not include any HTTP headers or status line information in the HFS file. CICS generates the required information when the response is sent. The HFS file only provides the body of the response.
    2. The location of the file is significant if you want to use path matching, as described later in this topic. If you do not want to use path matching, the location of the file does not need to have any relationship to the URL of the request.
    3. The CICS region must have permissions to access z/OS UNIX, and it must have permission to access the HFS directory containing the file, and the file itself. Java™ Applications in CICS explains how to grant these permissions.
  3. If you want to use a CICS document template to provide the response, create the document template, following the instructions in the CICS Application Programming Guide. The document template is defined using a DOCTEMPLATE resource definition. The document template can be held in a partitioned data set, a CICS program, a file, a temporary storage queue, a transient data queue, an exit program or a z/OS UNIX System Services HFS file. When this response is identified by a URIMAP definition that matches the Web client's request, CICS creates a document using the template, retrieves the document, and carries out appropriate code page conversion.
    1. Do not include any HTTP headers or status line information in the document template. CICS generates the required information when the response is sent. The document template only provides the body of the response.
    2. A query string that consists of name and value pairs can be used as a symbol list and substituted into a document template. (The query string cannot be used in this way if it has already been used for URIMAP matching, as part of the PATH attribute in the URIMAP definition.) The recommended way to get the client to send a query string of the expected format in the URL, is to send an HTML form with the GET method for the user to fill in. Any of the names in the query string can be coded in the document template as a symbol, and when the template is used, CICS substitutes each symbol for the value specified in the query string. For example, if you have obtained a query string that includes a name and value pair username=Peter, you can use this in your document template by coding username as a symbol:
      Welcome to the finance system, &username;.
      The resulting static response delivered to the user reads
      Welcome to the finance system, Peter.
      Note: Symbols in document templates are case-sensitive. Specify the name using the same case as is present in the original query string.
      Any name and value pairs that do not correspond to symbols in the document template are ignored.
  4. Identify the media type (type of data content) that is provided by the HFS file or CICS document template. (See IANA media types and character sets for more information about media types.) Note that when you use a URIMAP definition to send a static response, the use of quality factors (the "q" parameter) is not supported. Quality factors can be used to choose among a client's list of acceptable media types or character sets, as specified in Accept headers. If you want to carry out this type of analysis, an application-generated response can be used instead.
  5. Identify the information that CICS requires for code page conversion of the static response. Code page conversion only takes place where a text media type is specified. Code page conversion for CICS Web support explains the processes for code page conversion.
    1. Identify the character set into which CICS should convert the static response before sending it to the Web client. The IANA character sets supported by CICS for code page conversion are listed in HTML coded character sets.
    2. Identify the IBM code page (EBCDIC) in which the document template or HFS file providing the response body is encoded.
    For a static response, this information is specified in the URIMAP definition for the request.
  6. Decide on the URL that the Web client will use for each request, including the scheme, host and path components, and any query string. The components of a URL explains each of these components and how they are delimited. URLs for CICS Web support explains the factors and limitations to consider in choosing a URL for CICS Web support.
  7. Decide whether you want to use path matching in the URIMAP definition. If so, plan your request URLs, and arrange the names of your CICS document templates or the locations of your HFS files to support this. In path matching, a wildcard character is used in the path component of the URIMAP definition, and also in the name of the CICS document template or HFS file that is specified by the URIMAP definition. The portion of the path that is covered by the wildcard character is used to select the document template or HFS file to provide the response.
    1. For CICS document templates, the portion of the path that is covered by the wildcard character is substituted as the last part of the template name. You can create a collection of document templates whose names begin in the same way, and access them using request URLs whose paths begin in the same way, through a single URIMAP definition.
    2. For HFS files, the portion of the path that is covered by the wildcard character is substituted as the last part of the HFS file name. You can store a number of HFS files in the same directory, and access them using request URLs whose paths begin in the same way, through a single URIMAP definition. Bear in mind that because a URIMAP definition must specify a type of data content (the MEDIATYPE attribute), a single URIMAP definition can only handle a group of HFS files that produce the same type of data content.
  8. Decide on the port that will be used for the requests. Reserving ports for CICS Web support has more information about ports that can be used by CICS Web support. For HTTP, the default port number is 80, and for HTTPS (with SSL), the default port number is 443. Port numbers that are not the default for a scheme need to be specified explicitly in the URL of requests. If you prefer, you can allow a request to use any port that is associated with CICS Web support.
  9. If you do not yet have a TCPIPSERVICE definition for the port on which the requests are received, follow the procedure in Creating TCPIPSERVICE resource definitions for CICS Web support to set up a TCPIPSERVICE definition. The name of the relevant TCPIPSERVICE definition is specified in the URIMAP definition for the request. Specifying no TCPIPSERVICE definition means that requests matched by the URIMAP definition can use any port for which a TCPIPSERVICE definition exists.
  10. Set up a URIMAP definition to handle each request. Follow the procedures in Starting a URIMAP resource definition for any requests for CICS as an HTTP server and Completing a URIMAP definition for a static response to an HTTP request for CICS as an HTTP server. The URIMAP definition can identify either a HFS file or a document template.
  11. Check the error handling procedures for this CICS Web support task.
    1. Check the behavior of the analyzer program associated with the TCPIPSERVICE definition for the port on which the requests are received. If URIMAP matching fails for a request, the request is passed on to the analyzer program. If the port is used only for static responses, the CICS-supplied default analyzer program DFHWBAAX provides suitable error handling. Otherwise, the choice of analyzer program is likely to depend on the requirements of user application programs, and you might need to customize it to provide suitable error handling for static responses. Analyzer programs has more information about what you can do using an analyzer program.
    2. Ensure that the user-replaceable Web error programs which are involved in your architecture provide appropriate responses to the Web client. Web error program explains the situations in which DFHWBEP and DFHWBERX are used, and tells you how to customize the responses that they provide.
End of change