home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _16838d868abe5dafe020e8cc45627c04 < prev    next >
Text File  |  2000-03-23  |  30KB  |  698 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>DBD::Oracle - Oracle database driver for the DBI module</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> DBD::Oracle - Oracle database driver for the DBI module</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#connecting to oracle">CONNECTING TO ORACLE</A></LI>
  26.     <UL>
  27.  
  28.         <LI><A HREF="#connecting without environment variables or tnsname.ora file">Connecting without environment variables or tnsname.ora file</A></LI>
  29.         <LI><A HREF="#oracle environment variables">Oracle environment variables</A></LI>
  30.         <LI><A HREF="#connection examples using dbd::oracle">Connection Examples Using DBD::Oracle</A></LI>
  31.         <LI><A HREF="#optimizing oracle's listner">Optimizing Oracle's listner</A></LI>
  32.         <LI><A HREF="#oracle utilities">Oracle utilities</A></LI>
  33.         <LI><A HREF="#connect attributes">Connect Attributes</A></LI>
  34.     </UL>
  35.  
  36.     <LI><A HREF="#international nls / 8bit text issues">International NLS / 8-bit text issues</A></LI>
  37.     <LI><A HREF="#pl/sql examples">PL/SQL Examples</A></LI>
  38.     <LI><A HREF="#private database handle functions">Private database handle functions</A></LI>
  39.     <UL>
  40.  
  41.         <LI><A HREF="#plsql_errstr">plsql_errstr</A></LI>
  42.         <LI><A HREF="#dbms_output_enable / dbms_output_put / dbms_output_get">dbms_output_enable / dbms_output_put / dbms_output_get</A></LI>
  43.     </UL>
  44.  
  45.     <LI><A HREF="#using dbd::oracle with oracle 8  features and issues">Using DBD::Oracle with Oracle 8 - Features and Issues</A></LI>
  46.     <UL>
  47.  
  48.         <LI><A HREF="#prepare postponed till execute">Prepare postponed till execute</A></LI>
  49.         <LI><A HREF="#handling lobs">Handling LOBs</A></LI>
  50.         <LI><A HREF="#binding cursors">Binding Cursors</A></LI>
  51.     </UL>
  52.  
  53.     <LI><A HREF="#oracle related links">Oracle Related Links</A></LI>
  54.     <UL>
  55.  
  56.         <LI><A HREF="#oracle on linux">Oracle on Linux</A></LI>
  57.         <LI><A HREF="#free oracle tools and links">Free Oracle Tools and Links</A></LI>
  58.         <LI><A HREF="#commercial oracle tools and links">Commercial Oracle Tools and Links</A></LI>
  59.     </UL>
  60.  
  61.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  62.     <LI><A HREF="#author">AUTHOR</A></LI>
  63.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  64.     <LI><A HREF="#acknowledgements">ACKNOWLEDGEMENTS</A></LI>
  65. </UL>
  66. <!-- INDEX END -->
  67.  
  68. <HR>
  69. <P>
  70. <H1><A NAME="name">NAME</A></H1>
  71. <P>DBD::Oracle - Oracle database driver for the DBI module</P>
  72. <P>
  73. <HR>
  74. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  75. <UL>
  76. <LI>Windows</LI>
  77. </UL>
  78. <HR>
  79. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  80. <PRE>
  81.   use DBI;</PRE>
  82. <PRE>
  83.   $dbh = DBI->connect("dbi:Oracle:$dbname", $user, $passwd);</PRE>
  84. <PRE>
  85.   $dbh = DBI->connect("dbi:Oracle:host=$host;sid=$sid", $user, $passwd);</PRE>
  86. <PRE>
  87.   # See the DBI module documentation for full details</PRE>
  88. <PRE>
  89.   # for some advanced uses you may need Oracle type values:
  90.   use DBD::Oracle qw(:ora_types);</PRE>
  91. <P>
  92. <HR>
  93. <H1><A NAME="description">DESCRIPTION</A></H1>
  94. <P>DBD::Oracle is a Perl module which works with the DBI module to provide
  95. access to Oracle databases (both version 7 and 8).</P>
  96. <P>
  97. <HR>
  98. <H1><A NAME="connecting to oracle">CONNECTING TO ORACLE</A></H1>
  99. <P>This is a topic which often causes problems. Mainly due to Oracle's many
  100. and sometimes complex ways of specifying and connecting to databases.
  101. (James Taylor and Lane Sharman have contributed much of the text in
  102. this section.)</P>
  103. <P>
  104. <H2><A NAME="connecting without environment variables or tnsname.ora file">Connecting without environment variables or tnsname.ora file</A></H2>
  105. <P>If you use the <CODE>host=$host;sid=$sid</CODE> style syntax, for example:</P>
  106. <PRE>
  107.   $dbh = DBI->connect("dbi:Oracle:host=myhost.com;sid=ORCL", $user, $passwd);</PRE>
  108. <P>then DBD::Oracle will construct a full connection descriptor string
  109. for you and Oracle will not need to consult the tnsname.ora file.
  110. If a <CODE>port</CODE> number is not specified then the descriptor try
  111. both 1526 and 1521 in that order.</P>
  112. <P>
  113. <H2><A NAME="oracle environment variables">Oracle environment variables</A></H2>
  114. <P>Oracle typically uses two environment variables to specify default
  115. connections: ORACLE_SID and TWO_TASK.</P>
  116. <P>ORACLE_SID is really unnecessary to set since TWO_TASK provides the
  117. same functionality in addition to allowing remote connections.</P>
  118. <PRE>
  119.   % setenv TWO_TASK T:hostname:ORACLE_SID            # for csh shell
  120.   $ TWO_TASK=T:hostname:ORACLE_SID export TWO_TASK   # for sh shell</PRE>
  121. <PRE>
  122.   % sqlplus username/password</PRE>
  123. <P>Note that if you have *both* local and remote databases, and you
  124. have ORACLE_SID *and* TWO_TASK set, and you don't specify a fully
  125. qualified connect string on the command line, TWO_TASK takes precedence
  126. over ORACLE_SID (i.e. you get connected to remote system).</P>
  127. <PRE>
  128.   TWO_TASK=P:sid</PRE>
  129. <P>will use the pipe driver for local connections using SQL*Net v1.</P>
  130. <PRE>
  131.   TWO_TASK=T:machine:sid</PRE>
  132. <P>will use TCP/IP (or D for DECNET, etc.) for remote SQL*Net v1 connection.</P>
  133. <PRE>
  134.   TWO_TASK=dbname</PRE>
  135. <P>will use the info stored in the SQL*Net v2 <EM>tnsnames.ora</EM>
  136. configuration file for local or remote connections.</P>
  137. <P>The ORACLE_HOME environment variable should be set correctly. It can be
  138. left unset if you aren't using any of Oracle's executables, but it is
  139. not recommended and error messages may not display.</P>
  140. <P>Discouraging the use of ORACLE_SID makes it easier on the users to see
  141. what is going on. (It's unfortunate that TWO_TASK couldn't be renamed,
  142. since it makes no sense to the end user, and doesn't have the ORACLE
  143. prefix).</P>
  144. <P>
  145. <H2><A NAME="connection examples using dbd::oracle">Connection Examples Using DBD::Oracle</A></H2>
  146. <P>Below are various ways of connecting to an oracle database using
  147. SQL*Net 1.x and SQL*Net 2.x.  ``Machine'' is the computer the database is
  148. running on, ``SID'' is the SID of the database, ``DB'' is the SQL*Net 2.x
  149. connection descriptor for the database.</P>
  150. <P><STRONG>Note:</STRONG> Some of these formats may not work with Oracle 8.</P>
  151. <PRE>
  152.   BEGIN {
  153.      $ENV{ORACLE_HOME} = '/home/oracle/product/7.x.x';
  154.      $ENV{TWO_TASK}    = 'DB';
  155.   }
  156.   $dbh = DBI->connect('dbi:Oracle:','scott', 'tiger');
  157.   #  - or -
  158.   $dbh = DBI->connect('dbi:Oracle:','scott/tiger');</PRE>
  159. <P>works for SQL*Net 2.x, so does</P>
  160. <PRE>
  161.   $ENV{TWO_TASK}    = 'T:Machine:SID';</PRE>
  162. <P>for SQL*Net 1.x connections.  For local connections you can use the
  163. pipe driver:</P>
  164. <PRE>
  165.   $ENV{TWO_TASK}    = 'P:SID';</PRE>
  166. <P>Here are some variations (not setting TWO_TASK)</P>
  167. <PRE>
  168.   $dbh = DBI->connect('dbi:Oracle:T:Machine:SID','username','password')</PRE>
  169. <PRE>
  170.   $dbh = DBI->connect('dbi:Oracle:','username@T:Machine:SID','password')</PRE>
  171. <PRE>
  172.   $dbh = DBI->connect('dbi:Oracle:','username@DB','password')</PRE>
  173. <PRE>
  174.   $dbh = DBI->connect('dbi:Oracle:DB','username','password')</PRE>
  175. <PRE>
  176.   $dbh = DBI->connect('dbi:Oracle:DB','username/password','')</PRE>
  177. <PRE>
  178.   $dbh = DBI->connect('dbi:Oracle:host=foobar;sid=ORCL;port=1521', 'scott/tiger', '')</PRE>
  179. <PRE>
  180.   $dbh = DBI->connect('dbi:Oracle:', q{scott/tiger@(DESCRIPTION=
  181.   (ADDRESS=(PROTOCOL=TCP)(HOST= foobar)(PORT=1521))
  182.   (CONNECT_DATA=(SID=ORCL)))}, "")</PRE>
  183. <P>If you are having problems with login taking a long time (>10 secs say)
  184. then you might have tripped up on an Oracle bug. You can try using one
  185. of the ...@DB variants as a workaround. E.g.,</P>
  186. <PRE>
  187.   $dbh = DBI->connect('','username/password@DB','');</PRE>
  188. <P>On the other hand, that may cause you to trip up on another Oracle bug
  189. that causes alternating connection attempts to fail! (In reality only
  190. a small proportion of people experience these problems.)</P>
  191. <P>
  192. <H2><A NAME="optimizing oracle's listner">Optimizing Oracle's listner</A></H2>
  193. <P>[By Lane Sharman <<A HREF="mailto:lane@bienlogic.com">lane@bienlogic.com</A>>] I spent a LOT of time optimizing
  194. listener.ora and I am including it here for anyone to benefit from. My
  195. connections over tnslistener on the same humble Netra 1 take an average
  196. of 10-20 milli seconds according to tnsping. If anyone knows how to
  197. make it better, please let me know!</P>
  198. <PRE>
  199.  LISTENER =
  200.   (ADDRESS_LIST =
  201.     (ADDRESS =
  202.       (PROTOCOL = TCP)
  203.       (Host = aa.bbb.cc.d)
  204.       (Port = 1521)
  205.       (QUEUESIZE=10)
  206.     )
  207.   )</PRE>
  208. <PRE>
  209.  STARTUP_WAIT_TIME_LISTENER = 0
  210.  CONNECT_TIMEOUT_LISTENER = 10
  211.  TRACE_LEVEL_LISTENER = OFF
  212.  SID_LIST_LISTENER =
  213.   (SID_LIST =
  214.     (SID_DESC =
  215.       (SID_NAME = xxxx)
  216.       (ORACLE_HOME = /xxx/local/oracle7-3)
  217.         (PRESPAWN_MAX = 40)
  218.         (PRESPAWN_LIST=
  219.         (PRESPAWN_DESC=(PROTOCOL=tcp) (POOL_SIZE=40) (TIMEOUT=120))
  220.       )
  221.     )
  222.   )</PRE>
  223. <P>1) When the application is co-located on the host AND there is no need for
  224. outside SQLNet connectivity, stop the listener. You do not need it. Get
  225. your application/cgi/whatever working using pipes and shared memory. I am
  226. convinced that this is one of the connection bugs (sockets over the same
  227. machine). Note the $ENV{ORAPIPES} env var.  The essential code to do
  228. this at the end of this section.</P>
  229. <P>2) Be careful in how you implement the multi-threaded server. Currently I
  230. am not using it in the initxxxx.ora file but will be doing some more testing.</P>
  231. <P>3) Be sure to create user rollback segments and use them; do not use the
  232. system rollback segments; however, you must also create a small rollback
  233. space for the system as well.</P>
  234. <P>5) Use large tuning settings and get lots of RAM. Check out all the
  235. parameters you can set in v$parameters because there are quite a few not
  236. documented you may to set in your initxxx.ora file.</P>
  237. <P>6) Use svrmgrl to control oracle from the command line. Write lots of small
  238. SQL scripts to get at V$ info.</P>
  239. <PRE>
  240.   use DBI;
  241.   # Environmental variables used by Oracle
  242.   $ENV{ORACLE_SID}   = "xxx";
  243.   $ENV{ORACLE_HOME}  = "/opt/oracle7";
  244.   $ENV{EPC_DISABLED} = "TRUE";
  245.   $ENV{ORAPIPES} = "V2";
  246.   my $dbname = "xxx";
  247.   my $dbuser = "xxx";
  248.   my $dbpass = "xxx";
  249.   my $dbh = DBI->connect("dbi:Oracle:$dbname", $dbuser, $dbpass)
  250.              || die "Unale to connect to $dbname: $DBI::errstr\n";</PRE>
  251. <P>
  252. <H2><A NAME="oracle utilities">Oracle utilities</A></H2>
  253. <P>If you are still having problems connecting then the Oracle adapters
  254. utility may offer some help. Run these two commands:</P>
  255. <PRE>
  256.   $ORACLE_HOME/bin/adapters
  257.   $ORACLE_HOME/bin/adapters $ORACLE_HOME/bin/sqlplus</PRE>
  258. <P>and check the output. The ``Protocol Adapters'' section should be the
  259. same.  It should include at least ``IPC Protocol Adapter'' and ``TCP/IP
  260. Protocol Adapter''.</P>
  261. <P>If it generates any errors which look relevant then please talk to yor
  262. Oracle technical support (and not the dbi-users mailing list). Thanks.
  263. Thanks to Mark Dedlow for this information.</P>
  264. <P>
  265. <H2><A NAME="connect attributes">Connect Attributes</A></H2>
  266. <P>The ora_session_mode attribute can be used to connect with SYSDBA
  267. authorization and SYSOPER authorization.</P>
  268. <PRE>
  269.   $mode = 2;    # SYSDBA
  270.   $mode = 4;    # SYSOPER
  271.   DBI->connect($dsn, $user, $passwd, { ora_session_mode => $mode });</PRE>
  272. <P>
  273. <HR>
  274. <H1><A NAME="international nls / 8bit text issues">International NLS / 8-bit text issues</A></H1>
  275. <P>If 8-bit text is returned as '?' characters or can't be inserted
  276. make sure the following environment vaiables are set correctly:
  277.     NLS_LANG, ORA_NLS, ORA_NLS32, ORA_NLS33
  278. Thanks to Robin Langdon <<A HREF="mailto:robin@igis.se">robin@igis.se</A>> for this information.
  279. Example:
  280.    $ENV{NLS_LANG}  = ``american_america.we8iso8859p1'';
  281.    $ENV{ORA_NLS}   = ``$ENV{ORACLE_HOME}/ocommon/nls/admin/data'';</P>
  282. <P>Also From: Yngvi Thor Sigurjonsson <<A HREF="mailto:yngvi@hagkaup.is">yngvi@hagkaup.is</A>>
  283. If you are using 8-bit characters and ``export'' for backups make sure
  284. that you have NLS_LANG set when export is run.  Otherwise you might get
  285. unusable backups with ? replacing all your beloved characters. We were
  286. lucky once when we noticed that our exports were damaged before
  287. disaster struck.</P>
  288. <P>Remember that the database has to be created with an 8-bit character set.</P>
  289. <P>Also note that the NLS files $ORACLE_HOME/ocommon/nls/admin/data
  290. changed extension (from .d to .nlb) between 7.2.3 and 7.3.2.</P>
  291. <P>
  292. <HR>
  293. <H1><A NAME="pl/sql examples">PL/SQL Examples</A></H1>
  294. <P>These PL/SQL examples come from: Eric Bartley <<A HREF="mailto:bartley@cc.purdue.edu">bartley@cc.purdue.edu</A>>.</P>
  295. <PRE>
  296.   # we assume this package already exists
  297.   my $plsql = q{</PRE>
  298. <PRE>
  299.     CREATE OR REPLACE PACKAGE plsql_example
  300.     IS
  301.       PROCEDURE proc_np;</PRE>
  302. <PRE>
  303.       PROCEDURE proc_in (
  304.           err_code IN NUMBER
  305.       );</PRE>
  306. <PRE>
  307.       PROCEDURE proc_in_inout (
  308.           test_num IN NUMBER,
  309.           is_odd IN OUT NUMBER
  310.       );</PRE>
  311. <PRE>
  312.       FUNCTION func_np
  313.         RETURN VARCHAR2;</PRE>
  314. <PRE>
  315.     END plsql_example;</PRE>
  316. <PRE>
  317.     CREATE OR REPLACE PACKAGE BODY plsql_example
  318.     IS
  319.       PROCEDURE proc_np
  320.       IS
  321.         whoami VARCHAR2(20) := NULL;
  322.       BEGIN
  323.         SELECT USER INTO whoami FROM DUAL;
  324.       END;</PRE>
  325. <PRE>
  326.       PROCEDURE proc_in (
  327.         err_code IN NUMBER
  328.       )
  329.       IS
  330.       BEGIN
  331.         RAISE_APPLICATION_ERROR(err_code, 'This is a test.');
  332.       END;</PRE>
  333. <PRE>
  334.       PROCEDURE proc_in_inout (
  335.         test_num IN NUMBER,
  336.         is_odd IN OUT NUMBER
  337.       )
  338.       IS
  339.       BEGIN
  340.         is_odd := MOD(test_num, 2);
  341.       END;</PRE>
  342. <PRE>
  343.       FUNCTION func_np
  344.         RETURN VARCHAR2
  345.       IS
  346.         ret_val VARCHAR2(20);
  347.       BEGIN
  348.         SELECT USER INTO ret_val FROM DUAL;
  349.         RETURN ret_val;
  350.       END;</PRE>
  351. <PRE>
  352.     END plsql_example;
  353.   };</PRE>
  354. <PRE>
  355.   use DBI;</PRE>
  356. <PRE>
  357.   my($db, $csr, $ret_val);</PRE>
  358. <PRE>
  359.   $db = DBI->connect('dbi:Oracle:database','user','password')
  360.         or die "Unable to connect: $DBI::errstr";</PRE>
  361. <PRE>
  362.   # So we don't have to check every DBI call we set RaiseError.
  363.   # See the DBI docs now if you're not familiar with RaiseError.
  364.   $db->{RaiseError} = 1;</PRE>
  365. <PRE>
  366.   # Example 1
  367.   #
  368.   # Calling a PLSQL procedure that takes no parameters. This shows you the
  369.   # basic's of what you need to execute a PLSQL procedure. Just wrap your
  370.   # procedure call in a BEGIN END; block just like you'd do in SQL*Plus.
  371.   #
  372.   # p.s. If you've used SQL*Plus's exec command all it does is wrap the
  373.   #      command in a BEGIN END; block for you.</PRE>
  374. <PRE>
  375.   $csr = $db->prepare(q{
  376.     BEGIN
  377.       PLSQL_EXAMPLE.PROC_NP;
  378.     END;
  379.   });
  380.   $csr->execute;</PRE>
  381. <PRE>
  382.   # Example 2
  383.   #
  384.   # Now we call a procedure that has 1 IN parameter. Here we use bind_param
  385.   # to bind out parameter to the prepared statement just like you might
  386.   # do for an INSERT, UPDATE, DELETE, or SELECT statement.
  387.   #
  388.   # I could have used positional placeholders (e.g. :1, :2, etc.) or
  389.   # ODBC style placeholders (e.g. ?), but I prefer Oracle's named
  390.   # placeholders (but few DBI drivers support them so they're not portable).</PRE>
  391. <PRE>
  392.   my $err_code = -20001;</PRE>
  393. <PRE>
  394.   $csr = $db->prepare(q{
  395.         BEGIN
  396.             PLSQL_EXAMPLE.PROC_IN(:err_code);
  397.         END;
  398.   });</PRE>
  399. <PRE>
  400.   $csr->bind_param(":err_code", $err_code);</PRE>
  401. <PRE>
  402.   # PROC_IN will RAISE_APPLICATION_ERROR which will cause the execute to 'fail'.
  403.   # Because we set RaiseError, the DBI will croak (die) so we catch that with eval.
  404.   eval {
  405.     $csr->execute;
  406.   };
  407.   print 'After proc_in: $@=',"'$@', errstr=$DBI::errstr, ret_val=$ret_val\n";</PRE>
  408. <PRE>
  409.   # Example 3
  410.   #
  411.   # Building on the last example, I've added 1 IN OUT parameter. We still
  412.   # use a placeholders in the call to prepare, the difference is that
  413.   # we now call bind_param_inout to bind the value to the place holder.
  414.   #
  415.   # Note that the third parameter to bind_param_inout is the maximum size
  416.   # of the variable. You normally make this slightly larger than necessary.
  417.   # But note that the perl variable will have that much memory assigned to
  418.   # it even if the actual value returned is shorter.</PRE>
  419. <PRE>
  420.   my $test_num = 5;
  421.   my $is_odd;</PRE>
  422. <PRE>
  423.   $csr = $db->prepare(q{
  424.         BEGIN
  425.             PLSQL_EXAMPLE.PROC_IN_INOUT(:test_num, :is_odd);
  426.         END;
  427.   });</PRE>
  428. <PRE>
  429.   # The value of $test_num is _copied_ here
  430.   $csr->bind_param(":test_num", $test_num);</PRE>
  431. <PRE>
  432.   $csr->bind_param_inout(":is_odd", \$is_odd, 1);</PRE>
  433. <PRE>
  434.   # The execute will automagically update the value of $is_odd
  435.   $csr->execute;</PRE>
  436. <PRE>
  437.   print "$test_num is ", ($is_odd) ? "odd - ok" : "even - error!", "\n";</PRE>
  438. <PRE>
  439.   # Example 4
  440.   #
  441.   # What about the return value of a PLSQL function? Well treat it the same
  442.   # as you would a call to a function from SQL*Plus. We add a placeholder
  443.   # for the return value and bind it with a call to bind_param_inout so
  444.   # we can access it's value after execute.</PRE>
  445. <PRE>
  446.   my $whoami = "";</PRE>
  447. <PRE>
  448.   $csr = $db->prepare(q{
  449.         BEGIN
  450.             :whoami := PLSQL_EXAMPLE.FUNC_NP;
  451.         END;
  452.   });</PRE>
  453. <PRE>
  454.   $csr->bind_param_inout(":whoami", \$whoami, 20);
  455.   $csr->execute;
  456.   print "Your database user name is $whoami\n";</PRE>
  457. <PRE>
  458.   $db->disconnect;</PRE>
  459. <P>You can find more examples in the t/plsql.t file in the DBD::Oracle
  460. source directory.</P>
  461. <P>
  462. <HR>
  463. <H1><A NAME="private database handle functions">Private database handle functions</A></H1>
  464. <P>These functions are called through the method <CODE>func()</CODE>
  465. which is described in the DBI documentation.</P>
  466. <P>
  467. <H2><A NAME="plsql_errstr">plsql_errstr</A></H2>
  468. <P>This function returns a string which describes the errors
  469. from the most recent PL/SQL function, procedure, package,
  470. or package body compile in a format similar to the output
  471. of the SQL*Plus command 'show errors'.</P>
  472. <P>The function returns undef if the error string could not
  473. be retrieved due to a database error.
  474. Look in $dbh->errstr for the cause of the failure.</P>
  475. <P>If there are no compile errors, an empty string is returned.</P>
  476. <P>Example:</P>
  477. <PRE>
  478.     # Show the errors if CREATE PROCEDURE fails
  479.     $dbh->{RaiseError} = 0;
  480.     if ( $dbh->do( q{
  481.         CREATE OR REPLACE PROCEDURE perl_dbd_oracle_test as
  482.         BEGIN
  483.             PROCEDURE filltab( stuff OUT TAB ); asdf
  484.         END; } ) ) {} # Statement succeeded
  485.     }
  486.     elsif ( 6550 != $dbh->err ) { die $dbh->errstr; } # Utter failure
  487.     my $msg = $dbh->func( 'plsql_errstr' );
  488.     die $dbh->errstr if ! defined $msg;
  489.     die $msg if $msg;</PRE>
  490. <P>
  491. <H2><A NAME="dbms_output_enable / dbms_output_put / dbms_output_get">dbms_output_enable / dbms_output_put / dbms_output_get</A></H2>
  492. <P>These functions use the PL/SQL DBMS_OUTPUT package to store and
  493. retrieve text using the DBMS_OUTPUT buffer.  Text stored in this buffer
  494. by dbms_output_put or any PL/SQL block can be retrieved by
  495. dbms_output_get or any PL/SQL block connected to the same database
  496. session.</P>
  497. <P>Stored text is not available until after dbms_output_put or the PL/SQL
  498. block that saved it completes its execution.  This means you <STRONG>CAN NOT</STRONG>
  499. use these functions to monitor long running PL/SQL procedures.</P>
  500. <P>Example 1:</P>
  501. <PRE>
  502.   # Enable DBMS_OUTPUT and set the buffer size
  503.   $dbh->{RaiseError} = 1;
  504.   $dbh->func( 1000000, 'dbms_output_enable' );</PRE>
  505. <PRE>
  506.   # Put text in the buffer . . .
  507.   $dbh->func( @text, 'dbms_output_put' );</PRE>
  508. <PRE>
  509.   # . . . and retreive it later
  510.   @text = $dbh->func( 'dbms_output_get' );</PRE>
  511. <P>Example 2:</P>
  512. <PRE>
  513.   $dbh->{RaiseError} = 1;
  514.   $sth = $dbh->prepare(q{
  515.     DECLARE tmp VARCHAR2(50);
  516.     BEGIN
  517.       SELECT SYSDATE INTO tmp FROM DUAL;
  518.       dbms_output.put_line('The date is '||tmp);
  519.     END;
  520.   });
  521.   $sth->execute;</PRE>
  522. <PRE>
  523.   # retreive the string
  524.   $date_string = $dbh->func( 'dbms_output_get' );</PRE>
  525. <DL>
  526. <DT><STRONG><A NAME="item_dbms_output_enable">dbms_output_enable ( [ buffer_size ] )</A></STRONG><BR>
  527. <DD>
  528. This function calls DBMS_OUTPUT.ENABLE to enable calls to package
  529. DBMS_OUTPUT procedures GET, GET_LINE, PUT, and PUT_LINE.  Calls to
  530. these procedures are ignored unless DBMS_OUTPUT.ENABLE is called
  531. first.
  532. <P>The buffer_size is the maximum amount of text that can be saved in the
  533. buffer and must be between 2000 and 1,000,000.  If buffer_size is not
  534. given, the default is 20,000 bytes.</P>
  535. <P></P>
  536. <DT><STRONG><A NAME="item_dbms_output_put">dbms_output_put ( [ @lines ] )</A></STRONG><BR>
  537. <DD>
  538. This function calls DBMS_OUTPUT.PUT_LINE to add lines to the buffer.
  539. <P>If all lines were saved successfully the function returns 1.  Depending
  540. on the context, an empty list or undef is returned for failure.</P>
  541. <P>If any line causes buffer_size to be exceeded, a buffer overflow error
  542. is raised and the function call fails.  Some of the text might be in
  543. the buffer.</P>
  544. <P></P>
  545. <DT><STRONG><A NAME="item_dbms_output_get">dbms_output_get</A></STRONG><BR>
  546. <DD>
  547. This function calls DBMS_OUTPUT.GET_LINE to retrieve lines of text from
  548. the buffer.
  549. <P>In an array context, all complete lines are removed from the buffer and
  550. returned as a list.  If there are no complete lines, an empty list is
  551. returned.</P>
  552. <P>In a scalar context, the first complete line is removed from the buffer
  553. and returned.  If there are no complete lines, undef is returned.</P>
  554. <P>Any text in the buffer after a call to DBMS_OUTPUT.GET_LINE or
  555. DBMS_OUTPUT.GET is discarded by the next call to DBMS_OUTPUT.PUT_LINE,
  556. DBMS_OUTPUT.PUT, or DBMS_OUTPUT.NEW_LINE.</P>
  557. <P></P></DL>
  558. <P>
  559. <HR>
  560. <H1><A NAME="using dbd::oracle with oracle 8  features and issues">Using DBD::Oracle with Oracle 8 - Features and Issues</A></H1>
  561. <P>DBD::Oracle version 0.55 onwards can be built to use either the Oracle 7
  562. or Oracle 8 OCI (Oracle Call Interface) API functions. The new Oracle 8
  563. API is used by default and offers several advantages, including support
  564. for LOB types and cursor binding. Here's a quote from the Oracle OCI
  565. documentation:</P>
  566. <PRE>
  567.   The Oracle8 OCI has several enhancements to improve application
  568.   performance and scalability. Application performance has been improved
  569.   by reducing the number of client to server round trips required and
  570.   scalability improvements have been facilitated by reducing the amount
  571.   of state information that needs to be retained on the server side.</PRE>
  572. <P>
  573. <H2><A NAME="prepare postponed till execute">Prepare postponed till execute</A></H2>
  574. <P>The DBD::Oracle module will avoid an explicit 'describe' operation
  575. prior to the execution of the statement unless the application requests
  576. information about the results (such as $sth->{NAME}). This reduces
  577. communication with the server and increases performance. However, it also
  578. means that SQL errors are not detected until <CODE>execute()</CODE> is called
  579. (instead of <CODE>prepare()</CODE> as now).</P>
  580. <P>
  581. <H2><A NAME="handling lobs">Handling LOBs</A></H2>
  582. <P>When fetching LOBs, they are treated just like LONGs and are subject to
  583. $sth->{LongReadLen} and $sth->{LongTruncOk}. Note that with OCI 7
  584. DBD::Oracle pre-allocates the whole buffer (LongReadLen) before
  585. constructing the returned column.  With OCI 8 it grows the buffer to
  586. the amount needed for the largest LOB to be fetched so far.</P>
  587. <P>When inserting or updating LOBs some <EM>major</EM> magic has to be performed
  588. behind the scenes to make it transparent.  Basically the driver has to
  589. refetch the newly inserted 'LOB Locators' before being able to write to
  590. them.  However, it works, and I've made it as fast as possible, just
  591. one extra server-round-trip per insert or update after the first.
  592. For the time being, only single-row LOB updates are supported. Also
  593. passing LOBS to PL/SQL blocks doesn't work.</P>
  594. <P>To insert or update a large LOB, DBD::Oracle has to know in advance
  595. that it is a LOB type. So you need to say:</P>
  596. <PRE>
  597.   $sth->bind_param($field_num, $lob_value, { ora_type => ORA_CLOB });</PRE>
  598. <P>The ORA_CLOB and ORA_BLOB constants can be imported using</P>
  599. <PRE>
  600.   use DBD::Oracle qw(:ora_types);</PRE>
  601. <P>or just use the corresponding integer values (112 and 113).</P>
  602. <P>To make scripts work with both Oracle7 and Oracle8, the Oracle7
  603. DBD::Oracle will treat the LOB ora_types as LONGs without error.
  604. So in any code you may have now that looks like</P>
  605. <PRE>
  606.   $sth->bind_param($idx, $value, { ora_type => 8 });</PRE>
  607. <P>you could change the 8 (LONG type) to ORA_CLOB or ORA_BLOB
  608. (112 or 113).</P>
  609. <P>One further wrinkle: for inserts and updates of LOBs, DBD::Oracle has
  610. to be able to tell which parameters relate to which table fields.
  611. In all cases where it can possibly work it out for itself, it does,
  612. however, if there are multiple LOB fields of the same type in the table
  613. then you need to tell it which field each LOB param relates to:</P>
  614. <PRE>
  615.   $sth->bind_param($idx, $value, { ora_type=>ORA_CLOB, ora_field=>'foo' });</PRE>
  616. <P>
  617. <H2><A NAME="binding cursors">Binding Cursors</A></H2>
  618. <P>Cursors can now be returned from PL/SQL blocks. Either from stored
  619. procedure OUT parameters or from direct <CODE>OPEN</CODE> statements, as show below:</P>
  620. <PRE>
  621.   use DBI;
  622.   use DBD::Oracle qw(:ora_types);
  623.   $dbh = DBI->connect(...);
  624.   $sth1 = $dbh->prepare(q{
  625.       BEGIN OPEN :cursor FOR
  626.           SELECT table_name, tablespace_name
  627.           FROM user_tables WHERE tablespace_name = :space
  628.       END;
  629.   });
  630.   $sth1->bind_param(":space", "USERS");
  631.   my $sth2;
  632.   $sth1->bind_param_inout(":cursor", \$sth2, 0, { ora_type => ORA_RSET } );
  633.   $sth1->execute();
  634.   # $sth2 is now a valid DBI statement handle for the cursor
  635.   while ( @row = $sth2->fetchrow_array ) { ... }</PRE>
  636. <P>The only special requirement is the use of <CODE>bind_param_inout()</CODE> with an
  637. attribute hash parameter that specifies <CODE>ora_type</CODE> as <CODE>ORA_RSET</CODE>.
  638. If you don't do that you'll get an error from the <CODE>execute()</CODE> like:
  639. ``ORA-06550: line X, column Y: PLS-00306: wrong number or types of
  640. arguments in call to ...''.</P>
  641. <P>
  642. <HR>
  643. <H1><A NAME="oracle related links">Oracle Related Links</A></H1>
  644. <P>
  645. <H2><A NAME="oracle on linux">Oracle on Linux</A></H2>
  646. <PRE>
  647.   <A HREF="http://www.datamgmt.com/maillist.html">http://www.datamgmt.com/maillist.html</A>
  648.   <A HREF="http://www.eGroups.com/list/oracle-on-linux">http://www.eGroups.com/list/oracle-on-linux</A>
  649.   <A HREF="http://www.wmd.de/wmd/staff/pauck/misc/oracle_on_linux.html">http://www.wmd.de/wmd/staff/pauck/misc/oracle_on_linux.html</A>
  650.   <A HREF="ftp://oracle-ftp.oracle.com/server/patch_sets/LINUX">ftp://oracle-ftp.oracle.com/server/patch_sets/LINUX</A></PRE>
  651. <P>
  652. <H2><A NAME="free oracle tools and links">Free Oracle Tools and Links</A></H2>
  653. <PRE>
  654.   ora_explain supplied and installed with DBD::Oracle.</PRE>
  655. <PRE>
  656.   <A HREF="http://vonnieda.org/oracletool/">http://vonnieda.org/oracletool/</A></PRE>
  657. <P>
  658. <H2><A NAME="commercial oracle tools and links">Commercial Oracle Tools and Links</A></H2>
  659. <P>Assorted tools and references for general information.
  660. No recommendation implied.</P>
  661. <PRE>
  662.   <A HREF="http://www.platinum.com/products/oracle.htm">http://www.platinum.com/products/oracle.htm</A>
  663.   <A HREF="http://www.SoftTreeTech.com">http://www.SoftTreeTech.com</A>
  664.   <A HREF="http://www.databasegroup.com">http://www.databasegroup.com</A></PRE>
  665. <P>Also PL/Vision from RevealNet and Steven Feuerstein, and
  666. ``Q'' from Savant Corporation.</P>
  667. <P>
  668. <HR>
  669. <H1><A NAME="see also">SEE ALSO</A></H1>
  670. <P><A HREF="../../../site/lib/DBI.html">the DBI manpage</A></P>
  671. <P>
  672. <HR>
  673. <H1><A NAME="author">AUTHOR</A></H1>
  674. <P>DBD::Oracle by Tim Bunce. DBI by Tim Bunce.</P>
  675. <P>
  676. <HR>
  677. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  678. <P>The DBD::Oracle module is Copyright (c) 1995,1996,1997,1998,1999 Tim Bunce. England.
  679. The DBD::Oracle module is free software; you can redistribute it and/or
  680. modify it under the same terms as Perl itself with the exception that it
  681. cannot be placed on a CD-ROM or similar media for commercial distribution
  682. without the prior approval of the author.</P>
  683. <P>
  684. <HR>
  685. <H1><A NAME="acknowledgements">ACKNOWLEDGEMENTS</A></H1>
  686. <P>A great many people have helped me over the years. Far too many to
  687. name, but I thank them all.</P>
  688. <P>See also <A HREF="../../../site/lib/DBI/acknowledgements.html">ACKNOWLEDGEMENTS in the DBI manpage</A>.</P>
  689. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  690. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  691. <STRONG><P CLASS=block> DBD::Oracle - Oracle database driver for the DBI module</P></STRONG>
  692. </TD></TR>
  693. </TABLE>
  694.  
  695. </BODY>
  696.  
  697. </HTML>
  698.