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

WS, preparing for the new doc style

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@226706 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Mehdi Achour 2007-01-08 01:02:31 +00:00
parent eb1adb553b
commit 9294ef5829
8 changed files with 644 additions and 650 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

61
reference/dbx/functions/dbx-close.xml
View file

@ -1,23 +1,22 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
<refentry id="function.dbx-close">
<refnamediv>
<refname>dbx_close</refname>
<refpurpose>Close an open connection/database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>dbx_close</methodname>
<methodparam><type>object</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
&return.success;
</para>
<example>
<title><function>dbx_close</function> example</title>
<programlisting role="php">
<!-- $Revision: 1.7 $ -->
<refentry id="function.dbx-close">
<refnamediv>
<refname>dbx_close</refname>
<refpurpose>Close an open connection/database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>dbx_close</methodname>
<methodparam><type>object</type><parameter>link_identifier</parameter></methodparam>
</methodsynopsis>
<para>
&return.success;
</para>
<example>
<title><function>dbx_close</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
@ -27,18 +26,18 @@ echo "Connected successfully";
dbx_close($link);
?>
]]>
</programlisting>
</example>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
</note>
<para>
See also <function>dbx_connect</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
</note>
<para>
See also <function>dbx_connect</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

149
reference/dbx/functions/dbx-compare.xml
View file

@ -1,72 +1,71 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
<refentry id="function.dbx-compare">
<refnamediv>
<refname>dbx_compare</refname>
<refpurpose>Compare two rows for sorting purposes</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<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>column_key</parameter></methodparam>
<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>
<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>
<example>
<title><function>dbx_compare</function> example</title>
<programlisting role="php">
<!-- $Revision: 1.5 $ -->
<refentry id="function.dbx-compare">
<refnamediv>
<refname>dbx_compare</refname>
<refpurpose>Compare two rows for sorting purposes</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<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>column_key</parameter></methodparam>
<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>
<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>
<example>
<title><function>dbx_compare</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
function user_re_order($a, $b)
@ -90,13 +89,13 @@ dbx_sort($result, "user_re_order");
dbx_close($link);
?>
]]>
</programlisting>
</example>
<para>
See also <function>dbx_sort</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<para>
See also <function>dbx_sort</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

277
reference/dbx/functions/dbx-connect.xml
View file

@ -1,138 +1,137 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
<refentry id="function.dbx-connect">
<refnamediv>
<refname>dbx_connect</refname>
<refpurpose>Open a connection/database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<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>
<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>
<para>
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">
<!-- $Revision: 1.12 $ -->
<refentry id="function.dbx-connect">
<refnamediv>
<refname>dbx_connect</refname>
<refpurpose>Open a connection/database</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<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>
<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>
<para>
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(DBX_MYSQL, "localhost", "db", "username", "password");
mysql_close($link->handle); // dbx_close($link) would be better here
?>
]]>
</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>
<title><function>dbx_connect</function> example</title>
<programlisting role="php">
</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>
<title><function>dbx_connect</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect(DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT)
@ -142,19 +141,19 @@ echo "Connected successfully";
dbx_close($link);
?>
]]>
</programlisting>
</example>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
</note>
</para>
</programlisting>
</example>
<note>
<para>
See also <function>dbx_close</function>.
Always refer to the module-specific documentation as well.
</para>
</refsect1>
</refentry>
</note>
</para>
<para>
See also <function>dbx_close</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

85
reference/dbx/functions/dbx-error.xml
View file

@ -1,31 +1,30 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
<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)
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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">
<!-- $Revision: 1.5 $ -->
<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)
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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">
<![CDATA[
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
@ -38,22 +37,22 @@ if ($result == 0) {
dbx_close($link);
?>
]]>
</programlisting>
</example>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
<para>
The error message for Microsoft SQL Server is actually the result
of the <function>mssql_get_last_message</function> function.
</para>
<para>
The error message for Oracle (oci8) is not implemented (yet).
</para>
</note>
</refsect1>
</refentry>
</programlisting>
</example>
<note>
<para>
Always refer to the module-specific documentation as well.
</para>
<para>
The error message for Microsoft SQL Server is actually the result
of the <function>mssql_get_last_message</function> function.
</para>
<para>
The error message for Oracle (oci8) is not implemented (yet).
</para>
</note>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

60
reference/dbx/functions/dbx-escape-string.xml
View file

@ -1,27 +1,27 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<refentry id="function.dbx-escape-string">
<refnamediv>
<refname>dbx_escape_string</refname>
<refpurpose>
Escape a string so it can safely be used in an sql-statement
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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">
<!-- $Revision: 1.7 $ -->
<refentry id="function.dbx-escape-string">
<refnamediv>
<refname>dbx_escape_string</refname>
<refpurpose>
Escape a string so it can safely be used in an sql-statement
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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">
<![CDATA[
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
@ -35,13 +35,13 @@ if ($result == 0) {
dbx_close($link);
?>
]]>
</programlisting>
</example>
<para>
See also <function>dbx_query</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<para>
See also <function>dbx_query</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

90
reference/dbx/functions/dbx-fetch-row.xml
View file

@ -1,32 +1,32 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<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>
<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).
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>
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>
<programlisting role="php">
<!-- $Revision: 1.6 $ -->
<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>
<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).
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>
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>
<programlisting role="php">
<![CDATA[
<?php
$result = dbx_query($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);
@ -42,23 +42,23 @@ while ($row = dbx_fetch_row($result)) {
echo "</table>\n";
?>
]]>
</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.
</para>
<para>
See also <function>dbx_query</function>.
</para>
</refsect1>
</refentry>
</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.
</para>
<para>
See also <function>dbx_query</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

501
reference/dbx/functions/dbx-query.xml
View file

@ -1,29 +1,28 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.18 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
<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>
<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">
<!-- $Revision: 1.19 $ -->
<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>
<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")
@ -42,173 +41,173 @@ if (is_object($result) ) {
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;.
<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>
<para>
The returned <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>
<programlisting role="php">
</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;.
<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>
<para>
The returned <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>
<programlisting role="php">
<![CDATA[
<?php
$result = dbx_query($link, "SELECT id FROM table");
mysql_field_len($result->handle, 0);
?>
]]>
</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">
</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[
<?php
$result = dbx_query($link, 'SELECT id FROM table');
@ -216,26 +215,26 @@ echo $result->rows; // number of records
echo $result->cols; // number of fields
?>
]]>
</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">
</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[
<?php
$result = dbx_query($link, 'SELECT id FROM table',
@ -247,24 +246,24 @@ for ($i = 0; $i < $result->cols; $i++ ) {
}
?>
]]>
</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">
</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
$result = dbx_query($link, 'SELECT id, parentid, description FROM table');
@ -280,11 +279,11 @@ foreach ($result->data as $row) {
echo "</table>\n";
?>
]]>
</programlisting>
</example>
<example>
<title>How to handle UNBUFFERED queries</title>
<programlisting role="php">
</programlisting>
</example>
<example>
<title>How to handle UNBUFFERED queries</title>
<programlisting role="php">
<![CDATA[
<?php
@ -302,28 +301,28 @@ echo "</table>\n";
?>
]]>
</programlisting>
</example>
</listitem>
</varlistentry>
</variablelist>
</para>
<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.
</para>
</note>
<para>
See also <function>dbx_escape_string</function>,
<function>dbx_fetch_row</function> and
<function>dbx_connect</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
</listitem>
</varlistentry>
</variablelist>
</para>
<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.
</para>
</note>
<para>
See also <function>dbx_escape_string</function>,
<function>dbx_fetch_row</function> and
<function>dbx_connect</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:

71
reference/dbx/functions/dbx-sort.xml
View file

@ -1,33 +1,32 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
<refentry id="function.dbx-sort">
<refnamediv>
<refname>dbx_sort</refname>
<refpurpose>
Sort a result from a dbx_query by a custom sort function
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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>
&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">
<!-- $Revision: 1.6 $ -->
<refentry id="function.dbx-sort">
<refnamediv>
<refname>dbx_sort</refname>
<refpurpose>
Sort a result from a dbx_query by a custom sort function
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<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>
&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">
<![CDATA[
<?php
function user_re_order($a, $b)
@ -51,13 +50,13 @@ dbx_sort($result, "user_re_order");
dbx_close($link);
?>
]]>
</programlisting>
</example>
<para>
See also <function>dbx_compare</function>.
</para>
</refsect1>
</refentry>
</programlisting>
</example>
<para>
See also <function>dbx_compare</function>.
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables: