UTL_URL v14

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

The UTL_URL package returns the BAD_URL exception if the call to a function includes a URL formed incorrectly.

ESCAPE

Use the ESCAPE function to escape illegal and reserved characters in a 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 escapes.

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 escapes only the illegal characters in the specified URL.

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

  By default, escape_reserved_chars is FALSE.

  In a 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 a 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 a URL are:

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

  The ESCAPE function treats the following characters as reserved and escapes 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 to convert a given character before escaping it. If url_charset is NULL, the character isn't converted. The default value of url_charset is ISO-8859-1.

Examples

This 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

Suppose 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 its original form.

The signature is:

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

Parameters

url

url specifies the Uniform Resource Locator that UTL_URL unescapes.

url_charset

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

Examples

This 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