Edit D:\rfid\database\database\doc\win.112\e10845\apps.htm
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" /> <meta http-equiv="Content-Language" content="en" /> <meta http-equiv="Content-Style-Type" content="text/css" /> <meta http-equiv="Content-Script-Type" content="text/javascript" /> <meta name="robots" content="all" scheme="http://www.robotstxt.org/" /> <meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 5.1" /> <meta name="Date" content="2010-03-05T15:45:39Z" /> <meta name="doctitle" content="Oracle® Database Platform Guide 11g Release 2 (11.2) for Microsoft Windows" /> <meta name="partno" content="E10845-01" /> <meta name="docid" content="NTQRF" /> <link rel="Start" href="../../index.htm" title="Home" type="text/html" /> <link rel="Copyright" href="../../dcommon/html/cpyr.htm" title="Copyright" type="text/html" /> <link rel="Stylesheet" href="../../dcommon/css/blafdoc.css" title="Default" type="text/css" /> <script type="text/javascript" src="../../dcommon/js/doccd.js"> </script> <link rel="Contents" href="toc.htm" title="Contents" type="text/html" /> <link rel="Index" href="index.htm" title="Index" type="text/html" /> <link rel="Glossary" href="glossary.htm" title="Glossary" type="text/html" /> <link rel="Prev" href="registry.htm" title="Previous" type="text/html" /> <link rel="Next" href="ap_doc.htm" title="Next" type="text/html" /> <link rel="alternate" href="../e10845.pdf" title="PDF version" type="application/pdf" /> <title>Developing Applications for Windows</title> </head> <body> <div class="header"> <div class="zz-skip-header"><a name="top" id="top" href="#BEGIN">Skip Headers</a></div> <table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%"> <tr> <td align="left" valign="top"><b>Oracle® Database Platform Guide<br /> 11<i>g</i> Release 2 (11.2) for Microsoft Windows</b><br /> Part Number E10845-01</td> <td valign="bottom" align="right"> <table class="icons oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="245"> <tr> <td align="center" valign="top"><a href="../../index.htm"><img width="24" height="24" src="../../dcommon/gifs/doclib.gif" alt="Go to Documentation Home" /><br /> <span class="icon">Home</span></a></td> <td align="center" valign="top"><a href="../../nav/portal_booklist.htm"><img width="24" height="24" src="../../dcommon/gifs/booklist.gif" alt="Go to Book List" /><br /> <span class="icon">Book List</span></a></td> <td align="center" valign="top"><a href="toc.htm"><img width="24" height="24" src="../../dcommon/gifs/toc.gif" alt="Go to Table of Contents" /><br /> <span class="icon">Contents</span></a></td> <td align="center" valign="top"><a href="index.htm"><img width="24" height="24" src="../../dcommon/gifs/index.gif" alt="Go to Index" /><br /> <span class="icon">Index</span></a></td> <td align="center" valign="top"><a href="../../dcommon/html/feedback.htm"><img width="24" height="24" src="../../dcommon/gifs/feedbck2.gif" alt="Go to Feedback page" /><br /> <span class="icon">Contact Us</span></a></td> </tr> </table> </td> </tr> </table> <hr /> <table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%"> <tr> <td align="left" valign="top"> <table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="98"> <tr> <td align="center" valign="top"><a href="registry.htm"><img width="24" height="24" src="../../dcommon/gifs/leftnav.gif" alt="Go to previous page" /><br /> <span class="icon">Previous</span></a></td> <td align="center" valign="top"><a href="ap_doc.htm"><img width="24" height="24" src="../../dcommon/gifs/rightnav.gif" alt="Go to next page" /><br /> <span class="icon">Next</span></a></td> </tr> </table> </td> <td align="right" valign="top" style="font-size: 90%"><a href="../e10845.pdf">View PDF</a></td> </tr> </table> <a name="BEGIN" id="BEGIN"></a></div> <div class="IND"><!-- End Header --><a id="g1012237" name="g1012237"></a><a id="NTQRF190" name="NTQRF190"></a><a id="i1006516" name="i1006516"></a> <h1 class="chapter"><span class="secnum">16</span> Developing Applications for Windows</h1> <p>This chapter points to sources of information on developing applications for Windows and outlines a procedure for building and debugging external procedures.</p> <p>This chapter contains these topics:</p> <ul> <li> <p><a href="#BACBICCJ">Finding Information on Application Development for Windows</a></p> </li> <li> <p><a href="#i1005844">Building External Procedures</a></p> </li> <li> <p><a href="#CIHIBGAA">Multithreaded Agent Architecture</a></p> </li> <li> <p><a href="#i1006102">Debugging External Procedures</a></p> </li> <li> <p><a href="#BACCGJBI">Accessing Text Files with UTL_FILE</a></p> </li> <li> <p><a href="#i1006153">Accessing Web Data with Intercartridge Exchange</a></p> </li> </ul> <a id="BACBICCJ" name="BACBICCJ"></a><a id="NTQRF462" name="NTQRF462"></a> <div class="sect1"><!-- infolevel="all" infotype="General" --> <h2 class="sect1"><a id="sthref705" name="sthref705"></a><a id="sthref706" name="sthref706"></a>Finding Information on Application Development for Windows</h2> <p>This section describes where to find information on developing applications specifically for Windows. These products are included on your Oracle Database Server media.</p> <a id="NTQRF463" name="NTQRF463"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref707" name="sthref707"></a> <h3 class="sect2">Java Enhancements</h3> <p>Oracle Database includes an integrated Java Virtual Machine and JIT Compiler. Oracle Database also provides Oracle Java Database Connectivity (JDBC) Drivers. For more information, see <a class="olink JJDEV" href="http://www.oracle.com/pls/db112/lookup?id=JJDEV"><span class="italic">Oracle Database Java Developer's Guide</span></a> and <a class="olink JJDBC" href="http://www.oracle.com/pls/db112/lookup?id=JJDBC"><span class="italic">Oracle Database JDBC Developer's Guide</span></a>.</p> </div> <!-- class="sect2" --> <a id="CHDHBGJA" name="CHDHBGJA"></a><a id="NTQRF469" name="NTQRF469"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2">ODP.NET</h3> <p>Oracle Data Provider for .NET (ODP.NET) is an implementation of a data provider for Oracle Database. ODP.NET uses Oracle native APIs to offer fast and reliable access to Oracle data and features from any .NET application. ODP.NET also uses and inherits classes and interfaces available in the Microsoft .NET Framework Class Library. For more information, refer to <a class="olink ODPNT" href="http://www.oracle.com/pls/db112/lookup?id=ODPNT"><span class="italic">Oracle Data Provider for .NET Developer's Guide for Microsoft Windows</span></a>.</p> </div> <!-- class="sect2" --> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref708" name="sthref708"></a> <h3 class="sect2">Oracle Developer Tools for Visual Studio</h3> <p>The Oracle Developer Tools for Visual Studio (ODT) is a tightly integrated "Add-in" for Microsoft Visual Studio 2008, 2005, and 2003. ODT integrates with Visual Studio to make it easy to browse and edit Oracle schema objects using integrated visual designers and can automatically generate .NET code through a simple drag and drop. Developers can modify table data, execute Oracle SQL statements, edit and debug PL/SQL code, generate and edit SQL scripts, and develop and deploy .NET stored procedures. There are many more features included with these tools. For more information, visit the ODT Web home at</p> <p><code><a href="http://www.oracle.com/technology/tech/dotnet/tools/index.html">http://www.oracle.com/technology/tech/dotnet/tools/index.html</a></code></p> </div> <!-- class="sect2" --> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref709" name="sthref709"></a> <h3 class="sect2">Oracle Providers for ASP.NET</h3> <p>Beginning with .NET Framework 2.0, ASP.NET includes service providers that store state in databases. By storing this state in a database, applications can ensure high availability of data, while making the data equally available to all Web servers. For more information, refer to <span class="italic"><a class="olink ASPNT" href="http://www.oracle.com/pls/db112/lookup?id=ASPNT">Oracle Providers for ASP.NET Developer's Guide for Microsoft Windows</a></span>.</p> </div> <!-- class="sect2" --> <a id="NTQRF464" name="NTQRF464"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref710" name="sthref710"></a> <h3 class="sect2">XML Support</h3> <p>Oracle XML products include XML Developer's Kit (XDK) and Oracle XML SQL Utility. For more information:</p> <ul> <li> <p><a class="olink ADXDK" href="http://www.oracle.com/pls/db112/lookup?id=ADXDK"><span class="italic">Oracle XML Developer's Kit Programmer's Guide</span></a></p> </li> <li> <p><a class="olink ADXDB" href="http://www.oracle.com/pls/db112/lookup?id=ADXDB"><span class="italic">Oracle XML DB Developer's Guide</span></a></p> </li> <li> <p><a class="olink JAXML" href="http://www.oracle.com/pls/db112/lookup?id=JAXML"><span class="italic">Oracle Database XML Java API Reference</span></a></p> </li> <li> <p><a class="olink CAXML" href="http://www.oracle.com/pls/db112/lookup?id=CAXML"><span class="italic">Oracle Database XML C API Reference</span></a></p> </li> <li> <p><a class="olink CPXML" href="http://www.oracle.com/pls/db112/lookup?id=CPXML"><span class="italic">Oracle Database XML C++ API Reference</span></a></p> </li> <li> <p><a class="olink SQLRF" href="http://www.oracle.com/pls/db112/lookup?id=SQLRF"><span class="italic">Oracle Database SQL Language Reference</span></a></p> </li> <li> <p><a class="olink ARPLS" href="http://www.oracle.com/pls/db112/lookup?id=ARPLS"><span class="italic">Oracle Database PL/SQL Packages and Types Reference</span></a></p> </li> </ul> </div> <!-- class="sect2" --> <a id="NTQRF465" name="NTQRF465"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref711" name="sthref711"></a> <h3 class="sect2">Support for Internet Applications</h3> <p><a id="sthref712" name="sthref712"></a>Oracle Database support for internet applications includes Oracle Portal, which enables you to publish your data to the Web, Oracle HTTP Server, and PL/SQL Embedded Gateway, which offers <a href="glossary.htm#i432445"><span class="xrefglossterm">PL/SQL</span></a> procedures stored in Oracle Database that can be started through browsers. For more information:</p> <ul> <li> <p><span class="italic">Oracle Portal Installation Guide and Tutorial</span></p> </li> <li> <p><a class="olink OEMCG" href="http://www.oracle.com/pls/db112/lookup?id=OEMCG"><span class="italic">Oracle Enterprise Manager Grid Control Installation and Basic Configuration</span></a></p> <div class="infoboxnote"> <p class="notep1">Note:</p> Oracle Portal is available on a separate media and included with Oracle Database for Windows.</div> <p>Oracle Database provides built-in mechanisms that address the requirements of the largest PHP, Ruby, Python Web, and Rich Internet Applications. The features include extreme connectivity, scalability, caching, nonintrusive performance acceleration, advanced security, and high-availability.</p> </li> </ul> </div> <!-- class="sect2" --> <a id="NTQRF470" name="NTQRF470"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref713" name="sthref713"></a> <h3 class="sect2">Oracle Services For Microsoft Transaction Server</h3> <p>Oracle Database for Windows permits enhanced deployment of COM/COM+ components in <a href="glossary.htm#i432315"><span class="xrefglossterm">Microsoft Transaction Server</span></a>, using Oracle Database as the resource manager. For more information, refer to <a class="olink NTMTS" href="http://www.oracle.com/pls/db112/lookup?id=NTMTS"><span class="italic">Oracle Services for Microsoft Transaction Server Developer's Guide for Microsoft Windows</span></a>.</p> </div> <!-- class="sect2" --> <a id="NTQRF468" name="NTQRF468"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref714" name="sthref714"></a> <h3 class="sect2">Oracle Objects for OLE</h3> <p>Oracle Objects for OLE (OO4O) provides easy access to data stored in Oracle Database servers with any programming or scripting language that supports the Microsoft COM Automation and ActiveX technology. These include Visual Basic, Visual C++, Visual Basic For Applications (VBA), IIS Active Server Pages (VBScript and JavaScript), and others. For more information, refer to <a class="olink OOFOL" href="http://www.oracle.com/pls/db112/lookup?id=OOFOL"><span class="italic">Oracle Objects for OLE Developer's Guide for Microsoft Windows.</span></a></p> </div> <!-- class="sect2" --> <a id="NTQRF472" name="NTQRF472"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref715" name="sthref715"></a> <h3 class="sect2">Oracle Provider for OLE DB</h3> <p>Refer to <a class="olink OLEDB" href="http://www.oracle.com/pls/db112/lookup?id=OLEDB"><span class="italic">Oracle Provider for OLE DB Developer's Guide for Microsoft Windows</span></a> for information on OLE DB.</p> <div class="infoboxnote"> <p class="notep1">Note:</p> Oracle ODBC Driver is updated on a regular basis. The newest release available is included on your media. To download the latest release, visit: <code><a href="http://www.oracle.com/technology/index.html">http://www.oracle.com/technology/index.html</a></code> <p>Select Oracle ODBC Drivers from the Select a Utility or Driver list.</p> </div> </div> <!-- class="sect2" --> <a id="NTQRF467" name="NTQRF467"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref716" name="sthref716"></a> <h3 class="sect2">Oracle COM Automation Feature</h3> <p>Oracle <a href="glossary.htm#i432205"><span class="xrefglossterm">COM</span></a> automation feature enables PL/SQL and Java stored procedure developers and COM/COM+ developers to load COM/COM+ objects from Oracle Database. For more information, refer to <a class="olink COMDG" href="http://www.oracle.com/pls/db112/lookup?id=COMDG"><span class="italic">Oracle COM Automation Feature Developer's Guide for Microsoft Windows.</span></a></p> </div> <!-- class="sect2" --> <a id="NTQRF471" name="NTQRF471"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref717" name="sthref717"></a> <h3 class="sect2">Pro*C/C++ and Pro*COBOL Applications</h3> <p>Refer to the following guides for more information on Pro*C/C++ and Pro*COBOL applications:</p> <ul> <li> <p><a class="olink LNPCC" href="http://www.oracle.com/pls/db112/lookup?id=LNPCC"><span class="italic">Pro*C/C++ Programmer's Guide</span></a></p> </li> <li> <p><a class="olink LNPCB" href="http://www.oracle.com/pls/db112/lookup?id=LNPCB"><span class="italic">Pro*COBOL Programmer's Guide</span></a></p> </li> <li> <p><a class="olink LNOCI" href="http://www.oracle.com/pls/db112/lookup?id=LNOCI"><span class="italic">Oracle Call Interface Programmer's Guide</span></a></p> </li> </ul> </div> <!-- class="sect2" --></div> <!-- class="sect1" --> <a id="i1005844" name="i1005844"></a><a id="NTQRF478" name="NTQRF478"></a> <div class="sect1"><!-- infolevel="all" infotype="General" --> <h2 class="sect1">Building External Procedures</h2> <p>This section describes how to create and use <a href="glossary.htm#i432249"><span class="xrefglossterm">external procedures</span></a> on Windows. The following files are located in <code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\rdbms\extproc</code>:</p> <ul> <li> <p><code><span class="codeinlinebold">extern.c</span></code> is the code example shown in <a href="#i1005976">"Writing an External Procedure"</a></p> </li> <li> <p><code><span class="codeinlinebold">make.bat</span></code> is the batch file that builds the <a href="glossary.htm#i432246"><span class="xrefglossterm">dynamic link library</span></a></p> </li> <li> <p><code><span class="codeinlinebold">extern.sql</span></code> automates the instructions described in <a href="#i1006021">"Registering an External Procedure"</a> and <a href="#i1006075">"Executing an External Procedure"</a></p> </li> </ul> <a id="NTQRF479" name="NTQRF479"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref718" name="sthref718"></a> <h3 class="sect2">External Procedures Overview</h3> <p>External procedures are functions written in a third-generation language (C, for example) and callable from within PL/SQL or SQL as if they were a PL/SQL routine or function. External procedures let you take advantage of strengths and capabilities of a third-generation programming language in a PL/SQL environment.</p> <div class="infoboxnote"> <p class="notep1">Note:</p> Oracle Database also provides a special purpose interface, the call specification, that lets you call external procedures from other languages, as long as they are callable by C.</div> <p>The main advantages of external procedures are:</p> <ul> <li> <p>Performance, because some tasks are performed more efficiently in a third-generation language than in PL/SQL, which is better suited for SQL transaction processing</p> </li> <li> <p>Code re-usability, because dynamic link libraries (DLLs) can be called directly from PL/SQL programs on the server or in client tools</p> </li> </ul> <p>You can use external procedures to perform specific processes:</p> <ul> <li> <p>Solving scientific and engineering problems</p> </li> <li> <p>Analyzing data</p> </li> <li> <p>Controlling real-time devices and processes</p> </li> </ul> <div class="infoboxnote"> <p class="notep1">Caution:</p> Special security precautions are warranted when configuring a listener to handle external procedures. See <a href="ap_net.htm#CHDHEHCH">"Modifying Configuration of External Procedures for Higher Security"</a> and <a class="olink NETAG0132" href="http://www.oracle.com/pls/db112/lookup?id=NETAG0132"><span class="italic">Oracle Database Net Services Administrator's Guide</span></a> for more information.</div> <p>To create and use an external procedure, perform the following sequential steps:</p> <ul> <li> <p><a href="#i1005913">Installing and Configuring</a></p> </li> <li> <p><a href="#i1005976">Writing an External Procedure</a></p> </li> <li> <p><a href="#BACBIJJJ">Building a DLL</a></p> </li> <li> <p><a href="#i1006021">Registering an External Procedure</a></p> </li> <li> <p><a href="#i1006075">Executing an External Procedure</a></p> <div class="infoboxnote"> <p class="notep1">Note:</p> <ul> <li> <p>You must have a C compiler and linker installed on your system to build DLLs.</p> </li> <li> <p>You can combine the instructions described in the fourth and fifth tasks into one SQL script that automates the task of registering and executing your external procedure. See <code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\rdbms\extproc\extern.sql</code> for an example of a SQL script that combines these steps.</p> </li> </ul> </div> </li> </ul> </div> <!-- class="sect2" --> <a id="i1005913" name="i1005913"></a><a id="NTQRF480" name="NTQRF480"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2">Installing and Configuring</h3> <p>This section describes installation and configuration of Oracle Database and <a href="glossary.htm#i433191"><span class="xrefglossterm">Oracle Net</span></a>.</p> <a id="NTQRF481" name="NTQRF481"></a> <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref719" name="sthref719"></a> <h4 class="sect3">Installing Oracle Database</h4> <p>Follow the steps in <a class="olink NTDBI" href="../../install.112/e10843/toc.htm"><span class="italic">Oracle Database Installation Guide for Microsoft Windows</span></a> to install these products on your Windows server:</p> <ul> <li> <p><a id="sthref720" name="sthref720"></a>Oracle Database Enterprise Edition, Oracle Database Standard Edition, or Oracle Database Personal Edition. Each type contains PL/SQL, from which external procedures are called, and the PL/SQL external procedure program (EXTPROC), which runs external procedures.</p> </li> <li> <p>Oracle Net Services</p> </li> <li> <p><a href="glossary.htm#i432415"><span class="xrefglossterm">Oracle Protocol Support</span></a></p> </li> </ul> </div> <!-- class="sect3" --> <a id="i1005946" name="i1005946"></a><a id="NTQRF482" name="NTQRF482"></a> <div class="sect3"><!-- infolevel="all" infotype="General" --> <h4 class="sect3"><a id="sthref721" name="sthref721"></a>Configuring Oracle Net Services</h4> <p>During database server installation, Oracle Net Configuration Assistant configures <code>listener.ora</code> and <code>tnsnames.ora</code> files for external procedure calls.</p> <p><a id="sthref722" name="sthref722"></a><a id="sthref723" name="sthref723"></a>When an application calls an external procedure, Oracle Net Listener starts an external procedure agent called EXTPROC. Using a network connection established by the listener, the application passes the following information to EXTPROC:</p> <ul> <li> <p>DLL name</p> </li> <li> <p>External procedure name</p> </li> <li> <p>Parameters (if necessary)</p> </li> </ul> <p>EXTPROC then loads the DLL, runs the external procedure, and passes back any values returned by the external procedure.</p> <p>If you overwrite default <code>listener.ora</code> and <code>tnsnames.ora</code> files, then you must manually configure the following files for the external procedure behavior described previously to occur:</p> <ul> <li> <p><code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\network\admin\listener.ora</code></p> </li> <li> <p><code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\network\admin\tnsnames.ora</code></p> <div class="infoboxnote"> <p class="notep1">Caution:</p> Additional security may be required for the listener in a production environment. See <a class="olink NETAG010" href="http://www.oracle.com/pls/db112/lookup?id=NETAG010"><span class="italic">Oracle Database Net Services Administrator's Guide</span></a> for more information.</div> </li> </ul> </div> <!-- class="sect3" --></div> <!-- class="sect2" --> <a id="i1005976" name="i1005976"></a><a id="NTQRF483" name="NTQRF483"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2"><a id="sthref724" name="sthref724"></a><a id="sthref725" name="sthref725"></a>Writing an External Procedure</h3> <p>Using a third-generation programming language, you can write functions to be built into DLLs and started by EXTPROC. The following is a simple Microsoft Visual C++ example of an external procedure called <code>FIND_MAX</code>:</p> <div class="infoboxnote"> <p class="notep1">Note:</p> Because external procedures are built into DLLs, they must be explicitly exported. In this example, the <code>DLLEXPORT</code> storage class modifier exports the function <code>FIND_MAX</code> from a dynamic link library.</div> <pre xml:space="preserve" class="oac_no_warn">#include <windows.h> #define NullValue -1 /* This function tests if x is at least as big as y. */ long __declspec(dllexport) find_max(long x, short x_indicator, long y, short y_indicator, short *ret_indicator) { /* It can be tricky to debug DLL's that are being called by a process that is spawned only when needed, as in this case. Therefore try using the DebugBreak(); command. This will start your debugger. Uncomment the line with DebugBreak(); in it and you can step right into your code. */ /* DebugBreak(); */ /* First check to see if you have any nulls. */ /* Just return a null if either x or y is null. */ if ( x_indicator==NullValue || y_indicator==NullValue) { *ret_indicator = NullValue; return(0); } else { *ret_indicator = 0; /* Signify that return value is not null. */ if (x >= y) return x; else return y; } } </pre></div> <!-- class="sect2" --> <a id="BACBIJJJ" name="BACBIJJJ"></a><a id="NTQRF484" name="NTQRF484"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2"><a id="sthref726" name="sthref726"></a><a id="sthref727" name="sthref727"></a>Building a DLL</h3> <p>After writing your external procedure(s) in a third-generation programming language, use the appropriate compiler and linker to build a DLL, making sure to export the external procedures as noted previously. See your compiler and linker documentation for instructions on building a DLL and exporting its functions.</p> <p>You can build the external procedure <code>FIND_MAX</code>, created in <a href="#i1005976">"Writing an External Procedure"</a>, into a DLL called <code>extern.dll</code> by going to <code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\rdbms\extproc</code> and typing <code>make</code>. After building the DLL, you can move it to any directory on your system.</p> <p>Starting with Oracle9<span class="italic">i</span> Release 2, however, the default behavior of EXTPROC is to load DLLs only from <code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\bin</code> or <code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\lib</code>. To load DLLs from other directories, you must set environment variable <code>EXTPROC_DLLS</code> to a colon (:) separated list of DLL names qualified with their complete paths. The preferred way to set this environment variable is through the <code>ENVS</code> parameter in <code>listener.ora</code>.</p> <div class="infoboxnotealso"> <p class="notep1">See Also:</p> <a class="olink ADFNS010" href="http://www.oracle.com/pls/db112/lookup?id=ADFNS010"><span class="italic">Oracle Database Advanced Application Developer's Guide</span></a> for more information on EXTPROC</div> </div> <!-- class="sect2" --> <a id="i1006021" name="i1006021"></a><a id="NTQRF485" name="NTQRF485"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2"><a id="sthref728" name="sthref728"></a><a id="sthref729" name="sthref729"></a>Registering an External Procedure</h3> <p>Once you have built a DLL containing your external procedure(s), you must register your external procedure(s) with Oracle Database:</p> <p><a id="sthref730" name="sthref730"></a><a id="sthref731" name="sthref731"></a>To create a PL/SQL library to map to the DLL:</p> <ol> <li> <p>Set environment variable <code>EXTPROC_DLLS</code> in the <code>ENVS</code> parameter in <code>listener.ora</code>. For example:</p> <pre xml:space="preserve" class="oac_no_warn">SID_LIST_LISTENER = (SID_LIST = (SID_DESC = (SID_NAME=PLSExtProc) (ENVS=EXTPROC_DLLS=C:\app\oracle\product\11.2.0\dbhome_1\rdbms\extproc\extern.dll) (ORACLE_HOME=C:\app\oracle\product\11.2.0\dbhome_1) (PROGRAM=extproc) ) ) </pre></li> <li> <p>Start SQL*Plus:</p> <pre xml:space="preserve" class="oac_no_warn">C:\> sqlplus </pre></li> <li> <p>Connect to the database with appropriate <a href="glossary.htm#i432581"><span class="xrefglossterm">username</span></a> and password.</p> </li> <li> <p>Create the PL/SQL library using the <code>CREATE LIBRARY</code> command:</p> <pre xml:space="preserve" class="oac_no_warn">SQL> CREATE LIBRARY externProcedures AS 'C:\app\oracle\product\11.2.0\dbhome_1\rdbms\ extproc\extern.dll'; </pre> <p>where <code>externProcedures</code> is an alias library (essentially a schema object in the database), and</p> <pre xml:space="preserve" class="oac_no_warn">C:\app\oracle\product\11.2.0\dbhome_1\rdbms\extproc\extern.dll </pre> <p>is the path to the Windows operating system <code>dllextern.dll</code>. This example uses <code>C:\app\oracle\product\11.2.0</code> as your Oracle base and <code>dbhome_1</code> as your Oracle home.</p> <div class="infoboxnote"> <p class="notep1">Note:</p> <a id="sthref732" name="sthref732"></a><a id="sthref733" name="sthref733"></a>The DBA must grant the <code>EXECUTE</code> <a href="glossary.htm#i432451"><span class="xrefglossterm">privilege</span></a> on the PL/SQL library to users who want to call the library's external procedure from PL/SQL or SQL.</div> </li> <li> <p><a id="sthref734" name="sthref734"></a><a id="sthref735" name="sthref735"></a>Create a PL/SQL program unit specification.</p> <p>Do this by writing a PL/SQL subprogram that uses the <code>EXTERNAL</code> clause instead of declarations and a <code>BEGIN...END</code> block. The <code>EXTERNAL</code> clause is the interface between PL/SQL and the external procedure. The <code>EXTERNAL</code> clause identifies the following information about the external procedure:</p> <ul> <li> <p>Name</p> </li> <li> <p>DLL alias</p> </li> <li> <p>Programming language in which it was written</p> </li> <li> <p>Calling standard (defaults to C if omitted)</p> </li> </ul> <p>In the following example, <code>externProcedures</code> is a DLL alias. You need the <code>EXECUTE</code> privilege for this library. The external procedure to call is <code>find_max</code>. If enclosed in double quotation marks, it becomes case-sensitive. The <code>LANGUAGE</code> term specifies the language in which the external procedure was written.</p> <pre xml:space="preserve" class="oac_no_warn">CREATE OR REPLACE FUNCTION PLS_MAX( x BINARY_INTEGER, y BINARY_INTEGER) RETURN BINARY_INTEGER AS EXTERNAL LIBRARY externProcedures NAME "find_max" LANGUAGE C PARAMETERS ( x long, -- stores value of x x_INDICATOR short, -- used to determine if x is a NULL value y long, -- stores value of y y_INDICATOR short, -- used to determine if y is a NULL value RETURN INDICATOR short ); -- need to pass pointer to return value's -- indicator variable to determine if NULL -- This means that my function will be defined as: -- long max(long x, short x_indicator, -- long y, short y_indicator, short * ret_indicator) </pre></li> </ol> </div> <!-- class="sect2" --> <a id="i1006075" name="i1006075"></a><a id="NTQRF486" name="NTQRF486"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2">Executing an External Procedure</h3> <p>To run an external procedure, you must call the PL/SQL program unit (that is, the alias for the external function) that registered the external procedure. These calls can appear in any of the following:</p> <ul> <li> <p>Anonymous blocks</p> </li> <li> <p>Standalone and packaged subprograms</p> </li> <li> <p>Methods of an object type</p> </li> <li> <p>Database triggers</p> </li> <li> <p>SQL statements (calls to packaged functions only)</p> </li> </ul> <p>In <a href="#i1006021">"Registering an External Procedure"</a>, PL/SQL function <code>PLS_MAX</code> registered external procedure <code>find_max</code><span class="bold">.</span> Follow these steps to run <code>find_max</code>:</p> <ol> <li> <p>Call PL/SQL function <code>PLS_MAX</code> from a PL/SQL routine named <code>UseIt</code>:</p> <pre xml:space="preserve" class="oac_no_warn">SET SERVER OUTPUT ON CREATE OR REPLACE PROCEDURE UseIt AS a integer; b integer; c integer; BEGIN a := 1; b := 2; c := PLS_MAX(a,b); dbms_output.put_line('The maximum of '||a||' and '||b||' is '||c); END; </pre></li> <li> <p>Run the routine:</p> <pre xml:space="preserve" class="oac_no_warn">SQL> EXECUTE UseIt; </pre></li> </ol> </div> <!-- class="sect2" --></div> <!-- class="sect1" --> <a id="CIHIBGAA" name="CIHIBGAA"></a><a id="NTQRF487" name="NTQRF487"></a> <div class="sect1"><!-- infolevel="all" infotype="General" --> <h2 class="sect1">Multithreaded Agent Architecture<a id="sthref736" name="sthref736"></a></h2> <p>An agent process is started for each session to access a system at the same time leading to several thousand agent processes running concurrently. The agent processes operate regardless of whether each individual agent process is actually active at the moment. Agent processes and open connections can consume a disproportionate amount of system resources. This problem is addressed by using multithreaded agent architecture.</p> <p>The multithreaded agent architecture uses a pool of shared agent threads. The tasks requested by the user sessions are put in a queue and are picked up by the first available multithreaded agent thread. Because only a small percentage of user connections are active at a given moment, using a multithreaded architecture allows for more efficient use of system resources.</p> <div class="infoboxnotealso"> <p class="notep1">See Also:</p> <ul> <li> <p>Part III of <a class="olink ADFNS" href="http://www.oracle.com/pls/db112/lookup?id=ADFNS"><span class="italic">Oracle Database Advanced Application Developer's Guide</span></a></p> </li> <li> <p>"Multithreaded Agents" in <a class="olink HETER005" href="http://www.oracle.com/pls/db112/lookup?id=HETER005"><span class="italic">Oracle Database Heterogeneous Connectivity User's Guide</span></a></p> </li> </ul> </div> </div> <!-- class="sect1" --> <a id="i1006102" name="i1006102"></a><a id="NTQRF488" name="NTQRF488"></a> <div class="sect1"><!-- infolevel="all" infotype="General" --> <h2 class="sect1"><a id="sthref737" name="sthref737"></a><a id="sthref738" name="sthref738"></a>Debugging External Procedures</h2> <p>Usually, when an external procedure fails, its C prototype is faulty. That is, the prototype does not match the one generated internally by PL/SQL. This can happen if you specify an incompatible C data type. For example, to pass an <code>OUT</code> parameter of type <code>REAL</code>, you must specify <code>float</code> <code>*</code>. Specifying <code>float</code>, <code>double</code> <code>*</code>, or any other C data type will result in a mismatch.</p> <p>In such cases, you might get a <code>lost</code> <code>RPC</code> <code>connection</code> <code>to</code> <code>external</code> <code>procedure</code> <code>agent</code> error, which means that agent <code>extproc</code> terminated abnormally because the external procedure caused a core dump. To avoid errors when declaring C prototype parameters, refer to <a class="olink ADDCI" href="http://www.oracle.com/pls/db112/lookup?id=ADDCI"><span class="italic">Oracle Database Data Cartridge Developer's Guide.</span></a></p> <a id="NTQRF489" name="NTQRF489"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --><a id="sthref739" name="sthref739"></a> <h3 class="sect2">Using Package DEBUG_EXTPROC</h3> <p>To help you debug external procedures, PL/SQL provides utility package DEBUG_EXTPROC. To install the package, run script <code>dbgextp.sql</code>, which you can find in the PL/SQL demo directory.</p> <p>To use the package, follow instructions in <code>dbgextp.sql</code>. Your Oracle Database account must have <code>EXECUTE</code> privileges on the package and <code>CREATE</code> <code>LIBRARY</code> privileges.</p> <p>To debug external procedures:</p> <ol> <li> <p>From Windows Task Manager, in the Processes dialog, select <span class="bold">ExtProc.exe</span>.</p> </li> <li> <p>Right click, and select <span class="bold">Debug</span>.</p> </li> <li> <p>Click <span class="bold">OK</span> in the message window.</p> <p>If you have built your DLL in a debug fashion with Microsoft Visual C++, then Visual C++ is activated.</p> </li> <li> <p>In the Visual C++ window, select <span class="bold">Edit</span> <code>></code> <span class="bold">Breakpoints</span>.</p> <p>Use the breakpoint identified in <code>dbgextp.sql</code> in the PL/SQL demo directory.</p> <div class="infoboxnotealso"> <p class="notep1">See Also:</p> <ul> <li> <p><code><span class="codeinlineitalic">ORACLE_HOME</span></code><code>\rdbms\extproc\readme.doc</code> (explains how to run the sample and provides debugging advice)</p> </li> <li> <p><a class="olink LNPLS" href="http://www.oracle.com/pls/db112/lookup?id=LNPLS"><span class="italic">Oracle Database PL/SQL Language Reference</span></a></p> </li> <li> <p><a class="olink JJDEV" href="http://www.oracle.com/pls/db112/lookup?id=JJDEV"><span class="italic">Oracle Database Java Developer's Guide</span></a></p> </li> <li> <p>"Calling External Procedures" in <a class="olink ADFNS010" href="http://www.oracle.com/pls/db112/lookup?id=ADFNS010"><span class="italic">Oracle Database Advanced Application Developer's Guide</span></a></p> </li> <li> <p><a class="olink ADDCI" href="http://www.oracle.com/pls/db112/lookup?id=ADDCI"><span class="italic">Oracle Database Data Cartridge Developer's Guide</span></a></p> </li> </ul> </div> </li> </ol> </div> <!-- class="sect2" --></div> <!-- class="sect1" --> <a id="BACCGJBI" name="BACCGJBI"></a><a id="NTQRF490" name="NTQRF490"></a> <div class="sect1"><!-- infolevel="all" infotype="General" --> <h2 class="sect1"><a id="sthref740" name="sthref740"></a><a id="sthref741" name="sthref741"></a>Accessing Text Files with UTL_FILE</h2> <p>Package <code>UTL_FILE</code> allows your PL/SQL programs to read and write operating system text files. It provides a restricted version of standard operating system stream file I/O, including open, put, get, and close operations. When you want to read or write a text file, you call the function <code>fopen</code>, which returns a file handle for use in subsequent procedure calls. For example, the procedure <code>put_line</code> writes a text string and line terminator to an open file, and the procedure <code>get_line</code> reads a line of text from an open file into an output buffer.</p> <div class="infoboxnotealso"> <p class="notep1">See Also:</p> <a class="olink ARPLS069" href="http://www.oracle.com/pls/db112/lookup?id=ARPLS069"><span class="italic">Oracle Database PL/SQL Packages and Types Reference</span></a> for more information on <code>UTL_FILE</code></div> <p><code>FSEEK</code>, a <code>UTL_FILE</code> subprogram, adjusts the file pointer forward or backward within the file by the number of bytes specified. In order for <code>UTL_FILE.FSEEK</code> to work correctly, the lines in the file must have platform-specific line terminator characters. On Windows platforms the correct line terminator characters are <code><CR><LF></code>.</p> </div> <!-- class="sect1" --> <a id="i1006153" name="i1006153"></a><a id="NTQRF491" name="NTQRF491"></a> <div class="sect1"><!-- infolevel="all" infotype="General" --> <h2 class="sect1"><a id="sthref742" name="sthref742"></a><a id="sthref743" name="sthref743"></a>Accessing Web Data with Intercartridge Exchange</h2> <p>This section discusses the following topics:</p> <ul> <li> <p><a href="#i1006172">Configuring Intercartridge Exchange</a></p> </li> <li> <p><a href="#i1006217">Using Intercartridge Exchange</a></p> </li> <li> <p><a href="#i1006289">UTL_HTTP Exception Conditions</a></p> </li> <li> <p><a href="#BACGGHHD">Exception Conditions and Error Messages</a></p> </li> </ul> <a id="i1006172" name="i1006172"></a><a id="NTQRF492" name="NTQRF492"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2"><a id="sthref744" name="sthref744"></a>Configuring Intercartridge Exchange</h3> <p>You must add a parameter to the <a href="glossary.htm#i432474"><span class="xrefglossterm">registry</span></a> before using Intercartridge Exchange.</p> <ol> <li> <p>Start Registry Editor from the command prompt:</p> <pre xml:space="preserve" class="oac_no_warn">C:\> regedit </pre> <p>The Registry Editor window appears.</p> <div class="infoboxnote"> <p class="notep1">Note:</p> For another way to configure your registry, see <a href="registry.htm#i1006146">"Managing Registry Parameters with regedit"</a></div> </li> <li> <p>Add <code>HTTP_PROXY</code> to the registry subkey of the Oracle home directory that you are using. The location of this parameter is determined by how many Oracle home directories are on your computer. If you have only one home directory, add <code>HTTP_PROXY</code> to</p> <pre xml:space="preserve" class="oac_no_warn">HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOME0. </pre> <p>If you have multiple home directory, add it to</p> <pre xml:space="preserve" class="oac_no_warn">HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\KEY_<span class="italic">HOME_NAME</span> </pre></li> <li> <p>Choose <span class="bold">Add Value</span> from the <span class="bold">Edit</span> menu.</p> <p>The Add Value dialog appears.</p> <img width="350" height="157" src="img/http.gif" alt="Description of http.gif follows" title="Description of http.gif follows" longdesc="img_text/http.htm" /><br /> <a id="sthref745" name="sthref745" href="img_text/http.htm">Description of the illustration http.gif</a><br /> <br /></li> <li> <p>Type <code>HTTP_PROXY</code> in the <span class="bold">Value Name</span> field and <code>REG_SZ</code> in the <span class="bold">Data Type</span> field.</p> </li> <li> <p>Click <span class="bold">OK</span>.</p> </li> <li> <p>Type <code>www-proxy.</code><code><span class="codeinlineitalic">your-site</span></code> in the <span class="bold">String</span> field.</p> <img width="379" height="115" src="img/http2.gif" alt="Description of http2.gif follows" title="Description of http2.gif follows" longdesc="img_text/http2.htm" /><br /> <a id="sthref746" name="sthref746" href="img_text/http2.htm">Description of the illustration http2.gif</a><br /> <br /></li> </ol> <p>In this example, the Web site is <code>marketing.com</code>. You will enter the domain name of your actual Web site.</p> </div> <!-- class="sect2" --> <a id="i1006217" name="i1006217"></a><a id="NTQRF493" name="NTQRF493"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2"><a id="sthref747" name="sthref747"></a><a id="sthref748" name="sthref748"></a><a id="sthref749" name="sthref749"></a><a id="sthref750" name="sthref750"></a><a id="sthref751" name="sthref751"></a>Using Intercartridge Exchange</h3> <p>Intercartridge Exchange enables you to use a stored package called <code>UTL_HTTP</code> to make Hypertext Transfer Protocol (HTTP) calls from PL/SQL, SQL, and SQL*Plus statements.</p> <p><code>UTL_HTTP</code> can do both of the following:</p> <ul> <li> <p>Access data on the Internet</p> </li> <li> <p>Call Oracle Web Application Server cartridges</p> </li> </ul> <p><code>UTL_HTTP</code> contains two similar entry points, known as packaged functions, that turn PL/SQL and SQL statements into HTTP callouts:</p> <ul> <li> <p><code>UTL_HTTP.REQUEST</code></p> </li> <li> <p><code>UTL_HTTP.REQUEST_PIECES</code></p> </li> </ul> <p>Both packaged functions perform the following tasks:</p> <ul> <li> <p>Take a string universal resource locator (URL) of a site</p> </li> <li> <p>Contact that site</p> </li> <li> <p>Return data (typically HTML) obtained from that site</p> </li> </ul> <p>Declarations to use with both packaged functions are described in the following subsections.</p> <a id="NTQRF494" name="NTQRF494"></a> <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref752" name="sthref752"></a> <h4 class="sect3"><a id="sthref753" name="sthref753"></a><a id="sthref754" name="sthref754"></a>Packaged Function UTL_HTTP.REQUEST</h4> <p><code>UTL_HTTP.REQUEST</code> uses a URL as its argument and returns up to the first 2000 bytes of data retrieved from that URL. Specify <code>UTL_HTTP.REQUEST</code> as follows:</p> <pre xml:space="preserve" class="oac_no_warn">FUNCTION REQUEST (URL IN VARCHAR2) RETURN VARCHAR2; </pre> <p>To use <code>UTL_HTTP.REQUEST</code> from SQL*Plus, enter:</p> <pre xml:space="preserve" class="oac_no_warn">SQL> SELECT UTL_HTTP.REQUEST('HTTP://WWW.ORACLE.COM/') FROM DUAL; </pre> <p>which returns:</p> <pre xml:space="preserve" class="oac_no_warn">UTL_HTTP.REQUEST('HTTP://WWW.ORACLE.COM/') ------------------------------------------------------ <html> <head><title>Oracle Home Page</title> <!--changed Jan. 16, 19 1 row selected. </pre></div> <!-- class="sect3" --> <a id="NTQRF495" name="NTQRF495"></a> <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref755" name="sthref755"></a> <h4 class="sect3"><a id="sthref756" name="sthref756"></a><a id="sthref757" name="sthref757"></a>Packaged Function UTL_HTTP.REQUEST_PIECES</h4> <p><code>UTL_HTTP.REQUEST_PIECES</code> uses a URL as its argument and returns a PL/SQL table of 2000 bytes of data retrieved from the given URL. The final element can be shorter than 2000 characters. The <code>UTL_HTTP.REQUEST_PIECES</code> return type is a PL/SQL table of type <code>UTL_HTTP.HTML_PIECES</code>.</p> <p><code>UTL_HTTP.REQUEST_PIECES</code>, which uses type <code>UTL_HTTP.HTML_PIECES</code>, is specified as:</p> <pre xml:space="preserve" class="oac_no_warn">type html_pieces is table of varchar2(2000) index by binary_integer; function request_pieces (url in varchar2, max_pieces natural default 32767) return html_pieces; </pre> <p>A call to <code>REQUEST_PIECES</code> can look like this example. Note the use of PL/SQL table method <code>COUNT</code> to discover the number of pieces returned; it can be zero or more:</p> <pre xml:space="preserve" class="oac_no_warn">declare pieces utl_http.html_pieces; begin pieces := utl_http.request_pieces('http://www.oracle.com/'); for i in 1 .. pieces.count loop .... -- process each piece end loop; end; </pre> <p>The second argument to <code>UTL_HTTP.REQUEST_PIECES</code> (<code>MAX_PIECES</code>) is optional. <code>MAX_PIECES</code> is the maximum number of pieces (each 2000 characters in length, except for the last, which can be shorter) that <code>UTL_HTTP.REQUEST_PIECES</code> returns. If provided, that argument is usually a positive integer.</p> <p>For example, the following block retrieves up to 100 pieces of data (each 2000 bytes, except perhaps the last) from the URL. The block prints the number of pieces retrieved and the total length, in bytes, of the data retrieved.</p> <pre xml:space="preserve" class="oac_no_warn">set serveroutput on declare x utl_http.html_pieces; begin x := utl_http.request_pieces('http://www.oracle.com/', 100); dbms_output.put_line(x.count || ' pieces were retrieved.'); dbms_output.put_line('with total length '); if x.count < 1 then dbms_output.put_line('0'); else dbms_output.put_line ((2000 * (x.count - 1)) + length(x(x.count))); end if; end; which displays: Statement processed. 4 pieces were retrieved. with total length 7687 </pre> <p>Elements of the PL/SQL table returned by <code>UTL_HTTP.REQUEST_PIECES</code> are successive pieces of data obtained from the HTTP request to that URL.</p> </div> <!-- class="sect3" --></div> <!-- class="sect2" --> <a id="i1006289" name="i1006289"></a><a id="NTQRF496" name="NTQRF496"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2"><a id="sthref758" name="sthref758"></a><a id="sthref759" name="sthref759"></a><a id="sthref760" name="sthref760"></a>UTL_HTTP Exception Conditions</h3> <p>This subsection describes exceptions (errors) that can be raised by packaged functions <code>UTL_HTTP.REQUEST</code> and <code>UTL_HTTP.REQUEST_PIECES</code>.</p> <a id="NTQRF497" name="NTQRF497"></a> <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref761" name="sthref761"></a> <h4 class="sect3">UTL_HTTP.REQUEST</h4> <p><code>PRAGMA</code> <code>RESTRICT_REFERENCES</code> enables display of exceptions:</p> <pre xml:space="preserve" class="oac_no_warn">create or replace package utl_http is function request (url in varchar2) return varchar2; pragma restrict_references (request, wnds, rnds, wnps, rnps); </pre></div> <!-- class="sect3" --> <a id="NTQRF498" name="NTQRF498"></a> <div class="sect3"><!-- infolevel="all" infotype="General" --><a id="sthref762" name="sthref762"></a> <h4 class="sect3">UTL_HTTP.REQUEST_PIECES</h4> <p><code>PRAGMA</code> <code>RESTRICT_REFERENCES</code> enables display of exceptions:</p> <pre xml:space="preserve" class="oac_no_warn">create or replace package utl_http is type html_pieces is table of varchar2(2000) index by binary_integer; function request_pieces (url in varchar2, max_pieces natural default 32767) return html_pieces; pragma restrict_references (request_pieces, wnds, rnds, wnps, rnps); </pre></div> <!-- class="sect3" --></div> <!-- class="sect2" --> <a id="BACGGHHD" name="BACGGHHD"></a><a id="NTQRF499" name="NTQRF499"></a> <div class="sect2"><!-- infolevel="all" infotype="General" --> <h3 class="sect2"><a id="sthref763" name="sthref763"></a><a id="sthref764" name="sthref764"></a>Exception Conditions and Error Messages</h3> <p>If initialization of the HTTP callout subsystem fails for environmental reasons (such as lack of available memory), then exception <code>UTL_HTTP.INIT_FAILED</code> is raised:</p> <pre xml:space="preserve" class="oac_no_warn">init_failed exception; </pre> <p>If the HTTP call fails due to failure of the HTTP daemon or because the argument to <code>REQUEST</code> or <code>REQUEST_PIECES</code> cannot be interpreted as a URL (because it is <code>NULL</code> or has non-HTTP syntax), then exception <code>UTL_HTTP.REQUEST_FAILED</code> is raised<code>:</code></p> <pre xml:space="preserve" class="oac_no_warn">request_failed exception; </pre> <p>Unless explicitly caught by an exception handler, these first two exceptions are reported by a generic message that shows them as "user-defined" exceptions, even though they are defined in this system package:</p> <pre xml:space="preserve" class="oac_no_warn">ORA-06510: PL/SQL: unhandled user-defined exception </pre> <p>If any other exception is raised during processing of the HTTP request (for example, an out-of-memory error), then function <code>UTL_HTTP.REQUEST</code> or <code>UTL_HTTP.REQUEST_PIECES</code> reraises that exception.</p> <p>If no response is received from a request to the given URL, because the function made no contact with a site corresponding to that URL, then a formatted HTML error message may be returned:</p> <pre xml:space="preserve" class="oac_no_warn"><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> </pre> <p>If <code>UTL_HTTP.REQUEST</code> or <code>UTL_HTTP.REQUEST_PIECES</code> raises an exception or returns an HTML-formatted error message, yet you believe that the URL argument is correct, try contacting that same URL with a browser to verify network availability from your computer.</p> </div> <!-- class="sect2" --></div> <!-- class="sect1" --></div> <!-- class="ind" --> <div class="footer"> <hr /> <table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%"> <col width="33%" /> <col width="*" /> <col width="33%" /> <tr> <td align="left"> <table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="98"> <tr> <td align="center" valign="top"><a href="registry.htm"><img width="24" height="24" src="../../dcommon/gifs/leftnav.gif" alt="Go to previous page" /><br /> <span class="icon">Previous</span></a></td> <td align="center" valign="top"><a href="ap_doc.htm"><img width="24" height="24" src="../../dcommon/gifs/rightnav.gif" alt="Go to next page" /><br /> <span class="icon">Next</span></a></td> </tr> </table> </td> <td style="font-size: 90%" align="center" class="copyrightlogo"><img width="144" height="18" src="../../dcommon/gifs/oracle.gif" alt="Oracle" /><br /> Copyright © 1996, 2010, Oracle and/or its affiliates. All rights reserved.<br /> <a href="../../dcommon/html/cpyr.htm">Legal Notices</a></td> <td align="right"> <table class="icons oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="245"> <tr> <td align="center" valign="top"><a href="../../index.htm"><img width="24" height="24" src="../../dcommon/gifs/doclib.gif" alt="Go to Documentation Home" /><br /> <span class="icon">Home</span></a></td> <td align="center" valign="top"><a href="../../nav/portal_booklist.htm"><img width="24" height="24" src="../../dcommon/gifs/booklist.gif" alt="Go to Book List" /><br /> <span class="icon">Book List</span></a></td> <td align="center" valign="top"><a href="toc.htm"><img width="24" height="24" src="../../dcommon/gifs/toc.gif" alt="Go to Table of Contents" /><br /> <span class="icon">Contents</span></a></td> <td align="center" valign="top"><a href="index.htm"><img width="24" height="24" src="../../dcommon/gifs/index.gif" alt="Go to Index" /><br /> <span class="icon">Index</span></a></td> <td align="center" valign="top"><a href="../../dcommon/html/feedback.htm"><img width="24" height="24" src="../../dcommon/gifs/feedbck2.gif" alt="Go to Feedback page" /><br /> <span class="icon">Contact Us</span></a></td> </tr> </table> </td> </tr> </table> </div> <noscript> <p>Scripting on this page enhances content navigation, but does not change the content in any way.</p> </noscript> </body> </html>
Ms-Dos/Windows
Unix
Write backup
jsp File Browser version 1.2 by
www.vonloesch.de