cvs: phpdoc /en/reference/dbx/functions dbx-close.xml dbx-compare.xml dbx-connect.xml dbx-error.xml dbx-escape-string.xml dbx-fetch-row.xml
dbx-query.xml dbx-sort.xml
| From: | Mehdi Achour | Date: | Mon, 08 Jan 2007 02:00:40 +0000 |
| Subject: | cvs: phpdoc /en/reference/dbx/functions dbx-close.xml dbx-compare.xml dbx-connect.xml dbx-error.xml dbx-escape-string.xml dbx-fetch-row.xml dbx-query.xml dbx-sort.xml |
||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969374725@lists.php.net to get a copy of this message | ||
didou Mon Jan 8 02:00:40 2007 UTC
Modified files:
/phpdoc/en/reference/dbx/functions dbx-close.xml dbx-compare.xml
dbx-connect.xml dbx-error.xml
dbx-escape-string.xml
dbx-fetch-row.xml dbx-query.xml
dbx-sort.xml
Log:
Switch to new doc style
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-close.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-close.xml diff -u phpdoc/en/reference/dbx/functions/dbx-close.xml:1.7 phpdoc/en/reference/dbx/functions/dbx-close.xml:1.8 --- phpdoc/en/reference/dbx/functions/dbx-close.xml:1.7 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-close.xml Mon Jan 8 02:00:39 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <refentry id="function.dbx-close"> <refnamediv> <refname>dbx_close</refname> @@ -7,16 +7,38 @@ </refnamediv> <refsect1> <title>Description</title> - <methodsynopsis> - <type>bool</type><methodname>dbx_close</methodname> - <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> - </methodsynopsis> + <methodsynopsis> + <type>int</type><methodname>dbx_close</methodname> + <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> + </methodsynopsis> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; <para> - &return.success; + <variablelist> + <varlistentry> + <term><parameter>link_identifier</parameter></term> + <listitem> + <para> + The DBX link object to close. + </para> + </listitem> + </varlistentry> + </variablelist> </para> - <example> - <title><function>dbx_close</function> example</title> - <programlisting role="php"> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns 1 on success and 0 on errors. + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_close</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") @@ -26,15 +48,24 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Always refer to the module-specific documentation as well. </para> </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_connect</function>. + <simplelist> + <member><function>dbx_connect</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-compare.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-compare.xml diff -u phpdoc/en/reference/dbx/functions/dbx-compare.xml:1.5 phpdoc/en/reference/dbx/functions/dbx-compare.xml:1.6 --- phpdoc/en/reference/dbx/functions/dbx-compare.xml:1.5 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-compare.xml Mon Jan 8 02:00:40 2007 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <refentry id="function.dbx-compare"> <refnamediv> <refname>dbx_compare</refname> <refpurpose>Compare two rows for sorting purposes</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>dbx_compare</methodname> <methodparam><type>array</type><parameter>row_a</parameter></methodparam> @@ -15,57 +15,101 @@ <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam> </methodsynopsis> <para> - <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> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>row_a</parameter></term> + <listitem> + <para> + First row + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>row_b</parameter></term> + <listitem> + <para> + Second row + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>column_key</parameter></term> + <listitem> + <para> + The compared column + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para> + The <parameter>flags</parameter> can be set to specify comparison + 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> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - The <parameter>flags</parameter> can be set to specify comparison - 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>. + 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>. </para> - <example> - <title><function>dbx_compare</function> example</title> - <programlisting role="php"> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_compare</function> example</title> + <programlisting role="php"> <![CDATA[ <?php function user_re_order($a, $b) @@ -89,10 +133,16 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_sort</function>. + <simplelist> + <member><function>dbx_sort</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-connect.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-connect.xml diff -u phpdoc/en/reference/dbx/functions/dbx-connect.xml:1.12 phpdoc/en/reference/dbx/functions/dbx-connect.xml:1.13 --- phpdoc/en/reference/dbx/functions/dbx-connect.xml:1.12 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-connect.xml Mon Jan 8 02:00:40 2007 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.12 $ --> +<!-- $Revision: 1.13 $ --> <refentry id="function.dbx-connect"> <refnamediv> <refname>dbx_connect</refname> <refpurpose>Open a connection/database</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>object</type><methodname>dbx_connect</methodname> <methodparam><type>mixed</type><parameter>module</parameter></methodparam> @@ -16,64 +16,113 @@ <methodparam><type>string</type><parameter>password</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>persistent</parameter></methodparam> </methodsynopsis> - <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> - <constant>DBX_MYSQL</constant> or "mysql" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_ODBC</constant> or "odbc" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_PGSQL</constant> or "pgsql" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_MSSQL</constant> or "mssql" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_FBSQL</constant> or "fbsql" (available from PHP 4.1.0) - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_SYBASECT</constant> or "sybase_ct" (available from PHP - 4.2.0) - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_OCI8</constant> or "oci8" (available from PHP 4.3.0) - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_SQLITE</constant> or "sqlite" (PHP 5) - </simpara> - </listitem> - </itemizedlist> + <para> + Opens a connection to a database. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>module</parameter></term> + <listitem> + <para> + 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. + </para> + <para> + <itemizedlist> + <listitem> + <simpara> + <constant>DBX_MYSQL</constant> or "mysql" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_ODBC</constant> or "odbc" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_PGSQL</constant> or "pgsql" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_MSSQL</constant> or "mssql" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_FBSQL</constant> or "fbsql" (available from PHP 4.1.0) + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_SYBASECT</constant> or "sybase_ct" (available from PHP + 4.2.0) + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_OCI8</constant> or "oci8" (available from PHP 4.3.0) + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_SQLITE</constant> or "sqlite" (PHP 5) + </simpara> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem> + <para> + The SQL server host + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>database</parameter></term> + <listitem> + <para> + The database name + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>username</parameter></term> + <listitem> + <para> + The username + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>password</parameter></term> + <listitem> + <para> + The password + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>persistent</parameter></term> + <listitem> + <para> + The <parameter>persistent</parameter> parameter can be set to + <constant>DBX_PERSISTENT</constant>, if so, a persistent connection + will be created. + </para> + </listitem> + </varlistentry> + </variablelist> </para> <para> The <parameter>host</parameter>, <parameter>database</parameter>, @@ -81,6 +130,14 @@ parameters are expected, but not always used depending on the connect functions for the abstracted module. </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + 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. + </para> <para> The returned <varname>object</varname> has three properties: <variablelist> @@ -128,6 +185,9 @@ </varlistentry> </variablelist> </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>dbx_connect</function> example</title> @@ -143,14 +203,22 @@ ]]> </programlisting> </example> - <note> - <para> - Always refer to the module-specific documentation as well. - </para> - </note> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + Always refer to the module-specific documentation as well. + </para> + </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_close</function>. + <simplelist> + <member><function>dbx_close</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-error.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-error.xml diff -u phpdoc/en/reference/dbx/functions/dbx-error.xml:1.5 phpdoc/en/reference/dbx/functions/dbx-error.xml:1.6 --- phpdoc/en/reference/dbx/functions/dbx-error.xml:1.5 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-error.xml Mon Jan 8 02:00:40 2007 @@ -1,30 +1,53 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <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) + Report the error message of the latest function call in the module </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>dbx_error</methodname> <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> </methodsynopsis> - <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"> + <para> + <function>dbx_error</function> returns the last error message. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>link_identifier</parameter></term> + <listitem> + <para> + The DBX link object returned by <function>dbx_connect</function> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + 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. + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_error</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") @@ -37,8 +60,12 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Always refer to the module-specific documentation as well. @@ -48,7 +75,7 @@ of the <function>mssql_get_last_message</function> function. </para> <para> - The error message for Oracle (oci8) is not implemented (yet). + The error message for Oracle (oci8) is not implemented yet. </para> </note> </refsect1> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-escape-string.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-escape-string.xml diff -u phpdoc/en/reference/dbx/functions/dbx-escape-string.xml:1.7 phpdoc/en/reference/dbx/functions/dbx-escape-string.xml:1.8 --- phpdoc/en/reference/dbx/functions/dbx-escape-string.xml:1.7 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-escape-string.xml Mon Jan 8 02:00:40 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <refentry id="function.dbx-escape-string"> <refnamediv> <refname>dbx_escape_string</refname> @@ -7,21 +7,53 @@ Escape a string so it can safely be used in an sql-statement </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>dbx_escape_string</methodname> <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> <methodparam><type>string</type><parameter>text</parameter></methodparam> </methodsynopsis> - <simpara> - <function>dbx_escape_string</function> returns the text, escaped - where necessary (such as quotes, backslashes etc). It returns - NULL on error. - </simpara> - <example> - <title><function>dbx_escape_string</function> example</title> - <programlisting role="php"> + <para> + Escape the given string so that it can safely be used in an sql-statement. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>link_identifier</parameter></term> + <listitem> + <para> + The DBX link object returned by <function>dbx_connect</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>text</parameter></term> + <listitem> + <para> + The string to escape. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the text, escaped where necessary (such as quotes, backslashes + etc). On error, &null; is returned. + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_escape_string</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") @@ -35,10 +67,16 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_query</function>. + <simplelist> + <member><function>dbx_query</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml diff -u phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml:1.6 phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml:1.7 --- phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml:1.6 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml Mon Jan 8 02:00:40 2007 @@ -1,31 +1,66 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.dbx-fetch-row"> <refnamediv> <refname>dbx_fetch_row</refname> <refpurpose>Fetches rows from a query-result that had the <constant>DBX_RESULT_UNBUFFERED</constant> flag set</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</type><methodname>dbx_fetch_row</methodname> <methodparam><type>object</type><parameter>result_identifier</parameter></methodparam> </methodsynopsis> - <simpara> - <function>dbx_fetch_row</function> returns a row on success, and - <literal>0</literal> on failure (e.g. when no more rows are available). + <para> + <function>dbx_fetch_row</function> fetches rows from a result identifier + that had the <constant>DBX_RESULT_UNBUFFERED</constant> flag set. + </para> + <para> When the <constant>DBX_RESULT_UNBUFFERED</constant> is not set in the query, <function>dbx_fetch_row</function> will fail as all rows have already been fetched into the results <property>data</property> property. - </simpara> - <simpara> + </para> + <para> As a side effect, the <property>rows</property> property of the query-result object is incremented for each successful call to <function>dbx_fetch_row</function>. - </simpara> - <example> - <title>How to handle the returned value</title> + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result_identifier</parameter></term> + <listitem> + <para> + A result set returned by <function>dbx_query</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an object on success that contains the same information as any row + would have in the <function>dbx_query</function> result + <property>data</property> property, including columns accessible by index + or fieldname when the flags for <function>dbx_query</function> were set + that way. + </para> + <para> + Upon failure, returns <literal>0</literal> (e.g. when no more rows are + available). + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title>How to handle the returned value</title> <programlisting role="php"> <![CDATA[ <?php @@ -43,19 +78,15 @@ ?> ]]> </programlisting> - </example> - <para> - The <parameter>result_identifier</parameter> parameter is the result - object returned by a call to <function>dbx_query</function>. - </para> - <para> - The returned object contains the same information as any row would have - in the dbx_query result <property>data</property> property, including - columns accessible by index or fieldname when the flags for dbx_guery - were set that way. + </example> </para> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_query</function>. + <simplelist> + <member><function>dbx_query</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-query.xml?r1=1.19&r2=1.20&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-query.xml diff -u phpdoc/en/reference/dbx/functions/dbx-query.xml:1.19 phpdoc/en/reference/dbx/functions/dbx-query.xml:1.20 --- phpdoc/en/reference/dbx/functions/dbx-query.xml:1.19 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-query.xml Mon Jan 8 02:00:40 2007 @@ -1,177 +1,196 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.19 $ --> +<!-- $Revision: 1.20 $ --> <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> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</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>int</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 (i.e. a SELECT query, even if the result set is - empty). - </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 { - exit("Query failed"); -} - -dbx_close($link); -?> -]]> - </programlisting> - </example> <para> - 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 (|). The DBX_COLNAMES_* flags - override the dbx.colnames_case setting from &php.ini;. + Sends a query and fetch all results. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> <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> - <varlistentry> - <term> - <constant>DBX_RESULT_UNBUFFERED</constant> (PHP 5) - </term> + <term><parameter>link_identifier</parameter></term> <listitem> - <simpara> - This flag will not create the <property>data</property> property, and - the <property>rows</property> property will initially be 0. Use this - flag for large datasets, and use <function>dbx_fetch_row</function> to - retrieve the results row by row. - </simpara> - <simpara> - The <function>dbx_fetch_row</function> function will return rows that - are conformant to the flags set with this query. Incidentally, it will - also update the <property>rows</property> each time it is called. - </simpara> + <para> + The DBX link object returned by <function>dbx_connect</function> + </para> </listitem> </varlistentry> <varlistentry> - <term> - <constant>DBX_COLNAMES_UNCHANGED</constant> (available from PHP 4.3.0) - </term> + <term><parameter>sql_statement</parameter></term> <listitem> - <simpara> - The case of the returned column names will not be changed. - </simpara> + <para> + SQL statement. + </para> </listitem> </varlistentry> <varlistentry> - <term> - <constant>DBX_COLNAMES_UPPERCASE</constant> (available from PHP 4.3.0) - </term> + <term><parameter>flags</parameter></term> <listitem> - <simpara> - The case of the returned column names will be changed to - uppercase. - </simpara> + <para> + The compared column + </para> </listitem> </varlistentry> <varlistentry> - <term> - <constant>DBX_COLNAMES_LOWERCASE</constant> (available from PHP 4.3.0) - </term> + <term><parameter>flags</parameter></term> <listitem> - <simpara> - The case of the returned column names will be changed to - lowercase. - </simpara> + <para> + 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 (|). The DBX_COLNAMES_* flags + override the dbx.colnames_case setting from &php.ini;. + <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> + <varlistentry> + <term> + <constant>DBX_RESULT_UNBUFFERED</constant> (PHP 5) + </term> + <listitem> + <simpara> + This flag will not create the <property>data</property> property, and + the <property>rows</property> property will initially be 0. Use this + flag for large datasets, and use <function>dbx_fetch_row</function> to + retrieve the results row by row. + </simpara> + <simpara> + The <function>dbx_fetch_row</function> function will return rows that + are conformant to the flags set with this query. Incidentally, it will + also update the <property>rows</property> each time it is called. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_COLNAMES_UNCHANGED</constant> (available from PHP 4.3.0) + </term> + <listitem> + <simpara> + The case of the returned column names will not be changed. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_COLNAMES_UPPERCASE</constant> (available from PHP 4.3.0) + </term> + <listitem> + <simpara> + The case of the returned column names will be changed to + uppercase. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_COLNAMES_LOWERCASE</constant> (available from PHP 4.3.0) + </term> + <listitem> + <simpara> + The case of the returned column names will be changed to + lowercase. + </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 only the following combinations are effective: + <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> </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 only the following combinations are effective: - <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> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + <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 (i.e. a SELECT query, even if the result set is + empty). </para> <para> The returned <varname>object</varname> has four or five @@ -307,19 +326,54 @@ </varlistentry> </variablelist> </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <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 { + exit("Query failed"); +} + +dbx_close($link); +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Always refer to the module-specific documentation as well. </para> <para> - Column names for queries on an Oracle database are returned - in lowercase. + Column names for queries on an Oracle database are returned in lowercase. </para> </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_escape_string</function>, - <function>dbx_fetch_row</function> and - <function>dbx_connect</function>. + <simplelist> + <member><function>dbx_escape_string</function></member> + <member><function>dbx_fetch_row</function></member> + <member><function>dbx_connect</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-sort.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-sort.xml diff -u phpdoc/en/reference/dbx/functions/dbx-sort.xml:1.6 phpdoc/en/reference/dbx/functions/dbx-sort.xml:1.7 --- phpdoc/en/reference/dbx/functions/dbx-sort.xml:1.6 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-sort.xml Mon Jan 8 02:00:40 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.dbx-sort"> <refnamediv> <refname>dbx_sort</refname> @@ -7,26 +7,56 @@ Sort a result from a dbx_query by a custom sort function </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>dbx_sort</methodname> <methodparam><type>object</type><parameter>result</parameter></methodparam> <methodparam><type>string</type><parameter>user_compare_function</parameter></methodparam> </methodsynopsis> <para> + Sort a result from a <function>dbx_query</function> call with a custom sort + function. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result</parameter></term> + <listitem> + <para> + A result set returned by <function>dbx_query</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_compare_function</parameter></term> + <listitem> + <para> + The user-defined comparison function. It must accept two arguments and + return an integer less than, equal to, or greater than zero if the + first argument is considered to be respectively less than, equal to, + or greater than the second. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> &return.success; </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"> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_sort</function> example</title> + <programlisting role="php"> <![CDATA[ <?php function user_re_order($a, $b) @@ -50,10 +80,26 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + It is always better to use <literal>ORDER BY</literal> + <literal>SQL</literal> clause instead of <function>dbx_sort</function> + if possible. + </para> + </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_compare</function>. + <simplelist> + <member><function>dbx_compare</function></member> + </simplelist> </para> </refsect1> </refentry>
http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-close.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-close.xml diff -u phpdoc/en/reference/dbx/functions/dbx-close.xml:1.7 phpdoc/en/reference/dbx/functions/dbx-close.xml:1.8 --- phpdoc/en/reference/dbx/functions/dbx-close.xml:1.7 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-close.xml Mon Jan 8 02:00:39 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <refentry id="function.dbx-close"> <refnamediv> <refname>dbx_close</refname> @@ -7,16 +7,38 @@ </refnamediv> <refsect1> <title>Description</title> - <methodsynopsis> - <type>bool</type><methodname>dbx_close</methodname> - <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> - </methodsynopsis> + <methodsynopsis> + <type>int</type><methodname>dbx_close</methodname> + <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> + </methodsynopsis> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; <para> - &return.success; + <variablelist> + <varlistentry> + <term><parameter>link_identifier</parameter></term> + <listitem> + <para> + The DBX link object to close. + </para> + </listitem> + </varlistentry> + </variablelist> </para> - <example> - <title><function>dbx_close</function> example</title> - <programlisting role="php"> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns 1 on success and 0 on errors. + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_close</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") @@ -26,15 +48,24 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Always refer to the module-specific documentation as well. </para> </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_connect</function>. + <simplelist> + <member><function>dbx_connect</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-compare.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-compare.xml diff -u phpdoc/en/reference/dbx/functions/dbx-compare.xml:1.5 phpdoc/en/reference/dbx/functions/dbx-compare.xml:1.6 --- phpdoc/en/reference/dbx/functions/dbx-compare.xml:1.5 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-compare.xml Mon Jan 8 02:00:40 2007 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <refentry id="function.dbx-compare"> <refnamediv> <refname>dbx_compare</refname> <refpurpose>Compare two rows for sorting purposes</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>dbx_compare</methodname> <methodparam><type>array</type><parameter>row_a</parameter></methodparam> @@ -15,57 +15,101 @@ <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam> </methodsynopsis> <para> - <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> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>row_a</parameter></term> + <listitem> + <para> + First row + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>row_b</parameter></term> + <listitem> + <para> + Second row + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>column_key</parameter></term> + <listitem> + <para> + The compared column + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para> + The <parameter>flags</parameter> can be set to specify comparison + 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> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - The <parameter>flags</parameter> can be set to specify comparison - 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>. + 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>. </para> - <example> - <title><function>dbx_compare</function> example</title> - <programlisting role="php"> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_compare</function> example</title> + <programlisting role="php"> <![CDATA[ <?php function user_re_order($a, $b) @@ -89,10 +133,16 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_sort</function>. + <simplelist> + <member><function>dbx_sort</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-connect.xml?r1=1.12&r2=1.13&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-connect.xml diff -u phpdoc/en/reference/dbx/functions/dbx-connect.xml:1.12 phpdoc/en/reference/dbx/functions/dbx-connect.xml:1.13 --- phpdoc/en/reference/dbx/functions/dbx-connect.xml:1.12 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-connect.xml Mon Jan 8 02:00:40 2007 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.12 $ --> +<!-- $Revision: 1.13 $ --> <refentry id="function.dbx-connect"> <refnamediv> <refname>dbx_connect</refname> <refpurpose>Open a connection/database</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>object</type><methodname>dbx_connect</methodname> <methodparam><type>mixed</type><parameter>module</parameter></methodparam> @@ -16,64 +16,113 @@ <methodparam><type>string</type><parameter>password</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>persistent</parameter></methodparam> </methodsynopsis> - <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> - <constant>DBX_MYSQL</constant> or "mysql" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_ODBC</constant> or "odbc" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_PGSQL</constant> or "pgsql" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_MSSQL</constant> or "mssql" - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_FBSQL</constant> or "fbsql" (available from PHP 4.1.0) - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_SYBASECT</constant> or "sybase_ct" (available from PHP - 4.2.0) - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_OCI8</constant> or "oci8" (available from PHP 4.3.0) - </simpara> - </listitem> - <listitem> - <simpara> - <constant>DBX_SQLITE</constant> or "sqlite" (PHP 5) - </simpara> - </listitem> - </itemizedlist> + <para> + Opens a connection to a database. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>module</parameter></term> + <listitem> + <para> + 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. + </para> + <para> + <itemizedlist> + <listitem> + <simpara> + <constant>DBX_MYSQL</constant> or "mysql" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_ODBC</constant> or "odbc" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_PGSQL</constant> or "pgsql" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_MSSQL</constant> or "mssql" + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_FBSQL</constant> or "fbsql" (available from PHP 4.1.0) + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_SYBASECT</constant> or "sybase_ct" (available from PHP + 4.2.0) + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_OCI8</constant> or "oci8" (available from PHP 4.3.0) + </simpara> + </listitem> + <listitem> + <simpara> + <constant>DBX_SQLITE</constant> or "sqlite" (PHP 5) + </simpara> + </listitem> + </itemizedlist> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem> + <para> + The SQL server host + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>database</parameter></term> + <listitem> + <para> + The database name + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>username</parameter></term> + <listitem> + <para> + The username + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>password</parameter></term> + <listitem> + <para> + The password + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>persistent</parameter></term> + <listitem> + <para> + The <parameter>persistent</parameter> parameter can be set to + <constant>DBX_PERSISTENT</constant>, if so, a persistent connection + will be created. + </para> + </listitem> + </varlistentry> + </variablelist> </para> <para> The <parameter>host</parameter>, <parameter>database</parameter>, @@ -81,6 +130,14 @@ parameters are expected, but not always used depending on the connect functions for the abstracted module. </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + 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. + </para> <para> The returned <varname>object</varname> has three properties: <variablelist> @@ -128,6 +185,9 @@ </varlistentry> </variablelist> </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>dbx_connect</function> example</title> @@ -143,14 +203,22 @@ ]]> </programlisting> </example> - <note> - <para> - Always refer to the module-specific documentation as well. - </para> - </note> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + Always refer to the module-specific documentation as well. + </para> + </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_close</function>. + <simplelist> + <member><function>dbx_close</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-error.xml?r1=1.5&r2=1.6&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-error.xml diff -u phpdoc/en/reference/dbx/functions/dbx-error.xml:1.5 phpdoc/en/reference/dbx/functions/dbx-error.xml:1.6 --- phpdoc/en/reference/dbx/functions/dbx-error.xml:1.5 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-error.xml Mon Jan 8 02:00:40 2007 @@ -1,30 +1,53 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <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) + Report the error message of the latest function call in the module </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>dbx_error</methodname> <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> </methodsynopsis> - <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"> + <para> + <function>dbx_error</function> returns the last error message. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>link_identifier</parameter></term> + <listitem> + <para> + The DBX link object returned by <function>dbx_connect</function> + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + 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. + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_error</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") @@ -37,8 +60,12 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Always refer to the module-specific documentation as well. @@ -48,7 +75,7 @@ of the <function>mssql_get_last_message</function> function. </para> <para> - The error message for Oracle (oci8) is not implemented (yet). + The error message for Oracle (oci8) is not implemented yet. </para> </note> </refsect1> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-escape-string.xml?r1=1.7&r2=1.8&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-escape-string.xml diff -u phpdoc/en/reference/dbx/functions/dbx-escape-string.xml:1.7 phpdoc/en/reference/dbx/functions/dbx-escape-string.xml:1.8 --- phpdoc/en/reference/dbx/functions/dbx-escape-string.xml:1.7 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-escape-string.xml Mon Jan 8 02:00:40 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> +<!-- $Revision: 1.8 $ --> <refentry id="function.dbx-escape-string"> <refnamediv> <refname>dbx_escape_string</refname> @@ -7,21 +7,53 @@ Escape a string so it can safely be used in an sql-statement </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>dbx_escape_string</methodname> <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam> <methodparam><type>string</type><parameter>text</parameter></methodparam> </methodsynopsis> - <simpara> - <function>dbx_escape_string</function> returns the text, escaped - where necessary (such as quotes, backslashes etc). It returns - NULL on error. - </simpara> - <example> - <title><function>dbx_escape_string</function> example</title> - <programlisting role="php"> + <para> + Escape the given string so that it can safely be used in an sql-statement. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>link_identifier</parameter></term> + <listitem> + <para> + The DBX link object returned by <function>dbx_connect</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>text</parameter></term> + <listitem> + <para> + The string to escape. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the text, escaped where necessary (such as quotes, backslashes + etc). On error, &null; is returned. + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_escape_string</function> example</title> + <programlisting role="php"> <![CDATA[ <?php $link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password") @@ -35,10 +67,16 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_query</function>. + <simplelist> + <member><function>dbx_query</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml diff -u phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml:1.6 phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml:1.7 --- phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml:1.6 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-fetch-row.xml Mon Jan 8 02:00:40 2007 @@ -1,31 +1,66 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.dbx-fetch-row"> <refnamediv> <refname>dbx_fetch_row</refname> <refpurpose>Fetches rows from a query-result that had the <constant>DBX_RESULT_UNBUFFERED</constant> flag set</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</type><methodname>dbx_fetch_row</methodname> <methodparam><type>object</type><parameter>result_identifier</parameter></methodparam> </methodsynopsis> - <simpara> - <function>dbx_fetch_row</function> returns a row on success, and - <literal>0</literal> on failure (e.g. when no more rows are available). + <para> + <function>dbx_fetch_row</function> fetches rows from a result identifier + that had the <constant>DBX_RESULT_UNBUFFERED</constant> flag set. + </para> + <para> When the <constant>DBX_RESULT_UNBUFFERED</constant> is not set in the query, <function>dbx_fetch_row</function> will fail as all rows have already been fetched into the results <property>data</property> property. - </simpara> - <simpara> + </para> + <para> As a side effect, the <property>rows</property> property of the query-result object is incremented for each successful call to <function>dbx_fetch_row</function>. - </simpara> - <example> - <title>How to handle the returned value</title> + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result_identifier</parameter></term> + <listitem> + <para> + A result set returned by <function>dbx_query</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an object on success that contains the same information as any row + would have in the <function>dbx_query</function> result + <property>data</property> property, including columns accessible by index + or fieldname when the flags for <function>dbx_query</function> were set + that way. + </para> + <para> + Upon failure, returns <literal>0</literal> (e.g. when no more rows are + available). + </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title>How to handle the returned value</title> <programlisting role="php"> <![CDATA[ <?php @@ -43,19 +78,15 @@ ?> ]]> </programlisting> - </example> - <para> - The <parameter>result_identifier</parameter> parameter is the result - object returned by a call to <function>dbx_query</function>. - </para> - <para> - The returned object contains the same information as any row would have - in the dbx_query result <property>data</property> property, including - columns accessible by index or fieldname when the flags for dbx_guery - were set that way. + </example> </para> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_query</function>. + <simplelist> + <member><function>dbx_query</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-query.xml?r1=1.19&r2=1.20&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-query.xml diff -u phpdoc/en/reference/dbx/functions/dbx-query.xml:1.19 phpdoc/en/reference/dbx/functions/dbx-query.xml:1.20 --- phpdoc/en/reference/dbx/functions/dbx-query.xml:1.19 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-query.xml Mon Jan 8 02:00:40 2007 @@ -1,177 +1,196 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.19 $ --> +<!-- $Revision: 1.20 $ --> <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> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>mixed</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>int</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 (i.e. a SELECT query, even if the result set is - empty). - </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 { - exit("Query failed"); -} - -dbx_close($link); -?> -]]> - </programlisting> - </example> <para> - 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 (|). The DBX_COLNAMES_* flags - override the dbx.colnames_case setting from &php.ini;. + Sends a query and fetch all results. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> <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> - <varlistentry> - <term> - <constant>DBX_RESULT_UNBUFFERED</constant> (PHP 5) - </term> + <term><parameter>link_identifier</parameter></term> <listitem> - <simpara> - This flag will not create the <property>data</property> property, and - the <property>rows</property> property will initially be 0. Use this - flag for large datasets, and use <function>dbx_fetch_row</function> to - retrieve the results row by row. - </simpara> - <simpara> - The <function>dbx_fetch_row</function> function will return rows that - are conformant to the flags set with this query. Incidentally, it will - also update the <property>rows</property> each time it is called. - </simpara> + <para> + The DBX link object returned by <function>dbx_connect</function> + </para> </listitem> </varlistentry> <varlistentry> - <term> - <constant>DBX_COLNAMES_UNCHANGED</constant> (available from PHP 4.3.0) - </term> + <term><parameter>sql_statement</parameter></term> <listitem> - <simpara> - The case of the returned column names will not be changed. - </simpara> + <para> + SQL statement. + </para> </listitem> </varlistentry> <varlistentry> - <term> - <constant>DBX_COLNAMES_UPPERCASE</constant> (available from PHP 4.3.0) - </term> + <term><parameter>flags</parameter></term> <listitem> - <simpara> - The case of the returned column names will be changed to - uppercase. - </simpara> + <para> + The compared column + </para> </listitem> </varlistentry> <varlistentry> - <term> - <constant>DBX_COLNAMES_LOWERCASE</constant> (available from PHP 4.3.0) - </term> + <term><parameter>flags</parameter></term> <listitem> - <simpara> - The case of the returned column names will be changed to - lowercase. - </simpara> + <para> + 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 (|). The DBX_COLNAMES_* flags + override the dbx.colnames_case setting from &php.ini;. + <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> + <varlistentry> + <term> + <constant>DBX_RESULT_UNBUFFERED</constant> (PHP 5) + </term> + <listitem> + <simpara> + This flag will not create the <property>data</property> property, and + the <property>rows</property> property will initially be 0. Use this + flag for large datasets, and use <function>dbx_fetch_row</function> to + retrieve the results row by row. + </simpara> + <simpara> + The <function>dbx_fetch_row</function> function will return rows that + are conformant to the flags set with this query. Incidentally, it will + also update the <property>rows</property> each time it is called. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_COLNAMES_UNCHANGED</constant> (available from PHP 4.3.0) + </term> + <listitem> + <simpara> + The case of the returned column names will not be changed. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_COLNAMES_UPPERCASE</constant> (available from PHP 4.3.0) + </term> + <listitem> + <simpara> + The case of the returned column names will be changed to + uppercase. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term> + <constant>DBX_COLNAMES_LOWERCASE</constant> (available from PHP 4.3.0) + </term> + <listitem> + <simpara> + The case of the returned column names will be changed to + lowercase. + </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 only the following combinations are effective: + <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> </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 only the following combinations are effective: - <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> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + <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 (i.e. a SELECT query, even if the result set is + empty). </para> <para> The returned <varname>object</varname> has four or five @@ -307,19 +326,54 @@ </varlistentry> </variablelist> </para> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <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 { + exit("Query failed"); +} + +dbx_close($link); +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; <note> <para> Always refer to the module-specific documentation as well. </para> <para> - Column names for queries on an Oracle database are returned - in lowercase. + Column names for queries on an Oracle database are returned in lowercase. </para> </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_escape_string</function>, - <function>dbx_fetch_row</function> and - <function>dbx_connect</function>. + <simplelist> + <member><function>dbx_escape_string</function></member> + <member><function>dbx_fetch_row</function></member> + <member><function>dbx_connect</function></member> + </simplelist> </para> </refsect1> </refentry> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/dbx/functions/dbx-sort.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/dbx/functions/dbx-sort.xml diff -u phpdoc/en/reference/dbx/functions/dbx-sort.xml:1.6 phpdoc/en/reference/dbx/functions/dbx-sort.xml:1.7 --- phpdoc/en/reference/dbx/functions/dbx-sort.xml:1.6 Mon Jan 8 01:02:31 2007 +++ phpdoc/en/reference/dbx/functions/dbx-sort.xml Mon Jan 8 02:00:40 2007 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.6 $ --> +<!-- $Revision: 1.7 $ --> <refentry id="function.dbx-sort"> <refnamediv> <refname>dbx_sort</refname> @@ -7,26 +7,56 @@ Sort a result from a dbx_query by a custom sort function </refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>dbx_sort</methodname> <methodparam><type>object</type><parameter>result</parameter></methodparam> <methodparam><type>string</type><parameter>user_compare_function</parameter></methodparam> </methodsynopsis> <para> + Sort a result from a <function>dbx_query</function> call with a custom sort + function. + </para> + </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>result</parameter></term> + <listitem> + <para> + A result set returned by <function>dbx_query</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_compare_function</parameter></term> + <listitem> + <para> + The user-defined comparison function. It must accept two arguments and + return an integer less than, equal to, or greater than zero if the + first argument is considered to be respectively less than, equal to, + or greater than the second. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> &return.success; </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"> + </refsect1> + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>dbx_sort</function> example</title> + <programlisting role="php"> <![CDATA[ <?php function user_re_order($a, $b) @@ -50,10 +80,26 @@ dbx_close($link); ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + It is always better to use <literal>ORDER BY</literal> + <literal>SQL</literal> clause instead of <function>dbx_sort</function> + if possible. + </para> + </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>dbx_compare</function>. + <simplelist> + <member><function>dbx_compare</function></member> + </simplelist> </para> </refsect1> </refentry>