<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.30 $ -->
 <reference id="ref.oracle">
  <title>Oracle functions</title>
  <titleabbrev>Oracle</titleabbrev>

  <refentry id="function.ora-bind">
   <refnamediv>
    <refname>Ora_Bind</refname>
    <refpurpose>bind a PHP variable to an Oracle parameter</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_bind</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
      <methodparam><type>string</type><parameter>PHP variable name</parameter></methodparam>
      <methodparam><type>string</type><parameter>SQL parameter name</parameter></methodparam>
      <methodparam><type>int</type><parameter>length</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>type</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if the bind succeeds, otherwise &false;. Details
     about the error can be retrieved using the
     <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
    <para>
     This function binds the named PHP variable with a SQL parameter.
     The SQL parameter must be in the form ":name". With the optional
     type parameter, you can define whether the SQL parameter is an
     in/out (0, default), in (1) or out (2) parameter. As of PHP
     3.0.1, you can use the constants ORA_BIND_INOUT, ORA_BIND_IN and
     ORA_BIND_OUT instead of the numbers.
    </para>
    <para>
     ora_bind must be called after <function>ora_parse</function> and
     before <function>ora_exec</function>. Input values can be given  
     by assignment to the bound PHP variables, after calling 
     <function>ora_exec</function> the bound PHP variables contain the output
     values if available. 
     <informalexample>
      <programlisting role="php">
<![CDATA[
<?php
ora_parse($curs, "declare tmp INTEGER; begin tmp := :in; :out := tmp; :x := 7.77; end;");
ora_bind($curs, "result", ":x", $len, 2);
ora_bind($curs, "input", ":in", 5, 1);
ora_bind($curs, "output", ":out", 5, 2);
$input = 765;
ora_exec($curs);
echo "Result: $result<BR>Out: $output<BR>In: $input";
?>
]]>
      </programlisting>
     </informalexample>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-close">
   <refnamediv>
    <refname>Ora_Close</refname>
    <refpurpose>close an Oracle cursor</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_close</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if the close succeeds, otherwise &false;. Details
     about the error can be retrieved using the
     <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
    <para>
     This function closes a data cursor opened with
     <function>ora_open</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-columnname">
   <refnamediv>
    <refname>Ora_ColumnName</refname>
    <refpurpose>get name of Oracle result column</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>Ora_ColumnName</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
      <methodparam><type>int</type><parameter>column</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the name of the field/column
     <parameter>column</parameter> on the cursor
     <parameter>cursor</parameter>. The returned name is in all
     uppercase letters. Column 0 is the first column.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-columnsize">
   <refnamediv>
    <refname>Ora_ColumnSize</refname>
    <refpurpose>get size of Oracle result column</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>Ora_ColumnSize</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
      <methodparam><type>int</type><parameter>column</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the size of the Oracle column
     <parameter>column</parameter> on the cursor
     <parameter>cursor</parameter>. Column 0 is the first column.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-columntype">
   <refnamediv>
    <refname>Ora_ColumnType</refname>
    <refpurpose>get type of Oracle result column</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>Ora_ColumnType</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
      <methodparam><type>int</type><parameter>column</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the Oracle data type name of the field/column
     <parameter>column</parameter> on the cursor
     <parameter>cursor</parameter>. Column 0 is the first column. The returned
     type will be one of the following:
     <simplelist>
      <member><literal>"VARCHAR2"</literal></member>
      <member><literal>"VARCHAR"</literal></member>
      <member><literal>"CHAR"</literal></member>
      <member><literal>"NUMBER"</literal></member>
      <member><literal>"LONG"</literal></member>
      <member><literal>"LONG RAW"</literal></member>
      <member><literal>"ROWID"</literal></member>
      <member><literal>"DATE"</literal></member>
      <member><literal>"CURSOR"</literal></member>
     </simplelist>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-commit">
   <refnamediv>
    <refname>Ora_Commit</refname>
    <refpurpose>commit an Oracle transaction</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_commit</methodname>
      <methodparam><type>int</type><parameter>conn</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; on success, &false; on error. Details about the
     error can be retrieved using the <function>ora_error</function>
     and <function>ora_errorcode</function> functions.
    </para>
    <para>
     This function commits an Oracle transaction. A transaction is defined as
     all the changes on a given connection since the last commit/rollback,
     autocommit was turned off or when the connection was established.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-commitoff">
   <refnamediv>
    <refname>Ora_CommitOff</refname>
    <refpurpose>disable automatic commit</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_commitoff</methodname>
      <methodparam><type>int</type><parameter>conn</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; on success, &false; on error. Details about the error
     can be retrieved using the <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
    <para>
     This function turns off automatic commit after each
     <function>ora_exec</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-commiton">
   <refnamediv>
    <refname>Ora_CommitOn</refname>
    <refpurpose>enable automatic commit</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_commiton</methodname>
      <methodparam><type>int</type><parameter>conn</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function turns on automatic commit after each
     <function>ora_exec</function> on the given connection.
    </para>
    <para>
     Returns &true; on success, &false; on error. Details about the error
     can be retrieved using the <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-do">
   <refnamediv>
    <refname>Ora_Do</refname>
    <refpurpose>Parse, Exec, Fetch</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_do</methodname>
      <methodparam><type>int</type><parameter>conn</parameter></methodparam>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function is quick combination of <function>ora_parse</function>,
     <function>ora_exec</function> and <function>ora_fetch</function>.
     It will parse and execute a statement, then fetch the first result row.
    </para>
    <para>
     Returns &true; on success, &false; on error. Details about the error
     can be retrieved using the <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
    <para>
     See also <function>ora_parse</function>,<function>ora_exec</function>,
     and <function>ora_fetch</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-error">
   <refnamediv>
    <refname>Ora_Error</refname>
    <refpurpose>get Oracle error message</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>Ora_Error</methodname>
      <methodparam><type>int</type><parameter>cursor_or_connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns an error message of the form
     <replaceable>XXX</replaceable>-<replaceable>NNNNN</replaceable>
     where <replaceable>XXX</replaceable> is where the error comes
     from and <replaceable>NNNNN</replaceable> identifies the error
     message.
    </para>
    <para>
     <note>
      <para>Support for connection ids was added in 3.0.4.</para>
     </note>
    </para>
    <para>
     On UNIX versions of Oracle, you can find details about an error
     message like this:
     <computeroutput>
$ <userinput>oerr ora
<replaceable>00001</replaceable></userinput> 00001, 00000,
"unique constraint (%s.%s) violated" // *Cause: An update or insert
statement attempted to insert a duplicate key //         For Trusted
ORACLE configured in DBMS MAC mode, you may see //         this message
if a duplicate entry exists at a different level.  // *Action: Either
remove the unique restriction or do not insert the key
     </computeroutput>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-errorcode">
   <refnamediv>
    <refname>Ora_ErrorCode</refname>
    <refpurpose>get Oracle error code</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>Ora_ErrorCode</methodname>
      <methodparam><type>int</type><parameter>cursor_or_connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the numeric error code of the last executed statement on
     the specified cursor or connection.
     <!-- FIXME: should possible values be listed? -->
     <note>
      <para>Support for connection ids was added in 3.0.4.</para>
     </note>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-exec">
   <refnamediv>
    <refname>Ora_Exec</refname>
    <refpurpose>execute parsed statement on an Oracle cursor</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_exec</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; on success, &false; on error. Details about the error
     can be retrieved using the <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
    <simpara>
     See also <function>ora_parse</function>,
     <function>ora_fetch</function>, and <function>ora_do</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.ora-fetch">
   <refnamediv>
    <refname>Ora_Fetch</refname>
    <refpurpose>fetch a row of data from a cursor</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_fetch</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; (a row was fetched) or &false; (no more rows, or an
     error occured). If an error occured, details can be retrieved
     using the <function>ora_error</function> and
     <function>ora_errorcode</function> functions. If there was no
     error, <function>ora_errorcode</function> will return 0.
    </para>
    <para>
     Retrieves a row of data from the specified cursor.
    </para>
    <simpara>
     See also <function>ora_parse</function>,<function>ora_exec</function>,
     and <function>ora_do</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.ora-fetch-into">
   <refnamediv>
    <refname>Ora_Fetch_Into</refname>
    <refpurpose>Fetch a row into the specified result array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_fetch_into</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
      <methodparam><type>array</type><parameter>result</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        flags
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     You can fetch a row into an array with this function.
     <example>
      <title>Oracle fetch into array</title>
      <programlisting role="php">
<![CDATA[
<?php
array($results);
ora_fetch_into($cursor, &$results);
echo $results[0];
echo $results[1];
?>
]]>
      </programlisting>
     </example>
     Note that you need to fetch the array by reference.
    </para>
    <simpara>
     See also <function>ora_parse</function>,<function>ora_exec</function>,
     <function>ora_fetch</function>, and <function>ora_do</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.ora-getcolumn">
   <refnamediv>
    <refname>Ora_GetColumn</refname>
    <refpurpose>get data from a fetched column</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>mixed</type><methodname>ora_getcolumn</methodname>
      <methodparam><type>int</type><parameter>cursor</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>column</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the column data. If an error occurs, &false; is returned
     and <function>ora_errorcode</function>
     will return a non-zero value. Note, however, that a test for &false;
     on the results from this function may be &true; in cases where there is
     not error as well (&null; result, empty string, the number 0, the
     string "0").
    </para>
    <para>
     Fetches the data for a column or function result.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-logoff">
   <refnamediv>
    <refname>Ora_Logoff</refname>
    <refpurpose>close an Oracle connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_logoff</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; on success, &false; on error. Details about the error
     can be retrieved using the <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
    <para>
     Logs out the user and disconnects from the server.
    </para>
    <simpara>
     See also <function>ora_logon</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.ora-logon">
   <refnamediv>
    <refname>Ora_Logon</refname>
    <refpurpose>open an Oracle connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_logon</methodname>
      <methodparam><type>string</type><parameter>user</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
     </methodsynopsis>
    <para>
     Establishes a connection between PHP and an Oracle database with the
     given username and password.
    </para>
    <para>
     Connections can be made using <productname>SQL*Net</productname>
     by supplying the <acronym>TNS</acronym> name to
     <parameter>user</parameter> like this:
     <informalexample>
      <programlisting role="php">
<![CDATA[
$conn = Ora_Logon("user<emphasis>@TNSNAME</emphasis>", "pass");
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     If you have character data with non-ASCII characters, you should
     make sure that <envar>NLS_LANG</envar> is set in your
     environment. For server modules, you should set it in the
     server's environment before starting the server.
    </para>
    <para>
     Returns a connection index on success, or &false; on failure.
     Details about the error can be retrieved using the
     <function>ora_error</function> and <function>ora_errorcode</function>
     functions.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-plogon">
   <refnamediv>
    <refname>Ora_pLogon</refname>
    <refpurpose>
     Open a persistent Oracle connection
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_plogon</methodname>
      <methodparam><type>string</type><parameter>user</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
     </methodsynopsis>
    <para>
     Establishes a persistent connection between PHP and an Oracle database with
     the given username and password.
    </para>
    <simpara>
     See also <function>ora_logon</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.ora-numcols">
   <refnamediv>
    <refname>Ora_Numcols</refname>
    <refpurpose>Returns the number of columns</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_numcols</methodname>
      <methodparam><type>int</type><parameter>cursor_ind</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ora_numcols</function> returns the number of columns in a result.
     Only returns meaningful values after an parse/exec/fetch sequence.
    </para>
    <simpara>
     See also <function>ora_parse</function>,<function>ora_exec</function>,
     <function>ora_fetch</function>, and <function>ora_do</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.ora-numrows">
   <refnamediv>
    <refname>Ora_Numrows</refname>
    <refpurpose>Returns the number of rows</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_numrows</methodname>
      <methodparam><type>int</type><parameter>cursor_ind</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>ora_numrows</function> returns the number of rows in a result.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-open">
   <refnamediv>
    <refname>Ora_Open</refname>
    <refpurpose>open an Oracle cursor</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_open</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     Opens an Oracle cursor associated with connection.
    </para>
    <para>
     Returns a cursor index or &false; on failure. Details about the
     error can be retrieved using the <function>ora_error</function>
     and <function>ora_errorcode</function> functions.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ora-parse">
   <refnamediv>
    <refname>Ora_Parse</refname>
    <refpurpose>parse an SQL statement</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_parse</methodname>
      <methodparam><type>int</type><parameter>cursor_ind</parameter></methodparam>
      <methodparam><type>string</type><parameter>sql_statement</parameter></methodparam>
      <methodparam><type>int</type><parameter>defer</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function parses an SQL statement or a PL/SQL block and
     associates it with the given cursor.
    </para>
    <para>
     &return.success;
    </para>
    <simpara>
     See also <function>ora_exec</function>,
     <function>ora_fetch</function>, and <function>ora_do</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.ora-rollback">
   <refnamediv>
    <refname>Ora_Rollback</refname>
    <refpurpose>roll back transaction</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>ora_rollback</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     This function undoes an Oracle transaction. (See
     <function>ora_commit</function> for the definition of a
     transaction.)
    </para>
    <para>
     Returns &true; on success, &false; on error. Details about the error
     can be retrieved using the <function>ora_error</function> and
     <function>ora_errorcode</function> functions.
    </para>
   </refsect1>
  </refentry>
 </reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->