gerzson Fri Feb 15 19:17:18 2002 EDT Modified files: /phpdoc/en/functions dbx.xml Log: 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!
Index: phpdoc/en/functions/dbx.xml diff -u phpdoc/en/functions/dbx.xml:1.24 phpdoc/en/functions/dbx.xml:1.25 --- phpdoc/en/functions/dbx.xml:1.24 Wed Feb 13 06:20:47 2002 +++ phpdoc/en/functions/dbx.xml Fri Feb 15 19:17:18 2002 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.24 $ --> +<!-- $Revision: 1.25 $ --> <reference id="ref.dbx"> <title>dbx functions</title> <titleabbrev>dbx</titleabbrev> @@ -38,7 +38,7 @@ <title>Description</title> <methodsynopsis> <type>bool</type><methodname>dbx_close</methodname> - <methodparam><type>dbx_link_object</type><parameter>link_identifier</parameter></methodparam> + +<methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> </methodsynopsis> <para> Returns &true; on success, @@ -49,8 +49,9 @@ <programlisting role="php"> <![CDATA[ <?php -$link = dbx_connect ("mysql", "localhost", "db", "username", "password") +$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") or die ("Could not connect"); + print("Connected successfully"); dbx_close($link); ?> @@ -76,80 +77,107 @@ <refsect1> <title>Description</title> <methodsynopsis> - <type>dbx_link_object</type><methodname>dbx_connect</methodname> - <methodparam><type>string</type><parameter>module</parameter></methodparam> + <type>object</type><methodname>dbx_connect</methodname> + <methodparam><type>mixed</type><parameter>module</parameter></methodparam> <methodparam><type>string</type><parameter>host</parameter></methodparam> <methodparam><type>string</type><parameter>database</parameter></methodparam> <methodparam><type>string</type><parameter>username</parameter></methodparam> <methodparam><type>string</type><parameter>password</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>persistent</parameter></methodparam> </methodsynopsis> - <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> + <simpara> + <function>dbx_connect</function> 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 <parameter>persistent</parameter> parameter can be set to + <constant>DBX_PERSISTENT</constant>, if so, a persistent connection will be + created. + </simpara> + <simpara> + The <parameter>module</parameter> 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. + </simpara> <para> <itemizedlist> <listitem> <simpara> - module DBX_MYSQL : "mysql" + <constant>DBX_MYSQL</constant> or "mysql" </simpara> </listitem> <listitem> <simpara> - module DBX_ODBC : "odbc" + <constant>DBX_ODBC</constant> or "odbc" </simpara> </listitem> <listitem> <simpara> - module DBX_PGSQL : "pgsql" + <constant>DBX_PGSQL</constant> or "pgsql" </simpara> </listitem> <listitem> <simpara> - module DBX_MSSQL : "mssql" + <constant>DBX_MSSQL</constant> or "mssql" </simpara> </listitem> <listitem> <simpara> - module DBX_FBSQL : "fbsql" (CVS only) + <constant>DBX_FBSQL</constant> or "fbsql" (available from PHP 4.1.0) </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"> + The <parameter>host</parameter>, <parameter>database</parameter>, + <parameter>username</parameter> and <parameter>password</parameter> + parameters are expected, but not always used depending on the connect + functions for the abstracted module. + </para> + <para> + The returned <varname>object</varname> has three properties: + <variablelist> + <varlistentry> + <term> + <property>database</property> + </term> + <listitem> + <simpara> + It is the name of the currently selected database. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <property>handle</property> + </term> + <listitem> + <para> + It is a valid handle for the connected database, and as such it can be + used in module-specific functions (if required). + <informalexample> + <programlisting role="php"> <![CDATA[ -<?php -$link = dbx_connect ("mysql", "localhost", "db", "username", "password"); +$link = dbx_connect (DBX_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. + </programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <property>module</property> + </term> + <listitem> + <simpara> + It is used internally by dbx only, and is actually the module number + mentioned above. + </simpara> + </listitem> + </varlistentry> + </variablelist> </para> <para> <example> @@ -157,8 +185,9 @@ <programlisting role="php"> <![CDATA[ <?php -$link = dbx_connect ("odbc", "", "db", "username", "password", DBX_PERSISTENT) +$link = dbx_connect (DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT) or die ("Could not connect"); + print ("Connected successfully"); dbx_close ($link); ?> @@ -189,26 +218,26 @@ <title>Description</title> <methodsynopsis> <type>string</type><methodname>dbx_error</methodname> - <methodparam><type>dbx_link_object</type><parameter>link_identifier</parameter></methodparam> + +<methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> </methodsynopsis> - <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> + <simpara> + <function>dbx_error</function> 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 + <parameter>link_identifier</parameter> parameter. + </simpara> <example> <title><function>dbx_error</function> example</title> <programlisting role="php"> <![CDATA[ <?php -$link = dbx_connect ("mysql", "localhost", "db", "username", "password") +$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") or die ("Could not connect"); -$result = dbx_query ($link, "select id from nonexistingtbl"); -if ($result==0) { + +$result = dbx_query($link, "select id from non_existing_table"); +if ( $result == 0 ) { echo dbx_error ($link); } dbx_close ($link); @@ -221,7 +250,7 @@ Always refer to the module-specific documentation as well. </para> <para> - The error-message for Microsoft SQL Server is actually the result + The error message for Microsoft SQL Server is actually the result of the <function>mssql_get_last_message</function> function. </para> </note> @@ -236,135 +265,227 @@ <refsect1> <title>Description</title> <methodsynopsis> - <type>dbx_result_object</type><methodname>dbx_query</methodname> - <methodparam><type>dbx_link_object</type><parameter>link_identifier</parameter></methodparam> + <type>object</type><methodname>dbx_query</methodname> + +<methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> <methodparam><type>string</type><parameter>sql_statement</parameter></methodparam> <methodparam choice="opt"><type>long</type><parameter>flags</parameter></methodparam> </methodsynopsis> + <simpara> + <function>dbx_query</function> returns an object or <literal>1</literal> + on success, and <literal>0</literal> on failure. The result object is + returned only if the query given in <parameter>sql_statement</parameter> + produces a result set. + </simpara> + <example> + <title>How to handle the returned value</title> + <programlisting role="php"> +<![CDATA[ +<?php +$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); +?> +]]> + </programlisting> + </example> + <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: + The <parameter>flags</parameter> 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 (|): + <variablelist> + <varlistentry> + <term> + <constant>DBX_RESULT_INDEX</constant> + </term> + <listitem> + <simpara> + It is <emphasis>always</emphasis> set, that is, the returned object + has a <property>data</property> property which is a 2 dimensional + array indexed numerically. For example, in the expression + <literal>data[2][3]</literal> <literal>2</literal> stands for the row + (or record) number and <literal>3</literal> stands for the column + (or field) number. The first row and column are indexed at 0. + </simpara> + <simpara> + If <constant>DBX_RESULT_ASSOC</constant> is also specified, the + returning object contains the information related to + <constant>DBX_RESULT_INFO</constant> too, even if it was not specified. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_RESULT_INFO</constant> + </term> + <listitem> + <simpara> + It provides info about columns, such as field names and field types. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_RESULT_ASSOC</constant> + </term> + <listitem> + <simpara> + It effects that the field values can be accessed with the respective + column names used as keys to the returned object's + <property>data</property> property. + </simpara> + <simpara> + Associated results are actually references to the numerically indexed + data, so modifying <literal>data[0][0]</literal> causes that + <literal>data[0]['field_name_for_first_column']</literal> is modified + as well. + </simpara> + </listitem> + </varlistentry> + </variablelist> + Note that <constant>DBX_RESULT_INDEX</constant> is always used, regardless + of the actual value of <parameter>flags</parameter> parameter. This means + that the following combinations is effective only: + <itemizedlist> + <listitem> + <simpara> + <constant>DBX_RESULT_INDEX</constant> + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_RESULT_INDEX</constant> | + <constant>DBX_RESULT_INFO</constant> + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_RESULT_INDEX</constant> | + <constant>DBX_RESULT_INFO</constant> | + <constant>DBX_RESULT_ASSOC</constant> - this is the default, if + <parameter>flags</parameter> is not specified. + </simpara> + </listitem> + </itemizedlist> </para> <para> - <informalexample role="php"> - <programlisting> + The returing <varname>object</varname> has four or five + properties depending on <parameter>flags</parameter>: + <variablelist> + <varlistentry> + <term> + <property>handle</property> + </term> + <listitem> + <para> + It is a valid handle for the connected database, and as such it can be + used in module specific functions (if required). + <informalexample role="php"> + <programlisting> <![CDATA[ -$result = dbx_query ($link, "SELECT id FROM tbl"); +$result = dbx_query ($link, "SELECT id FROM table"); 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"> + </programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <property>cols</property> and <property>rows</property> + </term> + <listitem> + <para> + These contain the number of columns (or fields) and rows (or records) + respectively. + <informalexample> + <programlisting role="php"> <![CDATA[ -$result = dbx_query ($link, "SELECT id FROM tbl"); -echo "result size: " . $result->rows . " x " . $result->cols . "<br>\n"; +$result = dbx_query ($link, 'SELECT id FROM table'); +echo $result->rows; // number of records +echo $result->cols; // number of fields ]]> - </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"> + </programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <property>info</property> (optional) + </term> + <listitem> + <simpara> + It is returned only if either <constant>DBX_RESULT_INFO</constant> or + <constant>DBX_RESULT_ASSOC</constant> is specified in the + <parameter>flags</parameter> parameter. It is a 2 dimensional array, + that has two named rows (<literal>name</literal> and + <literal>type</literal>) to retrieve column information. + </simpara> + <example> + <title>lists each field's name and type</title> + <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"; +$result = dbx_query ($link, 'SELECT id FROM table', DBX_RESULT_INDEX | +DBX_RESULT_INFO); + +for ($i = 0; $i < $result->cols; $i++ ) { + echo $result->info['name'][$i] . "\n"; + echo $result->info['type'][$i] . "\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"> + </programlisting> + </example> + </listitem> + </varlistentry> + <varlistentry> + <term> + <property>data</property> + </term> + <listitem> + <simpara> + This property contains the actual resulting data, possibly associated + with column names as well depending on <parameter>flags</parameter>. + If <constant>DBX_RESULT_ASSOC</constant> is set, it is possible to use + <literal>$result->data[2]["field_name"]</literal>. + </simpara> + <example> + <title>outputs the content of data property into HTML table</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>"; +$result = dbx_query ($link, 'SELECT id, parentid, description FROM table'); + +echo "<table>\n"; +foreach ( $result->data as $row ) { + echo "<tr>\n"; + foreach ( $row as $field ) { + echo "<td>$field</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); -?> +echo "</table>\n"; ]]> - </programlisting> - </example> + </programlisting> + </example> + </listitem> + </varlistentry> + </variablelist> + </para> <note> <para> Always refer to the module-specific documentation as well. @@ -387,13 +508,20 @@ <title>Description</title> <methodsynopsis> <type>bool</type><methodname>dbx_sort</methodname> - <methodparam><type>dbx_result_object</type><parameter>result</parameter></methodparam> + <methodparam><type>object</type><parameter>result</parameter></methodparam> <methodparam><type>string</type><parameter>user_compare_function</parameter></methodparam> </methodsynopsis> <para> Returns &true; on success, &false; on error. </para> + <note> + <simpara> + It is always better to use <literal>ORDER BY</literal> + <literal>SQL</literal> clause instead of <function>dbx_sort</function>, + if possible. + </simpara> + </note> <example> <title><function>dbx_sort</function> example</title> <programlisting role="php"> @@ -401,16 +529,21 @@ <?php function user_re_order ($a, $b) { $rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC); - if (!$rv) $rv = dbx_compare ($a, $b, "id"); + if ( !$rv ) { + $rv = dbx_compare ($a, $b, "id", DBX_CMP_NUMBER); + } return $rv; } -$link = dbx_connect ("odbc", "", "db", "username", "password") +$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>"; + // 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<br>"; + // data in $result is now ordered by parentid (descending), then by id + dbx_close ($link); ?> ]]> @@ -433,24 +566,57 @@ <type>int</type><methodname>dbx_compare</methodname> <methodparam><type>array</type><parameter>row_a</parameter></methodparam> <methodparam><type>array</type><parameter>row_b</parameter></methodparam> - <methodparam><type>string</type><parameter>columnname_or_index</parameter></methodparam> + <methodparam><type>string</type><parameter>column_key</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam> </methodsynopsis> <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). + <function>dbx_compare</function> returns <literal>0</literal> if the + <literal>row_a[$column_key]</literal> is equal to + <literal>row_b[$column_key]</literal>, and <literal>1</literal> or + <literal>-1</literal> if the former is greater or is smaller than + the latter one, respectively, or vice versa if the + <parameter>flag</parameter> is set to <constant>DBX_CMP_DESC</constant>. + <function>dbx_compare</function> is a helper function for + <function>dbx_sort</function> to ease the make and use of the custom + sorting function. </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. + direction: + <itemizedlist> + <listitem> + <simpara> + <constant>DBX_CMP_ASC</constant> - ascending order + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_CMP_DESC</constant> - descending order + </simpara> + </listitem> + </itemizedlist> + and the preferred comparison type: + <itemizedlist> + <listitem> + <simpara> + <constant>DBX_CMP_NATIVE</constant> - no type conversion + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_CMP_TEXT</constant> - compare items as strings + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_CMP_NUMBER</constant> - compare items numerically + </simpara> + </listitem> + </itemizedlist> + One of the direction and one of the type constant can be combined with + bitwise OR operator (|). The default value for the + <parameter>flags</parameter> parameter is <constant>DBX_CMP_ASC</constant> + | <constant>DBX_CMP_NATIVE</constant>. </para> <example> <title><function>dbx_compare</function> example</title> @@ -459,18 +625,21 @@ <?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; + if ( !$rv ) { + $rv = dbx_compare ($a, $b, "id", DBX_CMP_NUMBER); } + return $rv; } -$link = dbx_connect ("odbc", "", "db", "username", "password") +$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>"; + +$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<br>"; + // date in $result is now ordered by parentid (descending), then by id + dbx_close ($link); ?> ]]> @@ -503,5 +672,4 @@ 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