Start of change

WEB EXTRACT

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.

Read syntax diagramSkip visual syntax diagram
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.

Read syntax diagramSkip visual syntax diagram
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.
End of change