UTL_URL v13

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

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 Z	Lowercase a through z	0 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 Character	Escape 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 Character	Escape 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