The DFHWBCLI Web Client Interface

DFHWBCLI is a CICS®-supplied utility program that you can invoke by EXEC CICS LINK to provide web client services or outbound HTTP. This program is deprecated. The functions of the DFHWBCLI Web Client Interface are retained for compatibility reasons. To gain enhanced functionality, you can upgrade existing HTTP client applications that used the DFHWBCLI interface, to use the EXEC CICS WEB API commands for client requests (with the SESSTOKEN option). When you develop new web applications, you should use the EXEC CICS WEB API commands and associated URIMAPs; do not use DFHWBCLI.

Stabilized feature: The DFHWBCLI Web Client Interface is stabilized. Consider moving to use the CICS WEB API with Session tokens. See also Stabilization notices.

One important difference to note is that in the EXEC CICS WEB API, the use of a proxy server is specified by a user exit on the WEB OPEN command (XWBOPEN), and the URL of the proxy server is supplied by that user exit. Making HTTP requests through CICS as an HTTP client describes how HTTP client requests can now be made.

If you want to use DFHWBCLI, you must set up CICS to use a name server. See Configuring CICS web support components.

To use DFHWBCLI, you must link to it with a commarea that contains a parameter list whose contents are mapped by the following copybooks:

DFHWBCLD for Assembler
DFHWBCLO for COBOL
DFHWBCLL for PL/I
DFHWBCLH for C

The parameters have the following meanings:

WBCLI_VERSION_NO

a one-byte binary number that specifies the version number of this parameter list. It should be set to the value specified by the symbolic constant WBCLI_VERSION_CURRENT.

WBCLI_FUNCTION

A one-byte binary number that specifies the function that you want DFHWBCLI to execute. It should be set to one of the following values:

0 (WBCLI_FUNCTION_CONVERSE): Send an HTTP request to a target server and receive the corresponding response
1 (WBCLI_FUNCTION_SEND): Send an HTTP request to a target server and return control without waiting for the response
2 (WBCLI_FUNCTION_RECEIVE): Wait for and receive the response to the HTTP request sent by a previous SEND function
3 (WBCLI_FUNCTION_INQUIRE_PROXY): Request the name of the proxy server that was specified in the INITPARM=(DFHWBCLI,'PROXY=http://....') system initialization parameter
4 (WBCLI_FUNCTION_CLOSE): Close the connection previously established by a SEND function, but without waiting for the HTTP response

WBCLI_METHOD

A one-byte binary number that specifies the HTTP method to be specified in the HTTP request. It should be set to one of the following values:

1 (WBCLI_METHOD_GET)
2 (WBCLI_METHOD_POST)

WBCLI_FLAGS

A one-byte binary bitstring that can be used to specify options associated with the HTTP request and its expected response. The bits in the bitstring may be set to the following values:

1... .... (WBCLI_OFFSET_MODE): Pointer values in the parameter list are specified as offset values from the start of the parameter list. This implies that all the targets of such pointers are contained within the commarea.
.1.. .... (WBCLI_DOCUMENT): The HTTP request body is a CICS document which was created by the DOCUMENT CREATE command and is specified by the document token in WBCLI_REQUEST_DOCTOKEN
..1. .... (WBCLI_USE_PROXY): The HTTP request is to be sent via the proxy server whose URL is specified in WBCLI_PROXY_URL_PTR
...1 .... (WBCLI_SET_RESP_BUFFER): CICS is to acquire a suitably sized buffer to contain the HTTP response body, and return its address in WBCLI_REQUEST_BODY_PTR
Note: This address is not made into an offset, regardless of the setting of WBCLI_OFFSET_MODE
.... ..1. (WBCLI_NATIVE_REQUEST_BODY): The application will provide the HTTP request body in its native form, and CICS does not need to translate it from EBCDIC to ASCII
.... ...1 (WBCLI_NATIVE_RESPONSE_BODY): The application will handle the HTTP response body in its native form, and CICS does not need to translate it from ASCII to EBCDIC

WBCLI_RESPONSE

A halfword binary number that is set to one of the following values to indicate the outcome of the function:

0 (WBCLI_RESPONSE_OK)
4 (WBCLI_RESPONSE_EXCEPTION)
8 (WBCLI_RESPONSE_DISASTER)

WBCLI_REASON

A halfword binary number that is set to one of the following values to qualify the response code:

1 (WBCLI_REASON_INVALID_URL): The format of the URL located by WBCLI_URL_PTR is invalid, or the host location cannot be resolved by the nameserver
2 (WBCLI_REASON_INVALID_HEADER): One of the HTTP headers in the list located by WBCLI_HEADER_PTR is not in the correct format
3 (WBCLI_REASON_INVALID_DOCUMENT): The document token specified in WBCLI_REQUEST_DOCTOKEN does not locate a valid CICS document
4 (WBCLI_REASON_GETMAIN_ERROR): An error occurred while DFHWBCLI was attempting to obtain storage for one of its internal workareas
5 (WBCLI_REASON_PROXY_ERROR): The proxy server located by WBCLI_PROXY_URL_PTR could not be found or returned an error response
6 (WBCLI_REASON_SOCKET_ERROR): An unexpected response was returned when performing a socket operation
7 (WBCLI_REASON_HTTP_ERROR): An unexpected HTTP response was returned by the server
8 (WBCLI_REASON_TRANSLATE_ERROR): An error was returned while CICS was translating data between the host code page and the server code page. This could be because the required translation is not supported by CICS
9 (WBCLI_REASON_TRUNCATED): The length of the user-provided response buffer specified in WBCLI_RESPONSE_BODY_LEN is insufficient to contain the response returned by the server. Data in excess of this length has been discarded.
10 (WBCLI_REASON_INVALID_HEADER_LENGTH): The length of the user-provided request header specified in WBCLI_HEADER_LEN was invalid.
11 (WBCLI_REASON_INVALID_BODY_LENGTH): The length of the user-provided request body specified in WBCLI_REQUEST_BODY_LEN was invalid.

WBCLI_SESSION_TOKEN

An opaque eight-byte binary token that represents the connection established with the HTTP server. It is set by the SEND function and is required by the RECEIVE and CLOSE functions. It is not used by the other functions.

WBCLI_URL_PTR

The address of an EBCDIC character string that contains the URL (Uniform Resource Locator) of the destination HTTP server. The URL must be fully qualified: that is, it must begin with 'http://' or 'https://'.

WBCLI_URL_LEN

A fullword binary number that contains the length of the URL located by WBCLI_URL_PTR.

WBCLI_PROXY_URL_PTR

The address of an EBCDIC character string that contains the URL (Uniform Resource Locator) of a proxy server that may be required to access remote sites outside your firewall. The URL must be fully qualified: that is, it must begin with 'http://'. To use the proxy, you must also set the WBCLI_USE_PROXY flag.

WBCLI_PROXY_URL_LEN

A fullword binary number that contains the length of the URL located by WBCLI_PROXY_URL_PTR.

WBCLI_HEADER_PTR

The address of list of HTTP headers that are to be sent with the HTTP request. The headers must be encoded in EBCDIC, in the following form:

headername: headervalue§headername: headervalue§ ...

where

headername: is the name of the header
headervalue: is the value of the header

The colon (:) and space that separate these two should be present as shown; the '§' shown here should be replaced by one or more of the following delimiters:

carriage return (X'0D')
line feed (X'25')
new line (X'15')
field separator (X'1E')

Note: These delimiters are not used when the headers are sent: CICS uses the architecturally correct HTTP delimiters.

You may code as many headers in the list as you need. However, you must not include the following headers, as CICS will provide them:

Host
User-Agent
Content-Length
Content-Type

You do not need to provide a delimiter following the last header in the list.

WBCLI_HEADER_LEN

A fullword binary number that contains the length of the list of headers located by WBCLI_HEADER_PTR.

WBCLI_REQUEST_DOCTOKEN

A 16-byte binary document token, created by the DOCUMENT CREATE command, that represents a CICS document that is to be used as the HTTP request body. You must indicate that you are using this token by setting the WBCLI_DOCUMENT flag.

WBCLI_REQUEST_BODY_PTR

The address of an EBCDIC character string that contains the entire contents of the HTTP request body. This parameter is used when the WBCLI_DOCUMENT flag is not set.

WBCLI_REQUEST_BODY_LEN

A fullword binary number that contains the length of the request body that is located by WBCLI_REQUEST_BODY_PTR.

WBCLI_RESPONSE_BODY_PTR

The address of a buffer in which DFHWBCLI returns the HTTP response body from the server.

If flag WBCLI_SET_RESP_BUFFER is not set, this address and WBCLI_RESPONSE_BODY_LEN must be set by the caller. If this buffer is not large enough to contain the response body, it is truncated.
If flag WBCLI_SET_RESP_BUFFER is set, this address and WBCLI_RESPONSE_BODY_LEN are ignored. CICS obtains a new buffer which is large enough to contain the entire response, and its address is returned in this field. This address is never converted into an offset, whatever the value of the WBCLI_OFFSET_MODE flag.

Normally, CICS frees the storage at this address when the task that invokes DFHWBCLI ends. Alternatively, you can free the storage earlier by issuing an EXEC CICS FREEMAIN command in your application program. You are advised to do so when DFHWBCLI is called repeatedly in a long-running task, in order to prevent CICS going short-on-storage.

WBCLI_RESPONSE_BODY_LEN

A fullword binary number that contains the length of the response buffer located by WBCLI_RESPONSE_BODY_PTR.

On input, if WBCLI_SET_RESP_BUFFER is not set, use this parameter to specify the length of the user-provided buffer.
On output, it contains the actual length of the response body that was returned.

WBCLI_MEDIATYPE

A 40-byte EBCDIC blank-padded character string that contains the IANA media type (also known as the MIME type) of the HTTP body.

On input, use this parameter to specify the media type of the HTTP request body. This media type will be sent in the HTTP Content-Type header
On output, it will contain the media type of the HTTP response body, as received in the HTTP Content-Type header.

The media type must be specified for SEND requests that use the POST method (requests where WBCLI_FUNCTION_SEND and WBCLI_METHOD_POST are both set).

WBCLI_CHARSET

A 40-byte EBCDIC character string that contains the IANA character set of the HTTP body.

On input, if WBCLI_NATIVE_REQUEST_BODY is not set, use this parameter to specify the name of the character set into which you want CICS to translate the HTTP request body. The character set you specify is used to qualify the media type in the HTTP Content-Type header. If you do not specify a value, the default of iso-8859-1 is assumed only if WBCLI_MEDIATYPE includes the value TEXT.
On output, it will contain the character set of the HTTP response body as received in the HTTP Content-Type header. This character set is used to translate the HTTP response body (unless the WBCLI_NATIVE_RESPONSE_BODY is set).

WBCLI_HOST_CODEPAGE

A 10-character EBCDIC blank-padded character string that contains the name of the EBCDIC code page used by your application. It is used in combination with WBCLI_CHARSET to determine what translation is to be performed on the HTTP document bodies (unless translation is suppressed by the WBCLI_NATIVE_REQUEST_BODY or WBCLI_NATIVE_RESPONSE_BODY flags). If it is omitted, CICS uses code page 037.

WBCLI_HTTP_STATUS_CODE

A three-digit numeric EBCDIC character string in which the HTTP status code is returned. This indicates whether the HTTP request was successful or not. The 200 status code is used for a normal response, and other status codes in the 2xx range also indicate success. Other status codes indicate that there is an error that prevents fulfilment of the request, or that the client needs to do something else in order to complete its request successfully, such as following a redirection URL.