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

Adding more see also information, description of

Browse source 
MYSQL_... constants, more cross references, using
&return.success; where applicable, more discussion
of mysql_query() return value, etc.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@62632 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Gabor Hojtsy 2001-11-17 12:59:11 +00:00
parent 3887a894e5
commit 7cc925a924
1 changed files with 103 additions and 71 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

174
functions/mysql.xml
View file

@ -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 @@ mysql_close($link);
<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 @@ mysql_close($link);
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 @@ mysql_close($link);
</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 @@ mysql_close($link);
<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 @@ mysql_close($link);
$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 @@ while ($i &lt; $cnt) {
</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 @@ while ($i &lt; $cnt) {
</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 @@ echo mysql_errno().": ".mysql_error()."&lt;BR>";
<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 @@ mysql_free_result ($result);
<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 @@ mysql_free_result ($result);
</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 @@ mysql_free_result ($result);
<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 @@ mysql_free_result ($result);
</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 @@ mysql_free_result ($result);
</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 @@ password
</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 @@ password
</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 @@ password
</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 @@ mysql_close();
</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 @@ mysql_close();
<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 @@ mysql_close();
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 @@ mysql_close();
<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 @@ mysql_close();
<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 @@ mysql_close();
<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 @@ database3
</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 @@ database3
<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 @@ field3
</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 @@ field3
<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 @@ field3
<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 @@ field3
<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 @@ echo "$num_rows Rows\n";
</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 @@ echo "$num_rows Rows\n";
<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 @@ echo "$num_rows Rows\n";
</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 @@ echo "$num_rows Rows\n";
<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 @@ echo "$num_rows Rows\n";
</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 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
<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 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
</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 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
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 @@ $result = mysql_query ("SELECT my_col FROM my_tbl")
</para>
<para>
For downward compatibility <function>mysql_selectdb</function>
can also be used.
can also be used. This is deprecated however.
</para>
</refsect1>
</refentry>