WEB PARSE URL

Description

With WEB PARSE URL, you can break down a URL string into its component parts: scheme, host, port, path, and query string. The components of a URL explains these components. You can use this process to examine the construction of the URL and to separate the components. The returned information can be used in the WEB OPEN command to open a client connection to the host named in the URL.

Any escape sequences found in the URL are checked for validity. An escape sequence consists of the percent character (%) followed by two hexadecimal characters. Valid hexadecimal characters are the digits 0 to 9 and the letters A to F.

Note that where the string input to the WEB PARSE URL command has been delimited in the correct way for a URL, the command does not detect incorrect content, such as a host name that does not represent an existing host on the Internet, or a character that is not permitted in a URL.

Options

HOST(data-area)

Returns the host component of the URL. This value can be either a character host name or a numeric IP address. If a port number is specified explicitly in the URL, the port number is returned separately as the PORTNUMBER option.

An IPv4 or IPv6 address can represent the host name. IPv6 addresses are returned as native IPv6 colon hexadecimal addresses, for example, ::a:b:c:d. If you specify an IPv6 address in a URL, for example, http://[::a:b:c:d]:80, HOST returns the address without brackets.

Use the characters X'BA' and X'BB' (code page 37) to represent square brackets when you specify IPv6 addresses.

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 (the host name). 116 characters is suggested as 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.

PATH(data-area)

Returns the path component of the URL.

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 (the path component of the URL). 256 characters is suggested as 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)

Returns as a fullword binary data area, the port number that is specified in, or appropriate for, the URL. Port numbers are sometimes specified explicitly in a URL, following the host name. However, well-known port numbers for a service are normally omitted from a URL. If the port number is not present in the URL, the WEB PARSE URL 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)

Returns the query string from the URL. 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.

QUERYSTRLEN(data-area)

Specifies the length of the buffer supplied on the QUERYSTRING 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 suggested as 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.

SCHEMENAME(data-area)

Returns the scheme component of the URL, as a 16-character data area. Only the HTTP and HTTPS schemes (the HTTP protocol with and without SSL) are supported by CICS® and can be used in a WEB OPEN command.

The scheme name is always returned in uppercase.

URL(data-value)

Specifies the complete URL string.

URLLENGTH(data-value)

Specifies the length of the buffer containing the URL string, as a fullword binary value.

Conditions

16 INVREQ

RESP2 values:

28

Incorrect URL.

65

Bad escape sequence.

22 LENGERR

RESP2 values:

8

Length of query string returned is greater than QUERYSTRLEN.

29

Length of host name returned is greater than HOSTLENGTH.

30

Length of path returned is greater than PATHLENGTH.