61
UTL_HTTP

UTL_HTTP makes hyper-text transfer protocol (HTTP) callouts from PL/SQL and SQL. You can use it to access data on the Internet or to call Oracle Web Server cartridges.

UTL_HTTP contains two similar entrypoints: REQUEST and REQUEST_PIECES. They each take a string universal resource locator (URL), contact that site, and return the data (typically HTML -- hyper-text markup language) obtained from that site.

Please note that a valid Oracle Wallet that is setup by Oracle Wallet Manager is needed only when using UTL_HTTP to fetch pages from website using HTTPS (secured HTTP). Regular HTTP fetch, which is the more common case, does not require a wallet.

See Also:
Oracle Advanced Security Administrator's Guide for more information on Wallet Manager.

Exceptions

Table 61-1 UTL_HTTP Package Exceptions

Exception	Description
INIT_FAILED	Initialization of the HTTP-callout subsystem fails (for environmental reasons, such as lack of available memory).
REQUEST_FAILED	The HTTP call fails (for example, because of failure of the HTTP daemon, or because the argument to `REQUEST` or `REQUEST_PIECES` cannot be interpreted as a URL because it is `NULL` or has non-HTTP syntax).

The above two exceptions, unless explicitly caught by an exception handler, are reported by this generic message: ORA-06510: PL/SQL: unhandled user-defined exception. This reports them as "user-defined" exceptions, although they are defined in this system package.

If any other exception is raised during the processing of the HTTP request (for example, an out-of-memory error), then function REQUEST or REQUEST_PIECES reraises that exception.

When no response is received from a request to the given URL (for example, because no site corresponding to that URL is contacted), then a formatted HTML error message may be returned. For example:

<HTML>
<HEAD>
<TITLE>Error Message</TITLE>
</HEAD>
<BODY>
<H1>Fatal Error 500</H1>
Can't Access Document:  http://home.nothing.comm.
<P>
<B>Reason:</B> Can't locate remote host:  home.nothing.comm.
<P>
 
<P><HR>
<ADDRESS><A HREF="http://www.w3.org">
CERN-HTTPD3.0A</A></ADDRESS>
</BODY>
</HTML>

Usage Notes

You should not expect REQUEST or REQUEST_PIECES to succeed in contacting a URL unless you can contact that URL by using a browser on the same machine (and with the same privileges, environment variables, etc.)

If REQUEST or REQUEST_PIECES fails (for example, if it raises an exception, or if it returns an HTML-formatted error message, yet you believe that the URL argument is correct), then try contacting that same URL with a browser, to verify network availability from your machine. Remember that you may have a proxy server set in your browser that needs to be set with each REQUEST or REQUEST_PIECES call using the optional proxy parameter.

Note:
UTL_HTTP can also use environment variables to specify its proxy behavior. For example, on UNIX, setting the environment variable http_proxy to a URL specifies to use that service as the proxy server for HTTP requests. Setting the environment variable no_proxy to a domain name specifies to not use the HTTP proxy server for URL's in that domain.

61UTL_HTTP

Exceptions

Table 61-1 UTL_HTTP Package Exceptions

Usage Notes

61
UTL_HTTP