For CICS® as
an HTTP client, CICS is
the Web client, and it communicates with an HTTP server. A user-written application
program sends requests through CICS to the HTTP server, and receives the
responses from it. CICS maintains a persistent connection with the server.
A session token is used on the commands issued by the application program
to identify the connection.
An application program that makes an HTTP request and receives a response
must use the EXEC CICS WEB API commands to explicitly direct
the interaction with the server. A Web-aware application
program could be used to make an HTTP request, and then process the results
to provide information to an application that is not Web-aware.
The application program that initiates the HTTP request should be designed
to process whatever CICS receives from the server in response to that request,
which might include error responses, redirection to another URL, embedded
hypertext links, HTML forms, image source, or other items that request an
action from the application program. CICS can perform code page conversion for
requests and responses, if required.
Figure 1 shows
the process described in this topic.Figure 1. Processing for CICS as an HTTP
client
Processing for CICS as an HTTP client takes place as follows:
- The application program initiates a connection with the HTTP server
through CICS. The
application program does this by issuing the EXEC CICS WEB
OPEN command. A URIMAP resource definition that you have created can be referenced
to specify the scheme and host name for the connection, or the application
program can provide this information. (The CICS Resource
Definition Guide has more information about URIMAP definitions.)
An application may have more than one connection open at a time.
- CICS establishes
the connection with the server. Using the information provided by the
application program, CICS opens a TCP/IP connection on a socket and contacts
the server. During this process, the XWBOPEN user
exit may be used (if it has been activated using the ENABLE PROGRAM command)
to redirect the application program's requests through a proxy server, if
required, and to apply a security policy to connections to the host. CICS queries
the HTTP version of the server when the connection is opened, and uses this
information for subsequent communications. CICS also returns the HTTP version information
to the application program, to be checked if you plan to write HTTP headers
or send chunked messages. When the TCP/IP connection is established, CICS returns
a session token to the application program to uniquely identify the connection.
This session token is used on all the remaining commands issued by the application
program concerning that connection. Session tokens explains more about the session token.
- The application program may write HTTP headers for its request. User-written
HTTP headers can be built using the WEB WRITE HTTPHEADER command and stored
ready for sending.
- The application program specifies components of the request line. The
request method, path information and query string are specified using the
WEB SEND or WEB CONVERSE command. The HTTP version
for the request is supplied by CICS.
- The application program may produce an entity body for its request. The
content of the request is specified on the WEB SEND or WEB CONVERSE command. It can be formed from a CICS document (using the DOCUMENT interface),
or from the contents of a buffer. If the server is at HTTP/1.1, chunked transfer-encoding
may be used for a request body formed from the contents of a buffer (but not
for a CICS document).
- The application program initiates transmission of the request.
When the application program issues the WEB SEND or WEB CONVERSE command,
the request is passed to CICS for sending across the connection specified by
the session token.
- CICS generates
some required HTTP headers and adds them to the request, then sends the request
to the server. The values for some of the headers
are generated directly by CICS (such as the Date header), and the values of others
are based on information provided by the application program (using the WEB
SEND command) or by a URIMAP definition. During sending of the request, the
XWBSNDO user exit is called to apply a security policy for the individual
request, if required.
- The server receives and processes the request, and provides a response. CICS passes
the response to the application program.
- The application program examines the response. The WEB READ HTTPHEADER
command, or the HTTP header browsing commands, can be used to examine the
headers of the response. The WEB RECEIVE or WEB CONVERSE command receives
the body of the response (if there is one), which can be processed by the
application program, and the response's status code and status text.
- The application program may initiate further requests and responses. If
the server supports persistent connections, the connection identified by the
session token remains open for further requests.
- The application program initiates closing of the connection to the
server. When all the requests and responses are completed, the application
program issues a WEB CLOSE command, and CICS closes its end of the TCP/IP connection.
If the application program does not issue a WEB CLOSE command, the connection
is closed at end of task.
During this process, code page conversion is usually needed when messages
enter and leave the CICS environment, so that CICS Web support processing and user-written
applications (which typically use an EBCDIC encoding) can communicate with
HTTP servers (which typically use an ASCII encoding). Code page conversion for CICS Web support explains when and how this
takes place. The type of code page conversion that is required can be specified
using options on the WEB SEND, WEB RECEIVE or WEB CONVERSE commands. For CICS as
an HTTP client, the default is that code page conversion does take place when
messages are sent and received.