From 3d0cae6885018d1965844da25b7e9683e582ee57 Mon Sep 17 00:00:00 2001 From: Gyozo Papp Date: Sat, 16 Feb 2002 00:17:18 +0000 Subject: [PATCH] introduce brand new tagging in dbx.xml according to my discussion with Marc Boeren. Anyone who finds difficult to figure out the changes, feel free to contact me! git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@70323 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/dbx.xml | 564 ++++++++++++++++++++++++++++++---------------- 1 file changed, 366 insertions(+), 198 deletions(-) diff --git a/functions/dbx.xml b/functions/dbx.xml index bb9e34f7ce..5724793f4b 100644 --- a/functions/dbx.xml +++ b/functions/dbx.xml @@ -1,5 +1,5 @@ - + dbx functions dbx @@ -38,7 +38,7 @@ Description booldbx_close - dbx_link_objectlink_identifier + objectlink_identifier Returns &true; on success, @@ -49,8 +49,9 @@ @@ -76,80 +77,107 @@ dbx_close($link); Description - dbx_link_objectdbx_connect - stringmodule + objectdbx_connect + mixedmodule stringhost stringdatabase stringusername stringpassword intpersistent - - 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. - - - The module 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. - + + dbx_connect returns an 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, if so, a persistent connection will be + created. + + + The module parameter can be either a string or a + constant, though the latter form is preferred. The possible values are + given below, but keep in mind that they only work if the module is + actually loaded. + - module DBX_MYSQL : "mysql" + DBX_MYSQL or "mysql" - module DBX_ODBC : "odbc" + DBX_ODBC or "odbc" - module DBX_PGSQL : "pgsql" + DBX_PGSQL or "pgsql" - module DBX_MSSQL : "mssql" + DBX_MSSQL or "mssql" - module DBX_FBSQL : "fbsql" (CVS only) + DBX_FBSQL or "fbsql" (available from PHP 4.1.0) - 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. + The host, database, + username and password + parameters are expected, but not always used depending on the connect + functions for the abstracted module. - - + The returned object has three properties: + + + + database + + + + It is the name of the currently selected database. + + + + + + handle + + + + It is a valid handle for the connected database, and as such it can be + used in module-specific functions (if required). + + 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 - abstracted module. + + + + + + + + module + + + + It is used internally by dbx only, and is actually the module number + mentioned above. + + + + @@ -157,8 +185,9 @@ mysql_close ($link->handle); // dbx_close($link) would be better here @@ -189,26 +218,26 @@ dbx_close ($link); Description stringdbx_error - dbx_link_objectlink_identifier + objectlink_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. - + + dbx_error returns a string containing the error + message from the last function call of the abstracted module (e.g. + mysql module). If there are multiple connections in the same module, + just the last error is given. If there are connections on different + modules, the latest error is returned for the module specified by the + link_identifier parameter. + <function>dbx_error</function> example - The error-message for Microsoft SQL Server is actually the result + The error message for Microsoft SQL Server is actually the result of the mssql_get_last_message function. @@ -236,135 +265,227 @@ dbx_close ($link); Description - dbx_result_objectdbx_query - dbx_link_objectlink_identifier + objectdbx_query + objectlink_identifier stringsql_statement longflags - - 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 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 - 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 isn't specified. Associated results are actual - references to the indexed data, so if you modify - data[0][0], then - data[0]['fieldnameforfirstcolumn'] is - modified as well. - - - A dbx_result_object has five members (possibly four depending on - 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: - - - - -handle, 0); -]]> - - - - - The cols and rows members contain the number of columns (or - fields) and rows (or records) respectively, e.g. - - - - -rows . " x " . $result->cols . "
\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. - - - - -info["name"][0] . "
\n"; -echo "column type: " . $result->info["type"][0] . "
\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"]. - + + dbx_query returns an object or 1 + on success, and 0 on failure. The result object is + returned only if the query given in sql_statement + produces a result set. + - <function>dbx_query</function> example + How to handle the returned value "; -elseif ($result==1) { - echo "Query executed successfully\n
"; -} else { - $rows=$result->rows; - $cols=$result->cols; - echo "

table dimension: {$result->rows} x {$result->cols}
\n"; - echo ""; - for ($col=0; $col<$cols; ++$col) { - echo ""; - } - echo "\n"; - for ($row=0; $row<$rows; ++$row){ - echo ""; - for ($col=0; $col<$cols; ++$col) { - echo ""; - } - echo "\n"; - } - echo "
-{$result->info["name"][$col]}-
-{$result->info["type"][$col]}-
-{$result->data[$row][$col]}-

\n"; - echo "table dimension: {$result->rows} x id, parentid, description
\n"; - for ($row=0; $row<$rows; ++$row) { - echo ""; - echo ""; - echo ""; - echo ""; - echo "\n"; - } - echo "
-{$result->data[$row]["id"]}--{$result->data[$row]["parentid"]}--{$result->data[$row]["description"]}-

\n"; +$link = dbx_connect(DBX_ODBC, "", "db", "username", "password") + or die("Could not connect"); + +$result = dbx_query($link, 'SELECT id, parentid, description FROM table'); + +if ( is_object($result) ) { + // ... do some stuff here, see detailed examples below ... + // first, print out field names and types + // then, draw a table filled with the returned field values } +else if ( $result == 1 ) { + echo("Query executed successfully, but no result set returned"); +} +else { + exit("Query failed"); +} + dbx_close($link); ?> ]]> + + + The flags parameter is used to control the amount of + information that is returned. It may be any combination of the following + constants with the bitwise OR operator (|): + + + + DBX_RESULT_INDEX + + + + It is always set, that is, the returned object + has a data property which is a 2 dimensional + array indexed numerically. For example, in the expression + data[2][3] 2 stands for the row + (or record) number and 3 stands for the column + (or field) number. The first row and column are indexed at 0. + + + If DBX_RESULT_ASSOC is also specified, the + returning object contains the information related to + DBX_RESULT_INFO too, even if it was not specified. + + + + + + DBX_RESULT_INFO + + + + It provides info about columns, such as field names and field types. + + + + + + DBX_RESULT_ASSOC + + + + It effects that the field values can be accessed with the respective + column names used as keys to the returned object's + data property. + + + Associated results are actually references to the numerically indexed + data, so modifying data[0][0] causes that + data[0]['field_name_for_first_column'] is modified + as well. + + + + + Note that DBX_RESULT_INDEX is always used, regardless + of the actual value of flags parameter. This means + that the following combinations is effective only: + + + + DBX_RESULT_INDEX + + + + + DBX_RESULT_INDEX | + DBX_RESULT_INFO + + + + + DBX_RESULT_INDEX | + DBX_RESULT_INFO | + DBX_RESULT_ASSOC - this is the default, if + flags is not specified. + + + + + + The returing object has four or five + properties depending on flags: + + + + handle + + + + It is a valid handle for the connected database, and as such it can be + used in module specific functions (if required). + + +handle, 0); +]]> + + + + + + + + cols and rows + + + + These contain the number of columns (or fields) and rows (or records) + respectively. + + +rows; // number of records +echo $result->cols; // number of fields +]]> + + + + + + + + info (optional) + + + + It is returned only if either DBX_RESULT_INFO or + DBX_RESULT_ASSOC is specified in the + flags parameter. It is a 2 dimensional array, + that has two named rows (name and + type) to retrieve column information. + + + lists each field's name and type + +cols; $i++ ) { + echo $result->info['name'][$i] . "\n"; + echo $result->info['type'][$i] . "\n"; +} +]]> + + + + + + + data + + + + This property contains the actual resulting data, possibly associated + with column names as well depending on flags. + If DBX_RESULT_ASSOC is set, it is possible to use + $result->data[2]["field_name"]. + + + outputs the content of data property into HTML table + +\n"; +foreach ( $result->data as $row ) { + echo "\n"; + foreach ( $row as $field ) { + echo "$field"; + } + echo "\n"; +} +echo "\n"; +]]> + + + + + + Always refer to the module-specific documentation as well. @@ -387,13 +508,20 @@ dbx_close($link); Description booldbx_sort - dbx_result_objectresult + objectresult stringuser_compare_function Returns &true; on success, &false; on error. + + + It is always better to use ORDER BY + SQL clause instead of dbx_sort, + if possible. + + <function>dbx_sort</function> example @@ -401,16 +529,21 @@ dbx_close($link); "; + // data in $result is now ordered by id + dbx_sort ($result, "user_re_order"); -echo "resulting data is now ordered by parentid (descending), then by id
"; + // data in $result is now ordered by parentid (descending), then by id + dbx_close ($link); ?> ]]> @@ -433,24 +566,57 @@ dbx_close ($link); intdbx_compare arrayrow_a arrayrow_b - stringcolumnname_or_index + stringcolumn_key intflags - 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). + dbx_compare returns 0 if the + row_a[$column_key] is equal to + row_b[$column_key], and 1 or + -1 if the former is greater or is smaller than + the latter one, respectively, or vice versa if the + flag is set to DBX_CMP_DESC. + dbx_compare is a helper function for + dbx_sort to ease the make and use of the custom + sorting function. The flags 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 - flags parameter is DBX_CMP_ASC | - DBX_CMP_NATIVE. + direction: + + + + DBX_CMP_ASC - ascending order + + + + + DBX_CMP_DESC - descending order + + + + and the preferred comparison type: + + + + DBX_CMP_NATIVE - no type conversion + + + + + DBX_CMP_TEXT - compare items as strings + + + + + DBX_CMP_NUMBER - compare items numerically + + + + One of the direction and one of the type constant can be combined with + bitwise OR operator (|). The default value for the + flags parameter is DBX_CMP_ASC + | DBX_CMP_NATIVE. <function>dbx_compare</function> example @@ -459,18 +625,21 @@ dbx_close ($link); "; + +$result = dbx_query ($link, "SELECT id, parentid, description FROM table ORDER BY id"); + // data in $result is now ordered by id + dbx_sort ($result, "user_re_order"); -echo "resulting data is now ordered by parentid (descending), then by id
"; + // date in $result is now ordered by parentid (descending), then by id + dbx_close ($link); ?> ]]> @@ -503,5 +672,4 @@ End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> - +--> \ No newline at end of file