84
UTL_URL

The UTL_URL package has two functions: ESCAPE and UNESCAPE.

Chapter 78, "UTL_HTTP"

This chapter discusses the following topics:

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. A URL allows you to easily 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 multi-byte 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

In fact, x-www-form-urlencoded encoding can be implemented using the UTL_URL.escape function as follows:

CREATE OR REPLACE FUNCTION form_urlencode (

v IN VARCHAR2) 

RETURN VARCHAR2 AS 
BEGIN 
  RETURN utl_url.escape(replace(v, ' ', '+'), TRUE); 
END;

UTL_URL Exceptions

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

Table 84-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.

Summary of UTL_URL Subprograms

Table 84-2 UTL_URL Package Subprograms

Subprogram	Description
"ESCAPE Function"	Returns a URL with illegal characters (and optionally reserved characters) escaped using the `%2-digit-hex-code` format
"UNESCAPE Function"	Unescapes the escape character sequences to their original forms in a URL. Convert the `%XX` escape character sequences to the original characters

84 UTL_URL