goba Sat Nov 17 07:59:12 2001 EDT
Modified files:
/phpdoc/en/functions mysql.xml
Log:
Adding more see also information, description of
MYSQL_... constants, more cross references, using
&return.success; where applicable, more discussion
of mysql_query() return value, etc.
Index: phpdoc/en/functions/mysql.xml
diff -u phpdoc/en/functions/mysql.xml:1.72 phpdoc/en/functions/mysql.xml:1.73
--- phpdoc/en/functions/mysql.xml:1.72 Sat Nov 17 06:43:14 2001
+++ phpdoc/en/functions/mysql.xml Sat Nov 17 07:59:11 2001
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.72 $ -->
+<!-- $Revision: 1.73 $ -->
<reference id="ref.mysql">
<title>MySQL Functions</title>
<titleabbrev>MySQL</titleabbrev>
@@ -324,7 +324,7 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_create_db</function></funcdef>
+ <funcdef>bool <function>mysql_create_db</function></funcdef>
<paramdef>string <parameter>database name</parameter></paramdef>
<paramdef>resource
<parameter>
@@ -338,7 +338,9 @@
database on the server associated with the specified link
identifier.
</para>
- <!-- returns?? bool -> succes? -->
+ <para>
+ &return.success;
+ </para>
<example>
<title>MySQL create database example</title>
<programlisting role="php">
@@ -355,7 +357,7 @@
</example>
<para>
For downwards compatibility <function>mysql_createdb</function>
- can also be used.
+ can also be used. This is deprecated, however.
</para>
<para>
See also: <function>mysql_drop_db</function>.
@@ -377,8 +379,8 @@
<paramdef>int <parameter>row_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
- <para>
- Returns: &true; on success, &false; on failure.
+ <para>
+ &return.success;
</para>
<para>
<function>mysql_data_seek</function> moves the internal row
@@ -403,7 +405,7 @@
$result = mysql_query ($query)
or die ("Query failed");
- # fetch rows in reverse order
+ // fetch rows in reverse order
for ($i = mysql_num_rows ($result) - 1; $i >=0; $i--) {
if (!mysql_data_seek ($result, $i)) {
@@ -501,7 +503,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns: A positive MySQL result resource to the query result,
+ Returns a positive MySQL result resource to the query result,
or &false; on error.
</para>
<para>
@@ -547,16 +549,19 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns: &true; on success, &false; on failure.
+ &return.succes;
</para>
<para>
<function>mysql_drop_db</function> attempts to drop (remove) an
entire database from the server associated with the specified
link identifier.
</para>
+ <para>
+ For downward compatibility <function>mysql_dropdb</function>
+ can also be used. This is deprecated, however.
+ </para>
<para>
- See also: <function>mysql_create_db</function>. For downward
- compatibility <function>mysql_dropdb</function> can also be used.
+ See also: <function>mysql_create_db</function>.
</para>
</refsect1>
</refentry>
@@ -724,25 +729,36 @@
<para>
If two or more columns of the result have the same field names,
the last column will take precedence. To access the other column(s)
- of the same name, you must the numeric index of the column or
- make an alias for the column.
+ of the same name, you must use the numeric index of the column or
+ make an alias for the column. For aliased columns, you cannot
+ access the contents with the original column name (by using
+ <literal>'field'<literal> in this example).
<informalexample>
<programlisting>
-select t1.f1 as foo t2.f1 as bar from t1, t2
+select tone.field as foo ttwo.field as bar from tone, ttwo
</programlisting>
</informalexample>
</para>
<para>
An important thing to note is that using
- <function>mysql_fetch_array</function> is NOT significantly
- slower than using <function>mysql_fetch_row</function>, while it
- provides a significant added value.
+ <function>mysql_fetch_array</function> is <emphasis>not
+ significantly</emphasis> slower than using
+ <function>mysql_fetch_row</function>, while it provides
+ a significant added value.
</para>
<para>
The optional second argument <parameter>result_type</parameter>
in <function>mysql_fetch_array</function> is a constant and can
take the following values: MYSQL_ASSOC, MYSQL_NUM, and
- MYSQL_BOTH. (This feature was added in PHP 3.0.7)
+ MYSQL_BOTH. This feature was added in PHP 3.0.7. MYSQL_BOTH
+ is the default for this argument.
+ </para>
+ <para>
+ By using MYSQL_BOTH, you'll get an array with both associative
+ and number indices. Using MYSQL_ASSOC, you only get associative
+ indices (as <function>mysql_fetch_assoc</function> works),
+ using MYSQL_NUM, you only get number indices (as
+ <function>mysql_fetch_row</function> works).
</para>
<para>
For further details, see also
@@ -797,14 +813,17 @@
<para>
If two or more columns of the result have the same field names,
the last column will take precedence. To access the other
- column(s) of the same name, you must use
- <function>mysql_fetch_array</function> and have it return the
- numeric indices as well.
+ column(s) of the same name, you either need to access the
+ result with numeric indices by using
+ <function>mysql_fetch_row<function> or add alias names.
+ See the example at the <function>mysql_fetch_array</function>
+ description about aliases.
</para>
<para>
An important thing to note is that using
- <function>mysql_fetch_assoc</function> is NOT significantly
- slower than using <function>mysql_fetch_row</function>, while it
+ <function>mysql_fetch_assoc</function> is <emphasis>not
+ significantly</emphasis> slower than using
+ <function>mysql_fetch_row</function>, while it
provides a significant added value.
</para>
<para>
@@ -981,7 +1000,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns: An array that corresponds to the lengths of each field
+ Returns an array that corresponds to the lengths of each field
in the last row fetched by <function>mysql_fetch_row</function>,
or &false; on error.
</para>
@@ -1031,7 +1050,9 @@
<para>
The optional argument <parameter>result_type</parameter> is a
constant and can take the following values: MYSQL_ASSOC,
- MYSQL_NUM, and MYSQL_BOTH.
+ MYSQL_NUM, and MYSQL_BOTH. See
+ <function>mysql_fetch_array</function> for explanation
+ of these constants.
</para>
<para>
Speed-wise, the function is identical to
@@ -1074,7 +1095,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns: An array that corresponds to the fetched row, or &false;
+ Returns an array that corresponds to the fetched row, or &false;
if there are no more rows.
</para>
<para>
@@ -1127,7 +1148,7 @@
</para>
<para>
For downward compatibility <function>mysql_fieldflags</function>
- can also be used.
+ can also be used. This is deprecated, however.
</para>
</refsect1>
</refentry>
@@ -1190,7 +1211,7 @@
</para>
<para>
For downwards compatibility <function>mysql_fieldname</function>
- can also be used.
+ can also be used. This is deprecated, however.
</para>
</refsect1>
</refentry>
@@ -1217,7 +1238,7 @@
</para>
<para>
For downward compatibility <function>mysql_fieldlen</function>
- can also be used.
+ can also be used. This is deprecated, however.
</para>
</refsect1>
</refentry>
@@ -1272,7 +1293,7 @@
</para>
<para>
For downward compatibility <function>mysql_fieldtable</function>
- can also be used.
+ can also be used. This is deprecated, however.
</para>
</refsect1>
</refentry>
@@ -1330,7 +1351,7 @@
</para>
<para>
For downward compatibility <function>mysql_fieldtype</function>
- can also be used.
+ can also be used. This is deprecated, however.
</para>
</refsect1>
</refentry>
@@ -1344,7 +1365,7 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_free_result</function></funcdef>
+ <funcdef>bool <function>mysql_free_result</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1359,10 +1380,12 @@
automatically freed at the end of the script's execution.
<!-- TODO and as of PHP4 before, see freeing resources -->
</para>
- <!-- returns?? -->
+ <para>
+ &returns.success;
+ </para>
<para>
For downward compatibility <function>mysql_freeresult</function>
- can also be used.
+ can also be used. This is deprecated, however.
</para>
</refsect1>
</refentry>
@@ -1396,8 +1419,9 @@
<para>
<function>mysql_insert_id</function> returns 0 if the previous
query does not generate an AUTO_INCREMENT value. If you need to
- save the value for later, be sure to call mysql_insert_id()
- immediately after the query that generates the value.
+ save the value for later, be sure to call
+ <function>mysql_insert_id</function> immediately after the
+ query that generates the value.
</para>
<note>
<para>
@@ -1412,11 +1436,11 @@
<function>mysql_insert_id</function> converts the return type of
the native MySQL C API function
<literal>mysql_insert_id()</literal> to a type of
- <literal>long</literal>. If your AUTO_INCREMENT column has
- a column type of BIGINT, the value returned by
- <function>mysql_insert_id</function> will be incorrect.
- Instead, use the internal MySQL SQL function
- <literal>LAST_INSERT_ID()</literal>.
+ <literal>long</literal> (named <type>int</type> in PHP).
+ If your AUTO_INCREMENT column has a column type of BIGINT,
+ the value returned by <function>mysql_insert_id</function>
+ will be incorrect. Instead, use the internal MySQL SQL function
+ <literal>LAST_INSERT_ID()</literal> in an SQL query.
</para>
</warning>
</refsect1>
@@ -1445,7 +1469,7 @@
<function>mysql_list_dbs</function> will return a result pointer
containing the databases available from the current mysql
daemon. Use the <function>mysql_tablename</function> function to
- traverse this result pointer.
+ traverse this result pointer, or any function for result tables.
</para>
<para>
<example>
@@ -1479,7 +1503,7 @@
</note>
<para>
For downward compatibility <function>mysql_listdbs</function> can
- also be used.
+ also be used. This is deprecated however.
</para>
<para>
See also <function>mysql_db_name</function>.
@@ -1515,15 +1539,6 @@
<function>mysql_field_name</function>, and
<function>mysql_field_type</function>.
</para>
- <!--
- this is very outdated, and now incorrect
- <para>
- A result identifier is a positive integer. The function returns
- -1 if a error occurs. A string describing the error will be
- placed in <literal>$phperrmsg</literal>, and unless the function
- was called as <literal>@mysql()</literal> then this error string
- will also be printed out.
- </para> -->
<para>
<example>
<title><function>mysql_list_fields</function> example</title>
@@ -1552,7 +1567,7 @@
</para>
<para>
For downward compatibility <function>mysql_listfields</function>
- can also be used.
+ can also be used. This is deprecated however.
</para>
<!-- TODO: this is equiv. with 'select * from $table where &false;,'
which implies you can better use the field-research functions
@@ -1582,13 +1597,14 @@
<para>
<function>mysql_list_tables</function> takes a database name and
returns a result pointer much like the
- <function>mysql_db_query</function> function. The
- <function>mysql_tablename</function> function should be used to
- extract the actual table names from the result pointer.
+ <function>mysql_db_query</function> function. You can use the
+ <function>mysql_tablename</function> function to extract the
+ actual table names from the result pointer, or any other result
+ table function.
</para>
<para>
For downward compatibility <function>mysql_listtables</function>
- can also be used.
+ can also be used. This is deprecated however.
</para>
</refsect1>
</refentry>
@@ -1618,7 +1634,7 @@
<function>mysql_num_rows</function>.</para>
<para>
For downward compatibility <function>mysql_numfields</function>
- can also be used.
+ can also be used. This is deprecated however.
</para>
</refsect1>
</refentry>
@@ -1639,7 +1655,7 @@
<para>
<function>mysql_num_rows</function> returns the number of rows in
a result set. This command is only valid for SELECT statements.
- To retrieve the number of rows returned from a INSERT, UPDATE or
+ To retrieve the number of rows affected by a INSERT, UPDATE or
DELETE query, use <function>mysql_affected_rows</function>.
<example>
<title><function>mysql_num_rows</function> example</title>
@@ -1667,7 +1683,7 @@
</para>
<para>
For downward compatibility <function>mysql_numrows</function> can
- also be used.
+ also be used. This is deprecated however.
</para>
</refsect1>
</refentry>
@@ -1676,7 +1692,7 @@
<refnamediv>
<refname>mysql_pconnect</refname>
<refpurpose>
- Open a persistent connection to a MySQL Server
+ Open a persistent connection to a MySQL server
</refpurpose>
</refnamediv>
<refsect1>
@@ -1698,7 +1714,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns: A positive MySQL persistent link identifier on success,
+ Returns a positive MySQL persistent link identifier on success,
or &false; on error.
</para>
<para>
@@ -1744,6 +1760,14 @@
<para>
This type of links is therefore called 'persistent'.
</para>
+ <note>
+ <para>
+ Note, that these kind of links only work if you are using
+ a module version of PHP. See the
+ <link linkend="features.persistent-connections">Persistent
+ Database Connections</link> section for more information.
+ </para>
+ </note>
</refsect1>
</refentry>
@@ -1778,9 +1802,12 @@
</para>
</note>
<para>
- <function>mysql_query</function> returns &true; (non-zero) or &false;
- to indicate whether or not the query succeeded. A return value
- of &true; means that the query was legal and could be executed by
+ Only for SELECT statements <function>mysql_query</function>
+ returns a resource identifier or &false; if the query was
+ not executed correctly. For other type of SQL statements,
+ <function>mysql_query</function> returns &true; on success
+ and &false; on error. A non-&false; return value
+ means that the query was legal and could be executed by
the server. It does not indicate anything about the number of
rows affected or returned. It is perfectly possible for a query
to succeed but affect no rows or return no rows.
@@ -1829,17 +1856,22 @@
<para>
Only for SELECT statements, <function>mysql_query</function>
returns a new result identifier that you can pass to
- <function>mysql_result</function>. When you are done with the
+ <function>mysql_fetch_array</function> and other
+ functions dealing with result tables. When you are done with the
result set, you can free the resources associated with it by
- calling <function>mysql_free_result</function>. Although, the
+ calling <function>mysql_free_result</function>. Although, the
memory will automatically be freed at the end of the script's
execution.
</para>
<para>
- See also: <function>mysql_affected_rows</function>,
+ See also: <function>mysql_num_rows</function>
+ <function>mysql_affected_rows</function>,
<function>mysql_db_query</function>,
<function>mysql_unbuffered_query</function>,
<function>mysql_free_result</function>,
+ <function>mysql_fetch_array</function>,
+ <function>mysql_fetch_row</function>,
+ <function>mysql_fetch_assoc</function>,
<function>mysql_result</function>,
<function>mysql_select_db</function>, and
<function>mysql_connect</function>.
@@ -1963,7 +1995,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns: &true; on success, &false; on error.
+ &return.success;
</para>
<para>
<function>mysql_select_db</function> sets the current active
@@ -1971,7 +2003,7 @@
identifier. If no link identifier is specified, the last opened
link is assumed. If no link is open, the function will try to
establish a link as if <function>mysql_connect</function> was
- called, and use it.
+ called without arguments, and use it.
</para>
<para>
Every subsequent call to <function>mysql_query</function> will be
@@ -1984,7 +2016,7 @@
</para>
<para>
For downward compatibility <function>mysql_selectdb</function>
- can also be used.
+ can also be used. This is deprecated however.
</para>
</refsect1>
</refentry>
