Obtain information about an HTTP request that has been
made to CICS® as an HTTP server or about a connection
between an Internet server and CICS as
an HTTP client. This command is a synonym of WEB EXTRACT.
EXTRACT WEB (CICS as an HTTP server)
>>-EXTRACT--WEB--+--------------+------------------------------->
'-SCHEME(cvda)-'
>--+-------------------------------------------------------------+-->
'-HOST(data-area)--HOSTLENGTH(data-value)--+----------------+-'
'-HOSTTYPE(cvda)-'
>--+------------------------------------------------+----------->
'-HTTPMETHOD(data-area)--METHODLENGTH(data-area)-'
>--+-----------------------------------------------+------------>
'-HTTPVERSION(data-area)--VERSIONLEN(data-area)-'
>--+----------------------------------------+------------------->
'-PATH(data-area)--PATHLENGTH(data-area)-'
>--+-----------------------+------------------------------------>
'-PORTNUMBER(data-area)-'
>--+------------------------------------------------+----------->
'-QUERYSTRING(data-area)--QUERYSTRLEN(data-area)-'
>--+-------------------+---------------------------------------><
'-REQUESTTYPE(cvda)-'
Conditions: INVREQ, LENGERR, NOTOPEN
This command is threadsafe.
EXTRACT WEB (CICS as an HTTP client)
>>-EXTRACT--WEB--SESSTOKEN(data-area)--+--------------+--------->
'-SCHEME(cvda)-'
>--+-------------------------------------------------------------+-->
'-HOST(data-area)--HOSTLENGTH(data-value)--+----------------+-'
'-HOSTTYPE(cvda)-'
>--+-----------------------------------------------+------------>
'-HTTPVERSION(data-area)--VERSIONLEN(data-area)-'
>--+----------------------------------------+------------------->
'-PATH(data-area)--PATHLENGTH(data-area)-'
>--+-----------------------+--+-------------------+------------->
'-PORTNUMBER(data-area)-' '-URIMAP(data-area)-'
>--+---------------------------------------+-------------------><
'-REALM(data-area)--REALMLEN(data-area)-'
Conditions: INVREQ, IOERR, LENGERR, NOTFND, NOTOPEN, TIMEDOUT
This command is threadsafe.
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 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.
This
option is not relevant for CICS as an HTTP server.
- 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.