diff --git a/functions/dbx.xml b/functions/dbx.xml index 4f79124820..519c857781 100644 --- a/functions/dbx.xml +++ b/functions/dbx.xml @@ -1,457 +1,514 @@ - - dbx functions - dbx - - - 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 and all options for the databases that will be used, e.g. for - MySQL you must also specify . - 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 :-). - - - Documentation for adding additional database support to dbx can be found at - &url.dbx.docs;. - - + + dbx functions + dbx + + + 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 and all options for + the databases that will be used, e.g. for MySQL you must also + specify . 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 :-). + + + Documentation for adding additional database support to dbx can be + found at &url.dbx.docs;. + + - - - dbx_close - Close an open connection/database - - - Description - - - int dbx_close - dbx_link_object link_identifier - - - - Returns TRUE on success, FALSE on error. - - - <function>dbx_close</function> example - -<?php - $link = dbx_connect("mysql", "localhost", "db", "username", "password") - or die ("Could not connect"); - print("Connected successfully"); - dbx_close($link); -?> - - - + + + dbx_close + Close an open connection/database + + + Description + + + int dbx_close + dbx_link_object + link_identifier + + + - Always refer to the module-specific documentation as well. + Returns TRUE on success, + FALSE on error. - - - See also: dbx_connect. - - - - - - - dbx_connect - Open a connection/database - - - Description - - - dbx_link_object dbx_connect - string module - string host - string database - string username - string password - int persistent - - - - 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. - - - Possible module names are given below, but keep in mind that they only - work if the module is actually loaded. - - - - module 1: "mysql" - - - - - module 2: "odbc" - - - - - module 3: "pgsql" - - - - 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. - - - 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. - - + + <function>dbx_close</function> example + <?php - $link = dbx_connect("mysql", "localhost", "db", "username", "password"); - mysql_close($link->handle); // dbx_close($link) would be better here +$link = dbx_connect ("mysql", "localhost", "db", "username", "password") + or die ("Could not connect"); +print("Connected successfully"); +dbx_close($link); ?> - - Host, database, username and password parameters are expected, but not - always used, depending on the connect-functions for the module that is - abstracted. - - - <function>dbx_connect</function> example - -<?php - $link = dbx_connect("odbc", "", "db", "username", "password", DBX_PERSISTENT) - or die ("Could not connect"); - print("Connected successfully"); - dbx_close($link); -?> - - - + + + + Always refer to the module-specific documentation as well. + + - Always refer to the module-specific documentation as well. + See also: dbx_connect. - - - See also: dbx_close. - - - + + - - - dbx_error - - Report the error message of the latest function call in the module - (not just in the connection) - - - - Description - - - string dbx_error - dbx_link_object link_identifier - - - - - 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. - - - <function>dbx_error</function> example - + + + dbx_connect + Open a connection/database + + + Description + + + dbx_link_object dbx_connect + string module + string host + string database + string username + string password + int + persistent + + + + + 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. + + + Possible module names are given below, but keep in mind that they + only work if the module is actually loaded. + + + + + + module 1: "mysql" + + + + + module 2: "odbc" + + + + + module 3: "pgsql" + + + + + + 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. + + + 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. + + + + <?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); +$link = dbx_connect ("mysql", "localhost", "db", "username", "password"); +mysql_close ($link->handle); // dbx_close($link) would be better here +?> + + + + + Host, database, username and password parameters are expected, + but not always used, depending on the connect-functions for the + module that is abstracted. + + + + <function>dbx_connect</function> example + +<?php +$link = dbx_connect ("odbc", "", "db", "username", "password", DBX_PERSISTENT) + or die ("Could not connect"); +print ("Connected successfully"); +dbx_close ($link); +?> + + + + + Always refer to the module-specific documentation as well. + + + + + See also: dbx_close. + + + + + + + dbx_error + + Report the error message of the latest function call in the + module (not just in the connection) + + + + Description + + + string dbx_error + dbx_link_object link_identifier + + + + + 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. + + + <function>dbx_error</function> example + +<?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); +?> + + + + + Always refer to the module-specific documentation as well. + + + + + + + + dbx_query + Send a query and fetch all results (if any) + + + Description + + + dbx_result_object dbx_query + dbx_link_object + link_identifier + + string sql_statement + long + flags + + + + + 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. + + + 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: + + + + +$result = dbx_query ($link, "SELECT id FROM tbl"); +mysql_field_len ($result->handle, 0); + + + + + The cols and rows members contain the number of columns (or + fields) and rows (or records) respectively, e.g. + + + + +$result = dbx_query ($link, "SELECT id FROM tbl"); +echo "result size: " . $result->rows . " x " . $result->cols . "<br>\n"; + + + + + 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. + + + + +$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"; + + + + + 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"]. + + + <function>dbx_query</function> example + +<?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>"; } - dbx_close($link); + 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); ?> - - - + + + + + Always refer to the module-specific documentation as well. + + - Always refer to the module-specific documentation as well. + See also: dbx_connect. - - - - - - - dbx_query - Send a query and fetch all results (if any) - - - Description - - - dbx_result_object dbx_query - dbx_link_object link_identifier - string sql_statement - long flags - - - - 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. - - - 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 - - - $result = dbx_query($link, "select id from tbl"); - mysql_field_len($result->handle, 0); - - - The cols and rows members contain the number of columns (or fields) and - rows (or records) respectively, e.g. - - - $result = dbx_query($link, "select id from tbl"); - echo "result size: " . $result->rows . " x " . $result->cols . "<br>\n"; - - - 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. - - - $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"; - - - 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"]. - - - <function>dbx_query</function> example - -<?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); -?> - - - + + + + + + dbx_sort + + Sort a result from a dbx_query by a custom sort function + + + Description + + + int dbx_sort + dbx_result_object result + string + user_compare_function + + + - Always refer to the module-specific documentation as well. + Returns: TRUE on success, + FALSE on error. - - - See also: dbx_connect. - - - - - - - dbx_sort - Sort a result from a dbx_query by a custom sort function - - - Description - - - int dbx_sort - dbx_result_object result - string user_compare_function - - - - Returns: TRUE on success, FALSE on error. - - - <function>dbx_sort</function> example - + + <function>dbx_sort</function> example + <?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; - } +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<br>"; - dbx_query($result, "user_re_order"); - echo "resulting data is now ordered by parentid, then by id<br>"; - dbx_close($link); +$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_query ($result, "user_re_order"); +echo "resulting data is now ordered by parentid, then by id<br>"; +dbx_close ($link); ?> - - - - See also dbx_cmp_asc and dbx_cmp_desc. - - - + + + + See also dbx_cmp_asc and + dbx_cmp_desc. + + + - - - dbx_cmp_asc - Compare two rows for sorting in ascending order - - - Description - - - int dbx_cmp_asc - array row_a - array row_b - string columnname_or_index - - - - 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. - - - <function>dbx_cmp_asc</function> example - + + + dbx_cmp_asc + Compare two rows for sorting in ascending order + + + Description + + + int dbx_cmp_asc + array row_a + array row_b + string columnname_or_index + + + + 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. + + + <function>dbx_cmp_asc</function> example + <?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; - } +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<br>"; - dbx_query($result, "user_re_order"); - echo "resulting data is now ordered by parentid, then by id<br>"; - dbx_close($link); +$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_query ($result, "user_re_order"); +echo "resulting data is now ordered by parentid, then by id<br>"; +dbx_close ($link); ?> - - - - See also dbx_sort and dbx_cmp_desc. - - - + + + + See also dbx_sort and + dbx_cmp_desc. + + + - - - dbx_cmp_desc - Compare two rows for sorting in descending order - - - Description - - - int dbx_cmp_desc - array row_a - array row_b - string columnname_or_index - - - - 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. - - - <function>dbx_cmp_desc</function> example - + + + dbx_cmp_desc + Compare two rows for sorting in descending order + + + Description + + + int dbx_cmp_desc + array row_a + array row_b + string + columnname_or_index + + + + + 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. + + + <function>dbx_cmp_desc</function> example + <?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; - } +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<br>"; - dbx_query($result, "user_re_order"); - echo "resulting data is now ordered by parentid, then by id<br>"; - dbx_close($link); +$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_query ($result, "user_re_order"); +echo "resulting data is now ordered by parentid, then by id<br>"; +dbx_close ($link); ?> - - - - See also dbx_sort and dbx_cmp_asc. - - - + + + + See also dbx_sort and + dbx_cmp_asc. + + + - +