Routing a Web client's request to an AOR

You cannot use the EXEC CICS® WEB API in an AOR; you can use it only in the router region. If you want to use a Web-aware application to respond to requests, one solution is to code your presentation logic in the Web-aware application program (which executes in the router region), and code your business logic (which executes in the AOR) to be entirely independent of presentation. The Web-aware application program is named as the program that handles the request, and it must manage its own communication with the application program that carries out the business logic. HTTP request and response processing for CICS as an HTTP server explains the processing stages for Web-aware applications.

For non-Web-aware applications, a converter program in the router region can be used to produce an HTTP response from information supplied by an application program in an AOR. Figure 1 shows the processing stages and task structure associated with a request from a Web client when a non-Web-aware application program is executed in an application-owning region.
Figure 1. How CICS Web support routes non-Web-aware application requests to an AOR
This figure illustrates the processing stages and task structure when processes an HTTP request, and routes the application request to an application-owning region.
The corresponding stages for the CICS business logic interface are shown in Figure 2.
Figure 2. How the CICS business logic interface routes application requests to an AOR
This figure illustrates the processing stages and task structure when the processes an HTTP request, and routes the application request to an application-owning region.

CICS uses Distributed Program Link (DPL) to invoke the application program in the AOR; the application executes under the mirror task. For information about DPL, see the CICS Intercommunication Guide.

To execute a business application in an AOR:
  • You must specify the REMOTESYSTEM attribute, or specify DYNAMIC(YES) on the PROGRAM definition for the application program. If you specify DYNAMIC(YES), the dynamic routing program determines where the application program executes.
  • Other resource definitions (for the analyzer program, the Web-aware application program or converter program, and the alias transaction) must specify that they execute in the router region.
  • You must define an MRO or APPC connection between the router region and the AOR.

If the application program which executes in the AOR is designed to be entirely independent of presentation, it returns output to the Web-aware application program or the converter program, which then constructs the HTML output. Alternatively, if you are using a converter program, you might want to use the EXEC CICS DOCUMENT API in the AOR to construct HTML output. The converter program can convert this output into a COMMAREA containing a complete HTTP response, to be sent by CICS Web support.

You must provide your own mechanism for transferring the application program's output back to the router region. The output can be transferred in a COMMAREA. Alternatively, you can use some other mechanism, such as a temporary storage queue, and transfer a token representing the data in that mechanism. The program in the router region can use the token to retrieve the output, then process it and pass it to the Web client. CICS provides a sample state management program (DFH$WBSR) that you can use to do this. It is described in Reference information for DFH$WBST and DFH$WBSR, state management samples (the other sample, DFH$WBST, creates an affinity, and so is not suitable for use in a CICSPlex®).