HTTP client open exit XWBOPEN

With XWBOPEN, you can specify proxy servers that are used for HTTP requests by CICS® as an HTTP client. You can also 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. XWBOPEN is also called during processing of an EXEC CICS INVOKE SERVICE command.

CICS 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. You have 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, you can use the user exit program for two purposes:

To determine whether the HTTP request needs to use a proxy server, and to 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 and a NOTAUTH response is returned to the WEB OPEN command. The application programmer must stop trying to open that connection. If you want to apply a security policy for individual resources, as well as (or instead of) for the host, use the XWBSNDO user exit on the EXEC CICS WEB SEND and EXEC CICS WEB CONVERSE commands 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, with 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 must 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 can load or build a table that matches host names to appropriate proxy servers or marks them as barred, which can then be used as a lookup 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 or EXEC CICS INVOKE SERVICE command.

Exit-specific parameters

UEPHOST (Input supplied by CICS): The address of a field containing the host name, IPv4, or IPv6 address specified in the HOST option of the WEB OPEN command.
Note: The host name is converted into lowercase when it is saved in this field. Your user exit program must take into account this conversion 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. The proxy server name must be in URL format. 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.
UEPHOSTT (Input supplied by CICS): The address of a 1-byte code that indicates the host type contained in the UEPHOST parameter.
Note: Binary 01 indicates host name, binary 02 indicates an IPv4 address, and binary 03 indicates an IPv6 address.

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.