Writing Web-aware application programs for XCICS as an HTTP server

In XCICS, Web-aware application programs are programs that use EXEC CICS WEB commands to interact with a Web client or a server through XCICS. For XCICS as an HTTP server, these programs can receive and analyze HTTP requests and provide application-generated responses to the Web client.

Before you start to code Web-aware application programs for XCICS as an HTTP server, read the topic HTTP requests and response processing (as server)" so that you are aware of the processing stages that can be involved.

For each HTTP request that requires an application-generated response, XCICS calls the Web-aware application program that is specified on the URIMAP definition for the request, or by the analyzer program, if an analyzer is used. If you use a URIMAP definition to specify the application program, you can select a single application program to service all requests using a particular URL. If you are using an analyzer program either instead of, or in addition to, the URIMAP definition, it can carry out analysis on the request and decide on an alternative application program.

Remember: Web-aware application programs that use the EXEC CICS WEB commands must run in the XCICS region where the Web client's request is received. However, they may link to application programs in other XCICS regions, for example to perform business logic.

For XCICS as an HTTP server, when an application program has sent a response to a request and returned control to XCICS, it does not wait for | further requests from the Web client. If you need to share information between different programs (or new instances of the same program) across a series of requests and responses, you can do this using XCICS-managed resources, or using elements of the requests sent by the Web client.

You can code each of your Web-aware application programs to perform some or all of the following actions for processing an HTTP request:

Retrieve any information that your application program needs from the request line (including the request URL), using the WEB EXTRACT command. "Examining the request line for an HTTP request" tells you how to do this. The request line includes the HTTP method, which indicates the action that the application program should take. You can also design the path component of a request URL to provide processing information to the application program. If there is a query string in the request URL, the application program can extract it as a whole for processing.

2.	Read or browse the HTTP headers for the request, using the HTTP header commands. "Examining the HTTP headers for a message" tells you how to do this. The information in the HTTP headers might be useful to the application program for processing and responding to the request.

3.	Retrieve any technical information about the request that your application program needs to use. You can use EXEC CICS commands to access information about the TCP/IP environment and security options. "Retrieving technical and security information about an HTTP request" tells you how to do this.

If the request contains form data that you want to extract, read or browse the data using the form field commands. "Examining form data in an HTTP request" in topic 2.3.4 tells you how to do this. The data can be in the body of the request or as a query string in the URL, and XCICS can extract the data from either of these locations.

If the request has a message body that you need to use, receive it into a buffer using the WEB RECEIVE command. "Receiving the entity body of an HTTP request" in topic 2.3.5 tells you how to do this. XCICS does not require you to receive a message body if one is present, and some requests do not have a message body.

Execute the business logic for the request processing, using the information you have gathered. You might want to involve other application programs to perform processing. A Web-aware application program can produce a response to the HTTP request based on information that it receives from non-Web-aware programs. It is advisable to separate the business logic from the presentation logic. In a Web-aware application, presentation logic controls the interaction with the Web client.

7.	Write HTTP headers for the response, using the WEB WRITE HTTPHEADER command. "Writing HTTP headers for a response" tells you how to do this. XCICS automatically provides some required headers, such as the Date header. You can provide additional headers for other purposes.

Produce an entity body, or message body, which is the content of the HTTP response. "Producing an entity body for an HTTP message" tells you how to do this. The entity body can be formed from a XCICS document (which is created using the EXEC CICS DOCUMENT application programming interface) or from a buffer of data supplied by the application program.

Send the response to the Web client using the WEB SEND command. "Sending an HTTP response from XCICS as an HTTP server" in topic 2.3.8 tells you how to do this. You need to select a suitable status code and reason phrase, and specify the entity body. XCICS assembles the response using these items and the HTTP headers. If you want to use chunked transfer-coding, you also need to follow the special instructions in "Using chunked transfer-coding to send an HTTP request or response".

10.	If you expect to exchange further requests and responses with this Web client, and you need to share data across the request sequence, use the suggestions in "Managing application state across an HTTP request sequence" to achieve this.

11.	When EXEC CICS WEB commands are used for XCICS as an HTTP server, they do not have the SESSTOKEN option. The SESSTOKEN option indicates that a command is being used for XCICS as an HTTP client.