UTL_URL v11

The UTL_URL package provides a way to escape illegal and reserved characters within an URL.

Function/ProcedureReturn TypeDescription
ESCAPE(url, escape_reserved_chars, url_charset)VARCHAR2Use the ESCAPE function to escape any illegal and reserved characters in a URL.
UNESCAPE(url, url_charset)VARCHAR2The UNESCAPE function to convert an URL to it's original form.

The UTL_URL package will return the BAD_URL exception if the call to a function includes an incorrectly-formed URL.

ESCAPE

Use the ESCAPE function to escape illegal and reserved characters within an URL. The signature is:

ESCAPE(<url> VARCHAR2, <escape_reserved_chars> BOOLEAN,
<url_charset> VARCHAR2)

Reserved characters are replaced with a percent sign, followed by the two-digit hex code of the ascii value for the escaped character.

Parameters

url

url specifies the Uniform Resource Locator that UTL_URL will escape.

escape_reserved_chars

escape_reserved_chars is a BOOLEAN value that instructs the ESCAPE function to escape reserved characters as well as illegal characters:

  • If escaped_reserved_chars is FALSE, ESCAPE will escape only the illegal characters in the specified URL.

  • If escape_reserved_chars is TRUE, ESCAPE will escape both the illegal characters and the reserved characters in the specified URL.

    By default, escape_reserved_chars is FALSE.

    Within an URL, legal characters are:

    Uppercase A through ZLowercase a through z0 through 9
    asterisk (*)exclamation point (!)hyphen (-)
    left parenthesis (()period (.)right parenthesis ())
    single-quote (')tilde (~)underscore (_)

    Some characters are legal in some parts of an URL, while illegal in others; to review comprehensive rules about illegal characters, refer to RFC 2396. Some examples of characters that are considered illegal in any part of an URL are:

    Illegal CharacterEscape Sequence
    a blank space ( )%20
    curly braces ({ or })%7b and %7d
    hash mark (#)%23

    The ESCAPE function considers the following characters to be reserved, and will escape them if escape_reserved_chars is set to TRUE:

    Reserved CharacterEscape Sequence
    ampersand (&)%5C
    at sign (@)%25
    colon (:)%3a
    comma (,)%2c
    dollar sign ($)%24
    equal sign (=)%3d
    plus sign (+)%2b
    question mark (?)%3f
    semi-colon (;)%3b
    slash (/)%2f

url_charset

url_charset specifies a character set to which a given character will be converted before it is escaped. If url_charset is NULL, the character will not be converted. The default value of url_charset is ISO-8859-1.

Examples

The following anonymous block uses the ESCAPE function to escape the blank spaces in the URL:

DECLARE
  result varchar2(400);
BEGIN
 result := UTL_URL.ESCAPE('http://www.example.com/Using the ESCAPE
function.html');
  DBMS_OUTPUT.PUT_LINE(result);
END;

The resulting (escaped) URL is:

http://www.example.com/Using%20the%20ESCAPE%20function.html

If you include a value of TRUE for the escape_reserved_chars parameter when invoking the function:

DECLARE
  result varchar2(400);
BEGIN
 result := UTL_URL.ESCAPE('http://www.example.com/Using the ESCAPE
function.html', TRUE);
  DBMS_OUTPUT.PUT_LINE(result);
END;

The ESCAPE function escapes the reserved characters as well as the illegal characters in the URL:

http%3A%2F%2Fwww.example.com%2FUsing%20the%20ESCAPE%20function.html

UNESCAPE

The UNESCAPE function removes escape characters added to an URL by the ESCAPE function, converting the URL to it's original form.

The signature is:

UNESCAPE(<url> VARCHAR2, <url_charset> VARCHAR2)

Parameters

url

url specifies the Uniform Resource Locator that UTL_URL will unescape.

url_charset

After unescaping a character, the character is assumed to be in url_charset encoding, and will be converted from that encoding to database encoding before being returned. If url_charset is NULL, the character will not be converted. The default value of url_charset is ISO-8859-1.

Examples

The following anonymous block uses the ESCAPE function to escape the blank spaces in the URL:

DECLARE
  result varchar2(400);
BEGIN
 result := 
UTL_URL.UNESCAPE('http://www.example.com/Using%20the%20UNESCAPE%20function.html');
  DBMS_OUTPUT.PUT_LINE(result);
END;

The resulting (unescaped) URL is:

http://www.example.com/Using the UNESCAPE function.html