jeroen Wed May 16 08:25:31 2001 EDT
Modified files:
/phpdoc/en/functions mysql.xml
Log:
- Fixed types
- Removed outdated para
- Added some return description, and comments where still undocumented
Index: phpdoc/en/functions/mysql.xml
diff -u phpdoc/en/functions/mysql.xml:1.40 phpdoc/en/functions/mysql.xml:1.41
--- phpdoc/en/functions/mysql.xml:1.40 Tue May 15 05:18:59 2001
+++ phpdoc/en/functions/mysql.xml Wed May 16 08:25:31 2001
@@ -38,7 +38,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_affected_rows</function></funcdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -107,7 +107,7 @@
<optional>database</optional>
</parameter>
</paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -121,6 +121,9 @@
specified, this will default or current database after the user
has been changed. If the new user and password authorization fails,
the current connected user stays active.</para>
+
+ <!-- what is returned? bool -> succes/failure i suppose? -->
+
<note><para>This function was introduced in PHP 3.0.13 and
requires MySQL 3.23.3 or higher.
</para></note>
@@ -136,8 +139,8 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_close</function></funcdef>
- <paramdef>int
+ <funcdef>bool <function>mysql_close</function></funcdef>
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -155,7 +158,9 @@
<para>
Using <function>mysql_close</function> isn't usually necessary,
as non-persistent open links are automatically closed at the end
- of the script's execution.
+ of the script's execution. See also
+ <link linkend="language.types.resource.self-destruct">freeing
+ resources</link>.
</para>
<note>
<para>
@@ -190,7 +195,7 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_connect</function></funcdef>
+ <funcdef>resource <function>mysql_connect</function></funcdef>
<paramdef>string
<parameter>
<optional>hostname
@@ -212,8 +217,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns a positive MySQL link identifier on success, or an error
- message on failure.
+ Returns a MySQL link identifier on success, or FALSE on failure.
</para>
<para>
<function>mysql_connect</function> establishes a connection
@@ -283,7 +287,7 @@
<funcprototype>
<funcdef>int <function>mysql_create_db</function></funcdef>
<paramdef>string <parameter>database name</parameter></paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -295,6 +299,7 @@
database on the server associated with the specified link
identifier.
</para>
+ <!-- returns?? bool -> succes? -->
<example>
<title>MySQL create database example</title>
<programlisting role="php">
@@ -328,8 +333,8 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_data_seek</function></funcdef>
- <paramdef>int <parameter>result_identifier</parameter></paramdef>
+ <funcdef>bool <function>mysql_data_seek</function></funcdef>
+ <paramdef>resource <parameter>result_identifier</parameter></paramdef>
<paramdef>int <parameter>row_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -364,14 +369,14 @@
for ($i = mysql_num_rows ($result) - 1; $i >=0; $i--) {
if (!mysql_data_seek ($result, $i)) {
- printf ("Cannot seek to row %d\n", $i);
+ echo "Cannot seek to row $i\n";
continue;
}
if(!($row = mysql_fetch_object ($result)))
continue;
- printf ("%s %s<BR>\n", $row->last_name, $row->first_name);
+ echo ("$row->last_name $row->first_name<BR>\n";
}
mysql_free_result ($result);
@@ -390,8 +395,8 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_db_name</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <funcdef>string <function>mysql_db_name</function></funcdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row</parameter></paramdef>
<paramdef>mixed
<parameter>
@@ -451,10 +456,10 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_db_query</function></funcdef>
+ <funcdef>resource <function>mysql_db_query</function></funcdef>
<paramdef>string <parameter>database</parameter></paramdef>
<paramdef>string <parameter>query</parameter></paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -462,7 +467,7 @@
</funcprototype>
</funcsynopsis>
<para>
- Returns: A positive MySQL result identifier to the query result,
+ Returns: A positive MySQL result resource to the query result,
or false on error.
</para>
<para>
@@ -474,8 +479,7 @@
arguments
</para>
<para>
- See also <function>mysql_connect</function> and
- <function>mysql_query</function>.
+ See also <function>mysql_connect</function>.
</para>
<para>
For downwards
@@ -493,9 +497,9 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_drop_db</function></funcdef>
+ <funcdef>bool <function>mysql_drop_db</function></funcdef>
<paramdef>string <parameter>database_name</parameter></paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -528,7 +532,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_errno</function></funcdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -578,7 +582,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>string <function>mysql_error</function></funcdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -628,7 +632,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>array <function>mysql_fetch_array</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int
<parameter>
<optional>result_type</optional>
@@ -703,7 +707,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>array <function>mysql_fetch_assoc</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -762,7 +766,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>object <function>mysql_fetch_field</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int
<parameter>
<optional>field_offset</optional>
@@ -898,7 +902,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>array <function>mysql_fetch_lengths</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -930,7 +934,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>object <function>mysql_fetch_object</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int
<parameter>
<optional>result_type</optional>
@@ -991,7 +995,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>array <function>mysql_fetch_row</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -1031,7 +1035,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>string <function>mysql_field_flags</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_offset</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1065,7 +1069,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>string <function>mysql_field_name</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_index</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1128,7 +1132,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_field_len</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_offset</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1155,7 +1159,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_field_seek</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_offset</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1183,7 +1187,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>string <function>mysql_field_table</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_offset</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1210,7 +1214,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>string <function>mysql_field_type</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>iresource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_offset</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -1266,7 +1270,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_free_result</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -1278,7 +1282,9 @@
you are concerned about how much memory is being used for queries
that return large result sets. All associated result memory is
automatically freed at the end of the script's execution.
+ <!-- TODO and as of PHP4 before, see freeing resources -->
</para>
+ <!-- returns?? -->
<para>
For downward compatibility <function>mysql_freeresult</function>
can also be used.
@@ -1298,7 +1304,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_insert_id</function></funcdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -1352,8 +1358,8 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_list_dbs</function></funcdef>
- <paramdef>int
+ <funcdef>resource <function>mysql_list_dbs</function></funcdef>
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -1400,6 +1406,7 @@
For downward compatibility <function>mysql_listdbs</function> can
also be used.
</para>
+ <para>See also <function>mysql_db_name</function></para>
</refsect1>
</refentry>
@@ -1412,10 +1419,10 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_list_fields</function></funcdef>
+ <funcdef>resource <function>mysql_list_fields</function></funcdef>
<paramdef>string <parameter>database_name</parameter></paramdef>
<paramdef>string <parameter>table_name</parameter></paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -1431,13 +1438,15 @@
<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
+ 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> -->
<para>
<example>
<title><function>mysql_list_fields</function> example</title>
@@ -1468,6 +1477,10 @@
For downward compatibility <function>mysql_listfields</function>
can also be used.
</para>
+ <!-- TODO: this is equiv. with 'select * from $table where FALSE,'
+ which implies you can better use the field-research functions
+ on a real query, that saves you one mysql-query.
+ -->
</refsect1>
</refentry>
@@ -1480,9 +1493,9 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_list_tables</function></funcdef>
+ <funcdef>resource <function>mysql_list_tables</function></funcdef>
<paramdef>string <parameter>database</parameter></paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -1513,7 +1526,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_num_fields</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -1543,7 +1556,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>int <function>mysql_num_rows</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -1593,7 +1606,7 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_pconnect</function></funcdef>
+ <funcdef>resource <function>mysql_pconnect</function></funcdef>
<paramdef>string
<parameter>
<optional>hostname
@@ -1636,6 +1649,8 @@
</para>
</note>
</para>
+
+ <!-- TODO move the story to features.persistent, and refer to that -->
<para>
<function>mysql_pconnect</function> acts very much like
<function>mysql_connect</function> with two major differences.
@@ -1667,9 +1682,9 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_query</function></funcdef>
+ <funcdef>resource <function>mysql_query</function></funcdef>
<paramdef>string <parameter>query</parameter></paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter><optional>link_identifier</optional></parameter>
</paramdef>
</funcprototype>
@@ -1749,7 +1764,6 @@
<para>
See also: <function>mysql_affected_rows</function>,
<function>mysql_db_query</function>,
- <function>mysql_unbuffered_query</function>,
<function>mysql_free_result</function>,
<function>mysql_result</function>,
<function>mysql_select_db</function>, and
@@ -1758,50 +1772,6 @@
</refsect1>
</refentry>
- <refentry id="function.mysql-unbuffered-query">
- <refnamediv>
- <refname>mysql_unbuffered_query</refname>
- <refpurpose>Send an SQL query to MySQL, without fetching and buffering the result
rows</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>mysql_unbuffered_query</function></funcdef>
- <paramdef>string <parameter>query</parameter></paramdef>
- <paramdef>int
- <parameter><optional>link_identifier</optional></parameter>
- </paramdef>
- <paramdef>int
- <parameter><optional>result_mode</optional></parameter>
- </paramdef>
- </funcprototype>
- </funcsynopsis>
- <para>
- <function>mysql_unbuffered_query</function> sends a SQL query to MySQL,
- without fetching and buffering the result rows automatically, as
- <function>mysql_query</function> does.
- On the one hand, this saves a considerable amount of memory with SQL
- queries that produce large result sets. On the other hand, you can start
- working on the result set immediately after the first row has been
- retrieved: you don't have to wait until the complete SQL query has been
- performed.
- </para>
- <note>
- <para>
- The benefits of <function>mysql_unbuffered_query</function> come at a
- cost: You cannot use <function>mysql_num_rows</function> on a result set
- returned from <function>mysql_unbuffered_query</function>. You also have
- to fetch all result rows from an unbuffered SQL query, before you can
- send a new SQL query to MySQL.
- </para>
- </note>
- <para>
- See also: <function>mysql_query</function>.
- </para>
- </refsect1>
- </refentry>
-
<refentry id="function.mysql-result">
<refnamediv>
<refname>mysql_result</refname>
@@ -1812,7 +1782,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>mysql_result</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row</parameter></paramdef>
<paramdef>mixed
<parameter>
@@ -1860,9 +1830,9 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>mysql_select_db</function></funcdef>
+ <funcdef>bool <function>mysql_select_db</function></funcdef>
<paramdef>string <parameter>database_name</parameter></paramdef>
- <paramdef>int
+ <paramdef>resource
<parameter>
<optional>link_identifier</optional>
</parameter>
@@ -1906,7 +1876,7 @@
<funcsynopsis>
<funcprototype>
<funcdef>string <function>mysql_tablename</function></funcdef>
- <paramdef>int <parameter>result</parameter></paramdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>i</parameter></paramdef>
</funcprototype>
</funcsynopsis>
