102
UTL_URL

The UTL_URL package has two functions: ESCAPE and UNESCAPE.

This chapter discusses the following topics:

• Introduction to the UTL_URL Package
• UTL_URL Exceptions
• Summary of UTL_URL Subprograms

Introduction to the UTL_URL Package

A Uniform Resource Locator (URL) is a string that identifies a Web resource, such as a page or a picture. Use a URL to access such resources by way of the HyperText Transfer Protocol (HTTP). For example, the URL for Oracle's Web site is:

http://www.oracle.com

Normally, a URL contains English alphabetic characters, digits, and punctuation symbols. These characters are known the unreserved characters. Any other characters in URLs, including multibyte characters or binary octet codes, must be escaped to be accurately processed by Web browsers or Web servers. Some punctuation characters, such as dollar sign ($), question mark (?), colon (:), and equals sign (=), are reserved as delimiters in a URL. They are known as the reserved characters. To literally process these characters, instead of treating them as delimiters, they must be escaped.

The unreserved characters are:

• A through Z, a through z, and 0 through 9
• Hyphen (-), underscore (_), period (.), exclamation point (!), tilde (~), asterisk (*), accent ('), left parenthesis ( ( ), right parenthesis ( ) )

The reserved characters are:

• Semi-colon (;) slash (/), question mark (?), colon (:), at sign (@), ampersand (&), equals sign (=), plus sign (+), dollar sign ($), and comma (,)

The UTL_URL package has two functions that provide escape and unescape mechanisms for URL characters. Use the escape function to escape a URL before the URL is used fetch a Web page by way of the UTL_HTTP package. Use the unescape function to unescape an escaped URL before information is extracted from the URL.

For more information, refer to the Request For Comments (RFC) document RFC2396. Note that this URL escape and unescape mechanism is different from the x-www-form-urlencoded encoding mechanism described in the HTML specification:

http://www.w3.org/TR/html

You can implement the x-www-form-urlencoded encoding using the UTL_URL.ESCAPE function as follows:

CREATE OR REPLACE FUNCTION form_url_encode (
   data IN VARCHAR2,
   charset IN VARCHAR2) 
RETURN VARCHAR2 AS 
BEGIN 
  RETURN utl_url.escape(data, TRUE, charset); -- note use of TURE
END; 

For decoding data encoded with the form-URL-encode scheme, the following function implements the decording scheme:

function form_url_decode(
   data in varchar2, 
   charset in varchar2) 
  return varchar2 as 

begin 
  return utl_url.unescape(
     replace(data, '+', ' '), 
     charset); 
end; 

UTL_URL Exceptions

Table 102-1 lists the exceptions that can be raised when the UTL_URL package API is invoked.

Table 102-1 UTL_URL Exceptions

Exception	Error Code	Reason
bad_url	29262	The URL contains badly formed escape code sequences
bad_fixed_width_charset	29274	Fixed-width multibyte character set is not allowed as a URL character set.