Start of change

WEB PARSE URL

Breaks down a URL string into its component parts.

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

Start of changeThe scheme name is always returned in upper case.End of change

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.
End of change