mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 17:08:54 +00:00
3747b34a1b
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@64852 c90b9560-bf6c-de11-be94-00142212c4b1
538 lines
17 KiB
XML
538 lines
17 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!-- $Revision: 1.22 $ -->
|
|
<reference id="ref.dbx">
|
|
<title>dbx functions</title>
|
|
<titleabbrev>dbx</titleabbrev>
|
|
<partintro>
|
|
&warn.experimental;
|
|
<simpara>
|
|
The dbx module is a database abstraction layer (db 'X', where 'X'
|
|
is a supported database). The dbx functions allow you to access
|
|
all supported databases using a single calling convention. In
|
|
order to have these functions available, you must compile PHP with
|
|
dbx support by using the <link linkend="install.configure.enable-dbx">
|
|
<option role="configure">--enable-dbx</option></link> option and all options for
|
|
the databases that will be used, e.g. for MySQL you must also
|
|
specify <link linkend="install.configure.with-mysql">
|
|
<option role="install.configure.with-mysql">--with-mysql</option></link>.
|
|
The dbx-functions themselves do not interface directly to the
|
|
databases, but interface to the modules that are used to support
|
|
these databases. To be able to use a database with the
|
|
dbx-module, the module must be either linked or loaded into PHP,
|
|
and the database module must be supported by the
|
|
dbx-module. Currently, MySQL, PostgreSQL, Microsoft SQL Server,
|
|
FrontBase and ODBC are supported, but others will follow
|
|
(soon, I hope :-).
|
|
</simpara>
|
|
<simpara>
|
|
Documentation for adding additional database support to dbx can be
|
|
found at <ulink url="&url.dbx.docs;">&url.dbx.docs;</ulink>.
|
|
</simpara>
|
|
</partintro>
|
|
|
|
<refentry id="function.dbx-close">
|
|
<refnamediv>
|
|
<refname>dbx_close</refname>
|
|
<refpurpose>Close an open connection/database</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>dbx_close</function></funcdef>
|
|
<paramdef>dbx_link_object
|
|
<parameter>link_identifier</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
&warn.experimental.func;
|
|
<para>
|
|
Returns &true; on success,
|
|
&false; on error.
|
|
</para>
|
|
<example>
|
|
<title><function>dbx_close</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$link = dbx_connect ("mysql", "localhost", "db", "username", "password")
|
|
or die ("Could not connect");
|
|
print("Connected successfully");
|
|
dbx_close($link);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
Always refer to the module-specific documentation as well.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also: <function>dbx_connect</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.dbx-connect">
|
|
<refnamediv>
|
|
<refname>dbx_connect</refname>
|
|
<refpurpose>Open a connection/database</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>dbx_link_object <function>dbx_connect</function></funcdef>
|
|
<paramdef>string <parameter>module</parameter></paramdef>
|
|
<paramdef>string <parameter>host</parameter></paramdef>
|
|
<paramdef>string <parameter>database</parameter></paramdef>
|
|
<paramdef>string <parameter>username</parameter></paramdef>
|
|
<paramdef>string <parameter>password</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>persistent</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
&warn.experimental.func;
|
|
<para>
|
|
Returns: a dbx_link_object on success, &false;
|
|
on error. If a connection has been made but the database could not
|
|
be selected, the connection is closed and &false;
|
|
is returned. The 'persistent' parameter can be set to
|
|
DBX_PERSISTENT so a persistent connection will be created.
|
|
</para>
|
|
<para>
|
|
The <parameter>module</parameter> parameter can be either a string
|
|
or a constant. The possible values are given below, but keep in
|
|
mind that they only work if the module is actually loaded.
|
|
</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
module DBX_MYSQL : "mysql"
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
module DBX_ODBC : "odbc"
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
module DBX_PGSQL : "pgsql"
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
module DBX_MSSQL : "mssql"
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
module DBX_FBSQL : "fbsql" (CVS only)
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The dbx_link_object has three members, a 'handle', a 'module' and
|
|
a 'database'. The 'database' member is the name of the currently
|
|
selected database. The 'module' member is for internal use by dbx
|
|
only, and is actually the module number mentioned above. The
|
|
'handle' member is a valid handle for the connected database, and
|
|
as such can be used in module-specific functions (if required),
|
|
e.g.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$link = dbx_connect ("mysql", "localhost", "db", "username", "password");
|
|
mysql_close ($link->handle); // dbx_close($link) would be better here
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Host, database, username and password parameters are expected,
|
|
but not always used, depending on the connect-functions for the
|
|
abstracted module.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>dbx_connect</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$link = dbx_connect ("odbc", "", "db", "username", "password", DBX_PERSISTENT)
|
|
or die ("Could not connect");
|
|
print ("Connected successfully");
|
|
dbx_close ($link);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
Always refer to the module-specific documentation as well.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
See also: <function>dbx_close</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.dbx-error">
|
|
<refnamediv>
|
|
<refname>dbx_error</refname>
|
|
<refpurpose>
|
|
Report the error message of the latest function call in the
|
|
module (not just in the connection)
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>dbx_error</function></funcdef>
|
|
<paramdef>dbx_link_object <parameter>link_identifier</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
&warn.experimental.func;
|
|
<para>
|
|
Returns a string containing the error-message from the last
|
|
function call of the module (e.g. mysql-module). If there are
|
|
multiple connections on the same module, just the last error is
|
|
given. If there are connections on different modules, the latest
|
|
error is returned for the specified module (specified by the link
|
|
parameter, that is). Note that the ODBC-module doesn't support an
|
|
error_reporting function at the moment.
|
|
</para>
|
|
<example>
|
|
<title><function>dbx_error</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$link = dbx_connect ("mysql", "localhost", "db", "username", "password")
|
|
or die ("Could not connect");
|
|
$result = dbx_query ($link, "select id from nonexistingtbl");
|
|
if ($result==0) {
|
|
echo dbx_error ($link);
|
|
}
|
|
dbx_close ($link);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
Always refer to the module-specific documentation as well.
|
|
</para>
|
|
<para>
|
|
The error-message for Microsoft SQL Server is actually the result
|
|
of the <function>mssql_get_last_message</function> function.
|
|
</para>
|
|
</note>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.dbx-query">
|
|
<refnamediv>
|
|
<refname>dbx_query</refname>
|
|
<refpurpose>Send a query and fetch all results (if any)</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>dbx_result_object <function>dbx_query</function></funcdef>
|
|
<paramdef>dbx_link_object
|
|
<parameter>link_identifier</parameter>
|
|
</paramdef>
|
|
<paramdef>string <parameter>sql_statement</parameter></paramdef>
|
|
<paramdef>long
|
|
<parameter><optional>flags</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
&warn.experimental.func;
|
|
<para>
|
|
Returns a dbx_result_object or 1 on success (a result object is
|
|
only returned for sql-statements that return results) or 0 on
|
|
failure. The <parameter>flags</parameter> parameter is used to
|
|
control the amount of
|
|
information that is returned. It may be any combination of the
|
|
constants DBX_RESULT_INFO, DBX_RESULT_INDEX, DBX_RESULT_ASSOC,
|
|
OR-ed together. DBX_RESULT_INFO provides info about columns, such
|
|
as field names and field types. DBX_RESULT_INDEX returns the
|
|
results in a 2d indexed array (e.g. data[2][3], where 2 is the
|
|
row (or record) number and 3 is the column (or field) number),
|
|
where the first row and column are indexed at 0. DBX_RESULT_ASSOC
|
|
associates the column indices with field names. Note that
|
|
DBX_RESULT_INDEX is always returned, regardless of the
|
|
<parameter>flags</parameter>
|
|
parameter. If DBX_RESULT_ASSOC is specified, DBX_RESULT_INFO is
|
|
also returned even if it wasn't specified. This means that
|
|
effectively only the combinations DBX_RESULT_INDEX,
|
|
DBX_RESULT_INDEX | DBX_RESULT_INFO and DBX_RESULT_INDEX |
|
|
DBX_RESULT_INFO | DBX_RESULT_ASSOC are possible. This last
|
|
combination is the default if the <parameter>flags</parameter>
|
|
parameter isn't specified. Associated results are actual
|
|
references to the indexed data, so if you modify
|
|
<literal>data[0][0]</literal>, then
|
|
<literal>data[0]['fieldnameforfirstcolumn']</literal> is
|
|
modified as well.
|
|
</para>
|
|
<para>
|
|
A dbx_result_object has five members (possibly four depending on
|
|
<parameter>flags</parameter>), 'handle', 'cols', 'rows', 'info'
|
|
(optional) and 'data'. Handle is a valid result identifier for
|
|
the specified module, and as such can be used in module-specific
|
|
functions, as seen in the example:
|
|
</para>
|
|
<para>
|
|
<informalexample role="php">
|
|
<programlisting>
|
|
<![CDATA[
|
|
$result = dbx_query ($link, "SELECT id FROM tbl");
|
|
mysql_field_len ($result->handle, 0);
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
The cols and rows members contain the number of columns (or
|
|
fields) and rows (or records) respectively, e.g.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$result = dbx_query ($link, "SELECT id FROM tbl");
|
|
echo "result size: " . $result->rows . " x " . $result->cols . "<br>\n";
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
The info member is only returned if DBX_RESULT_INFO and/or
|
|
DBX_RESULT_ASSOC are specified in the <parameter>flags</parameter> parameter.
|
|
It is a 2d array, that has two named rows ("name" and "type") to retrieve
|
|
column information, e.g.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
$result = dbx_query ($link, "SELECT id FROM tbl");
|
|
echo "column name: " . $result->info["name"][0] . "<br>\n";
|
|
echo "column type: " . $result->info["type"][0] . "<br>\n";
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
The data member contains the actual resulting data, possibly
|
|
associated with column names as well. If DBX_RESULT_ASSOC is set,
|
|
it is possible to use
|
|
<literal>$result->data[2]["fieldname"]</literal>.
|
|
</para>
|
|
<example>
|
|
<title><function>dbx_query</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$link = dbx_connect ("odbc", "", "db", "username", "password")
|
|
or die ("Could not connect");
|
|
$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl");
|
|
if ($result==0) echo "Query failed\n<br>";
|
|
elseif ($result==1) {
|
|
echo "Query executed successfully\n<br>";
|
|
} else {
|
|
$rows=$result->rows;
|
|
$cols=$result->cols;
|
|
echo "<p>table dimension: {$result->rows} x {$result->cols}<br><table border=1>\n";
|
|
echo "<tr>";
|
|
for ($col=0; $col<$cols; ++$col) {
|
|
echo "<td>-{$result->info["name"][$col]}-<br>-{$result->info["type"][$col]}-</td>";
|
|
}
|
|
echo "</tr>\n";
|
|
for ($row=0; $row<$rows; ++$row){
|
|
echo "<tr>";
|
|
for ($col=0; $col<$cols; ++$col) {
|
|
echo "<td>-{$result->data[$row][$col]}-</td>";
|
|
}
|
|
echo "</tr>\n";
|
|
}
|
|
echo "</table><p>\n";
|
|
echo "table dimension: {$result->rows} x id, parentid, description<br><table border=1>\n";
|
|
for ($row=0; $row<$rows; ++$row) {
|
|
echo "<tr>";
|
|
echo "<td>-{$result->data[$row]["id"]}-</td>";
|
|
echo "<td>-{$result->data[$row]["parentid"]}-</td>";
|
|
echo "<td>-{$result->data[$row]["description"]}-</td>";
|
|
echo "</tr>\n";
|
|
}
|
|
echo "</table><p>\n";
|
|
}
|
|
dbx_close($link);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<note>
|
|
<para>
|
|
Always refer to the module-specific documentation as well.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
See also: <function>dbx_connect</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.dbx-sort">
|
|
<refnamediv>
|
|
<refname>dbx_sort</refname>
|
|
<refpurpose>
|
|
Sort a result from a dbx_query by a custom sort function
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>dbx_sort</function></funcdef>
|
|
<paramdef>dbx_result_object <parameter>result</parameter></paramdef>
|
|
<paramdef>string
|
|
<parameter>user_compare_function</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
&warn.experimental.func;
|
|
<para>
|
|
Returns &true; on success,
|
|
&false; on error.
|
|
</para>
|
|
<example>
|
|
<title><function>dbx_sort</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function user_re_order ($a, $b) {
|
|
$rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC);
|
|
if (!$rv) $rv = dbx_compare ($a, $b, "id");
|
|
return $rv;
|
|
}
|
|
|
|
$link = dbx_connect ("odbc", "", "db", "username", "password")
|
|
or die ("Could not connect");
|
|
$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
|
|
echo "resulting data is now ordered by id<br>";
|
|
dbx_sort ($result, "user_re_order");
|
|
echo "resulting data is now ordered by parentid (descending), then by id<br>";
|
|
dbx_close ($link);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See also <function>dbx_compare</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.dbx-compare">
|
|
<refnamediv>
|
|
<refname>dbx_compare</refname>
|
|
<refpurpose>Compare two rows for sorting purposes</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>dbx_compare</function></funcdef>
|
|
<paramdef>array <parameter>row_a</parameter></paramdef>
|
|
<paramdef>array <parameter>row_b</parameter></paramdef>
|
|
<paramdef>string <parameter>columnname_or_index</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>flags</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
&warn.experimental.func;
|
|
<para>
|
|
Returns 0 if row_a[$columnname_or_index] is equal to
|
|
row_b[$columnname_or_index], 1 if it is greater and -1 if it is
|
|
smaller (or vice versa if the DBX_CMP_DESC flag is set).
|
|
</para>
|
|
<para>
|
|
The <parameter>flags</parameter> can be set to specify comparison
|
|
direction (whether sorting is ascending or descending) and
|
|
comparison type (force string or numeric compare by converting the
|
|
data). The constants for direction are DBX_CMP_ASC and DBX_CMP_DESC.
|
|
The constants for comparison type are DBX_CMP_NATIVE (no
|
|
conversion), DBX_CMP_TEXT and DBX_CMP_NUMBER. These constants can
|
|
be OR-ed together. The default value for the
|
|
<parameter>flags</parameter> parameter is DBX_CMP_ASC |
|
|
DBX_CMP_NATIVE.
|
|
</para>
|
|
<example>
|
|
<title><function>dbx_compare</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
function user_re_order ($a, $b) {
|
|
$rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC);
|
|
if (!$rv) {
|
|
$rv = dbx_compare ($a, $b, "id");
|
|
return $rv;
|
|
}
|
|
}
|
|
|
|
$link = dbx_connect ("odbc", "", "db", "username", "password")
|
|
or die ("Could not connect");
|
|
$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
|
|
echo "resulting data is now ordered by id<br>";
|
|
dbx_sort ($result, "user_re_order");
|
|
echo "resulting data is now ordered by parentid (descending), then by id<br>";
|
|
dbx_close ($link);
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
See also <function>dbx_sort</function>.
|
|
</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
|
|
-->
|