sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 17:08:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added documentation for the new dbx (database abstraction) module. (Mc)

Browse source 
@ Added documentation for the new dbx (database abstraction) module.
# manual.xml.in should be modified to actually include it!


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@45140 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Marc Boeren 2001-04-11 13:49:56 +00:00
parent 9212fb317a
commit 97760a9554
1 changed files with 412 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

412
functions/dbx.xml Normal file
View file

@ -0,0 +1,412 @@
<reference id="ref.dbx">
<title>dbx functions</title>
<titleabbrev>dbx</titleabbrev>
<partintro>
<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 <option role="configure">--enable-dbx</option> option and all options for the databases that will be used, e.g. for MySQL you must also specify <option role="configure">--with-mysql</option>. 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 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>int <function>dbx_close</function></funcdef>
<paramdef>dbx_link_object <parameter>link_identifier</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns: true on success, false on error.
</para>
<example>
<title>dbx_close example</title>
<programlisting role="php">
&lt;?php
$link = dbx_connect("mysql", "localhost", "db", "username", "password")
or die ("Could not connect");
print("Connected successfully");
dbx_close($link);
?>
</programlisting>
</example>
<para>
See also: <function>dbx_connect</function>.
</para>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.dbx-connect">
<refnamediv>
<refname>dbx_connect</refname>
<refpurpose>Opens 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>
<para>
Returns: a dbx_link_object on success, false on error. If a connection can be made but the database could not be selected, the function still returns a dbx_link_object. The 'persistent' parameter can be set to DBX_PERSISTENT so a persistent connection will be created.
</para>
<para>
Possible module names are given below, but keep in mind that they only work if the module is actually loaded.
<itemizedlist>
<listitem>
<simpara>
module 1: "mysql"
</simpara>
</listitem>
<listitem>
<simpara>
module 2: "odbc"
</simpara>
</listitem>
<listitem>
<simpara>
module 3: "pgsql"
</simpara>
</listitem>
</itemizedlist>
The pgsql support is still experimental, and you should compile the actual pgsql module yourself after you modify one of the source files, otherwise you will get PostgreSQL warnings for every query
</para>
<para>
The dbx_link_object has three members, a 'handle', a 'module' and a 'database'. The 'database' member is the name of the database that is selected. 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.
<informalexample>
<programlisting>
&lt;?php
$link = dbx_connect("mysql", "localhost", "db", "username", "password");
mysql_close($link->handle); // dbx_close($link) would be better here
?>
</programlisting>
</informalexample>
Host, database, username and password parameters are expected, but not always used, depending on the connect-functions for the module that is abstracted.
</para>
<example>
<title>dbx_connect example</title>
<programlisting role="php">
&lt;?php
$link = dbx_connect("odbc", "", "db", "username", "password", DBX_PERSISTENT)
or die ("Could not connect");
print("Connected successfully");
dbx_close($link);
?>
</programlisting>
</example>
<para>
See also: <function>dbx_close</function>.
</para>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.dbx-error">
<refnamediv>
<refname>dbx_error</refname>
<refpurpose>Reports 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>
<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>dbx_error example</title>
<programlisting role="php">
&lt;?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>
</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>
<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 flags parameter is used to control the amount of information that is returned. It can 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 flags 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 flags parameter is not specified. Associated results are actual references to the indexed data, so if you modify data[0][0], data[0]['fieldnameforfirstcolumn'] is modified as well.
</para>
<para>
A dbx_result_object has five members (possibly four depending on the flags), '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
<informalexample>
<programlisting>
$result = dbx_query($link, "select id from tbl");
mysql_field_len($result->handle, 0);
</programlisting>
</informalexample>
The cols and rows members contain the number of columns (or fields) and rows (or records) respectively, e.g.
<informalexample>
<programlisting>
$result = dbx_query($link, "select id from tbl");
echo "result size: " . $result->rows . " x " . $result->cols . "&lt;br>\n";
</programlisting>
</informalexample>
The info member is only returned if DBX_RESULT_INFO and/or DBX_RESULT_ASSOC are specified in the flags parameter. It is a 2d array, that has two named rows ("name" and "type") to retrieve column information, e.g.
<informalexample>
<programlisting>
$result = dbx_query($link, "select id from tbl");
echo "column name: " . $result->info["name"][0] . "&lt;br>\n";
echo "column type: " . $result->info["type"][0] . "&lt;br>\n";
</programlisting>
</informalexample>
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 $result->data[2]["fieldname"].
</para>
<example>
<title>dbx_query example</title>
<programlisting role="php">
&lt;?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&lt;br>";
elseif ($result==1) echo "Query executed successfully\n&lt;br>";
else {
$rows=$result->rows;
$cols=$result->cols;
echo "&lt;p>table dimension: {$result->rows} x {$result->cols}&lt;br>&lt;table border=1>\n";
echo "&lt;tr>";
for($col=0; $col&lt;$cols; ++$col) {
echo "&lt;td>-{$result->info["name"][$col]}-&lt;br>-{$result->info["type"][$col]}-&lt;/td>";
}
echo "&lt;/tr>\n";
for($row=0; $row&lt;$rows; ++$row){
echo "&lt;tr>";
for($col=0; $col&lt;$cols; ++$col) {
echo "&lt;td>-{$result->data[$row][$col]}-&lt;/td>";
}
echo "&lt;/tr>\n";
}
echo "&lt;/table>&lt;p>\n";
echo "table dimension: {$result->rows} x id, parentid, description&lt;br>&lt;table border=1>\n";
for($row=0; $row&lt;$rows; ++$row) {
echo "&lt;tr>";
echo "&lt;td>-{$result->data[$row]["id"]}-&lt;/td>";
echo "&lt;td>-{$result->data[$row]["parentid"]}-&lt;/td>";
echo "&lt;td>-{$result->data[$row]["description"]}-&lt;/td>";
echo "&lt;/tr>\n";
}
echo "&lt;/table>&lt;p>\n";
}
dbx_close($link);
?>
</programlisting>
</example>
<para>
See also: <function>dbx_connect</function>.
</para>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.dbx-sort">
<refnamediv>
<refname>dbx_sort</refname>
<refpurpose>Sorts a result from a dbx_query by a custom sort function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>dbx_sort</function></funcdef>
<paramdef>dbx_result_object <parameter>result</parameter></paramdef>
<paramdef>string <parameter>user_compare_function</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns: true on success, false on error.
</para>
<example>
<title>dbx_sort example</title>
<programlisting role="php">
&lt;?php
function user_re_order($a, $b) {
$rv = dbx_cmp_asc($a, $b, "parentid");
if (!$rv) $rv = dbx_cmp_asc($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&lt;br>";
dbx_query($result, "user_re_order");
echo "resulting data is now ordered by parentid, then by id&lt;br>";
dbx_close($link);
?>
</programlisting>
</example>
<para>
See also: <function>dbx_cmp_asc</function> and <function>dbx_cmp_desc</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.dbx-cmp-asc">
<refnamediv>
<refname>dbx_cmp_asc</refname>
<refpurpose>Compares two rows for sorting in ascending order</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>dbx_cmp_asc</function></funcdef>
<paramdef>array <parameter>row_a</parameter></paramdef>
<paramdef>array <parameter>row_b</parameter></paramdef>
<paramdef>string <parameter>columnname_or_index</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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.
</para>
<example>
<title>dbx_cmp_asc example</title>
<programlisting role="php">
&lt;?php
function user_re_order($a, $b) {
$rv = dbx_cmp_asc($a, $b, "parentid");
if (!$rv) $rv = dbx_cmp_asc($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&lt;br>";
dbx_query($result, "user_re_order");
echo "resulting data is now ordered by parentid, then by id&lt;br>";
dbx_close($link);
?>
</programlisting>
</example>
<para>
See also: <function>dbx_sort</function> and <function>dbx_cmp_desc</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.dbx-cmp-desc">
<refnamediv>
<refname>dbx_cmp_desc</refname>
<refpurpose>Compares two rows for sorting in descending order</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>dbx_cmp_desc</function></funcdef>
<paramdef>array <parameter>row_a</parameter></paramdef>
<paramdef>array <parameter>row_b</parameter></paramdef>
<paramdef>string <parameter>columnname_or_index</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<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.
</para>
<example>
<title>dbx_cmp_desc example</title>
<programlisting role="php">
&lt;?php
function user_re_order($a, $b) {
$rv = dbx_cmp_asc($a, $b, "parentid");
if (!$rv) $rv = dbx_cmp_asc($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&lt;br>";
dbx_query($result, "user_re_order");
echo "resulting data is now ordered by parentid, then by id&lt;br>";
dbx_close($link);
?>
</programlisting>
</example>
<para>
See also: <function>dbx_sort</function> and <function>dbx_cmp_asc</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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->