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.

WEB EXTRACT (CICS as an HTTP server)
>>-WEB--EXTRACT--+--------------+------------------------------->
'-SCHEME(cvda)-'
>--+-----------------------------------------+------------------>
'-HOST(data-area)--HOSTLENGTH(data-value)-'
>--+------------------------------------------------+----------->
'-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: ILLOGIC, INVREQ, LENGERR, NOTOPEN
This command is threadsafe.

WEB EXTRACT (CICS as an HTTP client)
>>-WEB--EXTRACT--SESSTOKEN(data-area)--+--------------+--------->
'-SCHEME(cvda)-'
>--+-----------------------------------------+------------------>
'-HOST(data-area)--HOSTLENGTH(data-value)-'
>--+-----------------------------------------------+------------>
'-HTTPVERSION(data-area)--VERSIONLEN(data-area)-'
>--+----------------------------------------+------------------->
'-PATH(data-area)--PATHLENGTH(data-area)-'
>--+-----------------------+--+-------------------+------------><
'-PORTNUMBER(data-area)-' '-URIMAP(data-area)-'
Conditions: ILLOGIC, INVREQ, LENGERR, NOTOPEN
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 on the Internet. 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's response.
Options
- HOST(data-area)
- For CICS as
an HTTP server, this option 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), this option 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.
- HOSTLENGTH(data-area)
- specifies
the length of the buffer supplied on the HOST option, as a fullword binary
variable, and is set to the actual 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.
- 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 identifed by the SESSTOKEN option.
"1.1" indicates
HTTP/1.1, and "1.0" indicates HTTP/1.0.
Note: CICS does not make any special provision
for a server or Web client that is below HTTP/1.0 level. CICS behaves
as though they were at HTTP/1.0 level, and returns "1.0" as the HTTP version.
If
your application program writes HTTP headers that might be unsuitable for
a Web client or server at HTTP/1.0 level, or if you intend to send chunked
information to the Web client or server (which cannot be received by a client
or server at HTTP/1.0 level), your application program should check the HTTP
version information.
- 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 actual 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 WEB EXTRACT 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 which
is not the default for the scheme, you need to 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 actual 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.
- 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:
- 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:
- 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" in the CICS Internet Guide explains
the use of the session token. For the WEB EXTRACT command, information is
returned about the specified connection.
This option is not relevant for CICS as
an HTTP server.
- URIMAP(data-value)
- 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 actual length of the data returned to the
application.
Conditions
- INVREQ
- RESP2
values are:
- 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 is set only if
one or more of HTTPMETHOD, HTTPVERSION, or PATH is specified and the request
is a non-HTTP request).
- LENGERR
- RESP2
values are:
- 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).
- NOTOPEN
- RESP2
values are:
- 27
- Invalid session token.
- ILLOGIC
- RESP2
values are:
- 9
- CICS logic
error.