php-doc-en/functions/oracle.xml
Hartmut Holzgraefe 7839d91186 added DO NOT EDIT noctice to old english functions files,
removing the others


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
2002-04-17 19:58:46 +00:00

668 lines
22 KiB
XML

<!-- D O N O T E D I T T H I S F I L E ! ! !
it is still here for historical reasons only
(as translators may need to check old revision diffs)
if you want to change things documented in this file
you should now edit the files found under en/reference
instead -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.31 $ -->
<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
-->