Breaks down a URL string into its component parts.

WEB PARSE URL
>>-WEB--PARSE URL(data-value)--URLLENGTH(data-value)------------>
>--+-----------------------+------------------------------------>
'-SCHEMENAME(data-area)-'
>--+----------------------------------------+------------------->
'-HOST(data-area)--HOSTLENGTH(data-area)-'
>--+-----------------------+------------------------------------>
'-PORTNUMBER(data-area)-'
>--+----------------------------------------+------------------->
'-PATH(data-area)--PATHLENGTH(data-area)-'
>--+------------------------------------------------+----------><
'-QUERYSTRING(data-area)--QUERYSTRLEN(data-area)-'
Conditions: INVREQ, LENGERR
This command is threadsafe.
Description
WEB PARSE URL enables you to break down
a URL string into its component parts: scheme, host, port, path and query
string. The CICS
Internet Guide explains these components. You can use this
process to examine the construction of the URL, and to separate out 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 invalid 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 can be either an alphanumeric host name
or a numeric IP address. If a port number was specified explicitly in the
URL, this is returned separately as the PORTNUMBER option.
An IPv4 address
can be used as a host name in the WEB OPEN command, but IPv6 addresses are not supported.
IPv6 addresses are rejected as invalid by the WEB PARSE URL command because
they do not conform to the expected structure.
- 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 (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.
- 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 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)
- 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 actual 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 upper case.
- 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
- INVREQ
- RESP2
values are:
- 28
- Invalid URL.
- 65
- Bad escape sequence.
- LENGERR
- RESP2
values are:
- 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.