|
You can use XCICS Web support to enable Web clients to interact with XCICS applications that use a COMMAREA interface to communicate with other programs. You can write a Web-aware application program that links to the application and uses its output to provide HTTP responses. Alternatively, you can use a converter program to convert the input from the Web client into a suitable COMMAREA, and convert the output from the application into HTML to provide the response.
The following task-specific components of XCICS Web support are used for this task:
| • | TCPIPSERVICE resource definitions |
| • | URIMAP resource definitions |
| • | COMMAREA application programs |
| • | Either: Web-aware application programs, using the EXEC XCICS WEB programming interface, that link to the COMMAREA application programs and use their output |
| • | Or: Converter programs that can provide suitable COMMAREA input and convert the output from the application programs into HTML |
| • | Alias transactions to cover the user application programs involved in this process |
"HTTP requests and response processing (as server)" explains how the process elements work together.
| 1. | Decide whether you want to write a Web-aware application program that handles the HTTP request and links to the COMMAREA application program; or whether you want to write a converter program to convert the input from the Web client into a suitable COMMAREA, and convert the output from the application into HTML to provide the response.
Note: For COMMAREA applications that use a converter program, XCICS cannot provide the fullest possible assistance with structuring responses and with HTTP protocol compliance. To take advantage of all the available XCICS Web support facilities, it is recommended that you use Web-aware applications to handle requests where possible. |
| a. | If you want to use a Web-aware application program, follow the steps in "Providing dynamic HTTP responses with Web-aware application programs" . Code your Web-aware application program to link to the COMMAREA application and use its output. The only task that cannot be performed by a Web-aware application program, but can be performed by a converter program, is receiving information that an analyzer program has created to pass to the next processing stage (in a user token or shared work area). This is unlikely to be a consideration when you are developing a new XCICS Web support application. |
| b. | If you want to use a converter program, follow the steps in this topic. |
| 2. | Decide how the analyzer program associated with the TCPIPSERVICE definition should be used, and select an appropriate program. "Analyzer programs" has more information about what you can do using an analyzer program. URIMAP definitions or analyzer programs can be used to map requests from Web clients to appropriate converter programs and user-written application programs. For non-Web-aware applications, even if you have URIMAP definitions, you need to use a customized analyzer program in the processing path for the request in the following circumstances: |
| a. | If you require nonstandard code page conversion. |
| b. | If you need to communicate any information to a converter program in addition to the standard input. A user token is provided, which the analyzer and converter programs can use to exchange either a small amount of information, or the address of a shared work area containing more information. |
| c. | If you require monitoring or audit actions, which can be carried out by an analyzer program. |
| d. | If you need to make dynamic changes to elements of the process such as the converter program that is used, the application program that handles the request, or the alias transaction and user ID used for the request. |
| 3. | Use the information in "Converter programs" to create a suitable converter program. XCICS passes the Web client's request to the converter program in a 32K block of storage. (If the request does not fit, it is truncated.) The converter program is called twice, first for the decode function, which receives the request and passes it to the application program, and next for the encode function, which receives the application's output and creates an HTTP response. The tasks carried out by a converter program are:
Decode function
- Receive the HTTP request in a storage area, along with any additional information supplied by the URIMAP definition or analyzer program in a COMMAREA.
- Process the HTTP request and convert relevant elements into suitable COMMAREA input for the application program | (in the same storage area or a new one).
Encode function
- Receive the output from the application program.
- Construct the HTTP response in a COMMAREA.
- Pass the HTTP response to XCICS for sending to the Web client. |
| 4. | Decide on the URL that the Web client will use for each request, including the scheme, host and path components, and any query string. |
| 5. | Decide on the port that will be used for the requests. |
| 6. | Select an alias transaction ID for the user application programs that are involved with this task. The default alias transaction is CWBA. You can create your own alias transaction following the instructions "Creating TRANSACTION resource definitions" . You can use the URIMAP definition or an analyzer program to specify an alias transaction for each HTTP request. |
| 7. | Consider security issues for this XCICS Web support task. For application-generated responses, XCICS 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 XCICS Web support". |
| 8. | Set up a URIMAP definition to handle each request. Follow the procedures in "Starting a URIMAP resource definition for any requests for XCICS as an HTTP server" in topic 2.4.3 and "Completing a URIMAP definition for an application response to an HTTP request for XCICS as an HTTP server". It is possible to pass HTTP requests directly to an analyzer program without using URIMAP definitions, following the same process that XCICS Web support used before IBM CICS TS 3.1. However, using URIMAP definitions can make it easier to manage HTTP requests. Without URIMAP definitions, if you want to change the way in which XCICS responds to a particular HTTP request, you need to change the logic in the analyzer program. With URIMAP definitions, you can perform these changes dynamically as a system management task. |
| 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" 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. |
|
