EXTRACT WEB

Description

For CICS as an HTTP server, WEB EXTRACT enables an application to obtain information about the most recent HTTP request that has been made to CICS by a Web client and assigned to the application for handling.

For CICS as an HTTP client, when the SESSTOKEN option is specified, the command enables an application to obtain information about a connection that it has opened with a server. The information returned to the application comprises global information about the connection, such as the host name of the server and its HTTP version. Information about specific requests made by the application, and responses made by the server, is not available using this command. The WEB RECEIVE command is used to receive information from a server response.

Options

HOST(data-area)

For CICS as an HTTP server, HOST specifies a buffer to contain the host component of the URL, as specified either in the Host header field for the request or in the request line (if an absolute URI was used for the request). The port number is presented separately using the PORTNUMBER option.

For CICS as an HTTP client, with the SESSTOKEN option, HOST specifies a buffer to contain the host name of the server in the connection identified by the SESSTOKEN option. The port number is presented separately using the PORTNUMBER option.

An IPv4 or IPv6 address can represent the host name. IPv4 addresses are returned as native IPv4 dotted decimal addresses; for example, 1.2.3.4. IPv6 addresses are returned as native IPv6 colon hexadecimal addresses; for example, ::a:b:c:d

For information on IP addresses, see IP addresses.

HOSTLENGTH(data-area)

Specifies the length of the buffer supplied on the HOST option, as a fullword binary variable, and is set to the length of the data returned to the application. 116 characters is an appropriate size to specify for this data area. If the data exceeds the buffer length, a LENGERR condition is raised and the data is truncated.

HOSTTYPE(cvda)

Returns the address format of the HOST option. CVDA values are as follows:

HOSTNAME

The HOST option contains a character host name. The IP address that corresponds to the host name is looked up in the domain name server.

IPV4

The address is a dotted decimal IPv4 address.

IPV6

The address is a colon hexadecimal IPv6 address.

NOTAPPLIC

An incorrect host address was returned (HOST=0.0.0.0).

HTTPMETHOD(data-area)

For CICS as an HTTP server, this option specifies a buffer to contain the HTTP method string on the request line of the message.

This option is not relevant for CICS as an HTTP client.

HTTPVERSION(data-area)

For CICS as an HTTP server, this option specifies a buffer to contain the HTTP version for the Web client, as stated on its request.

For CICS as an HTTP client (with the SESSTOKEN option), this option specifies a buffer to contain the HTTP version of the server in the connection identified by the SESSTOKEN option. If CICS does not already know the HTTP version of the server, CICS makes a request to the server with the OPTIONS method to find out this information.

1.1 indicates HTTP/1.1, and 1.0 indicates HTTP/1.0 or lower.

METHODLENGTH(data-area)

Specifies the length of the buffer supplied on the HTTPMETHOD option, as a fullword binary variable, and is set to the actual length of the data returned to the application. If the data exceeds the buffer length, a LENGERR condition is raised and the data is truncated.

PATH(data-area)

For CICS as an HTTP server, this option specifies a buffer to contain the path specified in the request line of the message.

For CICS as an HTTP client (with the SESSTOKEN option), this option specifies a buffer to contain the default path that applies to requests made using the connection. If a URIMAP definition was specified on the WEB OPEN command for the connection, the default path is the path specified in the URIMAP definition. Otherwise, the default path is a single forward slash.

PATHLENGTH(data-area)

Specifies the length of the buffer supplied on the PATH option, as a fullword binary variable, and is set to the length of the data returned to the application. 256 characters is an appropriate size to specify for this data-area. If the data exceeds the buffer length, a LENGERR condition is raised and the data is truncated.

PORTNUMBER(data-area)

For CICS as an HTTP server, this option returns a data area containing the port number specified in the request line of the message.

For CICS as an HTTP client (with the SESSTOKEN option), this option returns a data containing the port number used to access the server in the connection specified by the SESSTOKEN option.

The value returned in the data area is a fullword binary value.

Well-known port numbers for a service are normally omitted from the URL. If the port number is not present in the URL, the command identifies and returns it based on the scheme. For HTTP, the well-known port number is 80, and, for HTTPS, the well-known port number is 443. If a port number is returned that is not the default for the scheme, you must specify the port number explicitly to gain access to the URL; for example, if you are using this information in a WEB OPEN command.

QUERYSTRING(data-area)

For CICS as an HTTP server, this option specifies a buffer to contain the query string on the request line of the message. The query string is the value or values encoded after the question mark (?) delimiting the end of the path. The query string is returned in its escaped form.

This option is not relevant for CICS as an HTTP client.

QUERYSTRLEN(data-area)

Specifies the length of the buffer supplied on the QUERY option, as a fullword binary variable, and is set to the length of the data returned to the application (the query string). 256 characters is an appropriate size to specify for this data area. If the data exceeds the buffer length, a LENGERR condition is raised and the data is truncated.

REALM(data-area)

Specifies, for CICS as an HTTP client, the realm or security environment that contains the data that you are requesting. If you are issuing a command in response to an HTTP 401 message, REALM is the realm value in the most recently received WWW-Authenticate header.

REALMLEN(data-area)

Specifies, for CICS as an HTTP client, the buffer length supplied for the REALM option, as a fullword binary variable. If you are issuing a command in response to an HTTP 401 message, REALMLEN is the length of the realm name in the most recently received WWW-Authenticate header.

REQUESTTYPE(cvda)

For CICS as an HTTP server, this option specifies the type of request received. This option is not relevant for CICS as an HTTP client. CVDA values are as follows:

HTTPYES

Indicates an HTTP request.

HTTPNO

Indicates a non-HTTP request.

SCHEME(cvda)

For both CICS as an HTTP server, and CICS as an HTTP client (with the SESSTOKEN option), this option returns the scheme used for the connection between CICS and the Web client or server. CVDA values are as follows:

HTTP

Is the HTTP protocol, without SSL.

HTTPS

Is the HTTPS protocol, which is HTTP with SSL.

SESSTOKEN(data-value)

For CICS as an HTTP client, this option is required. It specifies the session token, an 8-byte binary value that uniquely identifies a connection between CICS and a server. This value is returned by a WEB OPEN command for CICS as an HTTP client. Session tokens explains the use of the session token. For the command, information is returned about the specified connection.

This option is not relevant for CICS as an HTTP server.

URIMAP(data-area)

For CICS as an HTTP server, this option returns the 8-character name (in mixed case) of the URIMAP that matched the inbound request. The name is blank if the request did not match a URIMAP.

For CICS as an HTTP client (with the SESSTOKEN option), this option returns the 8-character name (in mixed case) of any URIMAP definition that was specified on the WEB OPEN command to open the connection specified by the SESSTOKEN option. The INQUIRE URIMAP command can be used to find information about the attributes of this URIMAP definition.

VERSIONLEN(data-area)

Specifies the length of the buffer supplied on the HTTPVERSION option, as a fullword binary variable, and is set to the length of the data returned to the application.

Conditions

16 INVREQ

RESP2 values:

1

The command is being issued in a non-CICS Web support application.

3

The command is being issued for a non-HTTP request. This command is set only if one or more of HTTPMETHOD, HTTPVERSION, or PATH is specified and the request is a non-HTTP request).

41

The connection has closed. This is a WEB EXTRACT (Client) error only. The server may have timed out due to inactivity on this connection.

67

The content of the response does not conform to HTTP format. The error is generated because there is a syntax problem. This error is for WEB EXTRACT (Client) only.

71

A chunked transfer-coding error has occurred. This error is for WEB EXTRACT (Client) only.

144

One or more of the Web command parameters is invalid. This error is for WEB EXTRACT (Client) only.

17 IOERR

RESP2 values:

42

Socket error.

22 LENGERR

RESP2 values:

4

The method exceeds the length specified (METHODLENGTH option).

5

The PATHLENGTH option value was not greater than zero.

6

The HTTP version exceeds the length specified (VERSIONLEN option).

7

The VERSIONLEN option value was not greater than zero.

8

The query string exceeds the length specified (QUERYSTRLEN option).

21

The HOSTLENGTH option value was not greater than zero.

29

The host name exceeds the length specified (HOSTLENGTH option).

30

The path exceeds the length specified (PATHLENGTH option).

141

REALMLEN is not positive, or is not large enough to contain the realm value returned in the HTTP 401 response.

13 NOTFND

RESP2 values:

155

Request line information not found.

19 NOTOPEN

RESP2 values:

27

Session token not valid.

124 TIMEDOUT

RESP2 values:

62

Timeout on socket receive.