XWBOPEN enables systems administrators to specify proxy servers
that should be used for HTTP requests by CICS® as an HTTP client, and to apply a
security policy to the host name specified for those requests. XWBOPEN is
called during processing of an EXEC CICS WEB OPEN command,
which is used by an application program to open a connection with a server.
CICS itself does not have any requirements
concerning the use (or otherwise) of proxy servers for HTTP requests by CICS as
an HTTP client, and CICS does not apply any security policy for those requests.
It is your responsibility to set up these facilities if they are required
by your system or organization.
The
EXEC CICS WEB
OPEN command instructs the CICS Web domain to open a connection with a server.
XWBOPEN is called before the connection is opened. The host name for the connection
(for example,
www.example.com), which is specified by the
HOST option on the
EXEC CICS WEB OPEN command, is passed
as the UEPHOST parameter to the user exit program for checking. At this point,
the user exit program can be used for two purposes:
- To determine whether the HTTP request needs to use a proxy server,
and return the name of any proxy server that is required. If a proxy server
is needed, return code UERCPROX is used, and the name of the proxy server
is returned to the CICS Web domain (in the buffer identified by UEPPROXY)
and used to make the connection to the server. If no proxy server is needed,
return code UERCNORM is used.
- To apply a security policy to the host name. Return code UERCBARR
indicates that access to the host is not permitted. If access to the host
is not permitted, an INVREQ response is returned to the WEB OPEN command,
and the application programmer should abandon the attempt to open that connection.
If you want to apply a security policy for individual resources, as well as
(or instead of) for the host, the XWBSNDO user exit on the EXEC CICS WEB
SEND and EXEC CICS WEB CONVERSE commands can be used to
apply a security policy to the path component of the URL.
The XWBOPEN user exit does not support the use of EXEC
CICS commands.
The sample programs DFH$WBPI and DFH$WBEX,
and the associated copybook DFH$WBGA, show you how to set up proxy server
information or a security policy in a global work area. For example, if all
the requests from your CICS system should use a single proxy server, you can
specify the proxy server name as an initialization parameter. If you use a
number of proxy servers or want to apply a security policy to different host
names, you could load or build a table that matches host names to appropriate
proxy servers or marks them as barred, which could then be used as a look-up
table during processing of the EXEC CICS WEB OPEN command.
The sample programs can be run during program list table post initialization
(PLTPI) processing, or at any point before you expect the EXEC CICS WEB
OPEN command to be used.
Exit XWBOPEN
- When invoked
- During processing of an EXEC CICS WEB OPEN command.
- Exit-specific parameters
- UEPHOST (Input supplied by CICS)
- The address of a field containing the host name specified in the HOST
option of the WEB OPEN command.
Note: The host name is converted into lower
case when it is saved in this field. Your user exit program should take this
into account when matching the host name.
- UEPHOSTL (Input supplied by CICS)
- The address of a field containing the halfword length of the host name.
- UEPPROXY (Output supplied by user exit)
- The address of a field containing the address that points to the proxy
server name. On input to the user exit program, the parameter is set to the
address of a field containing the address of a 2046-byte area. You can place
the proxy server name in this area, and leave the address in UEPPROXY unchanged.
Alternatively, you can place the proxy server name in your own area, and replace
the address in UEPPROXY with the address of a field containing the address
of your own area.
- UEPPROXYL (Output supplied by user exit)
- The address of a field containing the halfword length of the proxy server
name.
- Return codes
- UERCNORM
- A proxy server is not needed for this HTTP request, and the host name
is not barred.
- UERCPROX
- A proxy server is needed for this HTTP request. UEPPROXY has been set
to the name of the required proxy server, and UEPPROXYL has been set to the
length of the proxy server name.
- UERCBARR
- The host name of the server is barred.
- UERCERR
- An error occurred in exit processing.
- XPI calls
- All XPI calls can be used.
- API and SPI commands
- No EXEC CICS commands can be used.