cvs: phpdoc /en/functions mysql.xml
| From: | Hojtsy Gabor | Date: | Thu, 30 Aug 2001 16:51:12 +0000 |
| Subject: | cvs: phpdoc /en/functions mysql.xml | ||
| Groups: | php.doc | ||
| Request: | Send a blank email to phpdoc+get-969337344@lists.php.net to get a copy of this message | ||
goba Thu Aug 30 12:51:12 2001 EDT
Modified files:
/phpdoc/en/functions mysql.xml
Log:
Readding mysql.xml, the english version
Index: phpdoc/en/functions/mysql.xml diff -u /dev/null phpdoc/en/functions/mysql.xml:1.62 --- /dev/null Thu Aug 30 12:51:12 2001 +++ phpdoc/en/functions/mysql.xml Thu Aug 30 12:51:12 2001 @@ -0,0 +1,2138 @@ +<?xml encoding="iso-8859-1"?> +<!-- $Revision: 1.62 $ --> + <reference id="ref.mysql"> + <title>MySQL functions</title> + <titleabbrev>MySQL</titleabbrev> + <partintro> + <simpara> + These functions allow you to access MySQL database servers. In + order to have these functions available, you must compile php + with MySQL support by using the + <option role="configure">--with-mysql</option> option. If you + use this option without specifying the path to MySQL, php will + use the built-in MySQL client libraries. Users who run other + applications that use MySQL (for example, running php3 and php4 + as concurrent apache modules, or auth-mysql) should always + specify the path to MySQL: + <option role="configure">--with-mysql=/path/to/mysql</option>. + This will force php to use the client libraries installed by + MySQL, avoiding any conflicts. + </simpara> + <simpara> + More information about MySQL can be found at <ulink + url="&url.mysql;">&url.mysql;</ulink>. + </simpara> + <simpara> + Documentation for MySQL can be found at <ulink + url="&url.mysql.docs;">&url.mysql.docs;</ulink>. + </simpara> + <para> + This simple example shows how to connect, execute a query, print + resulting rows and disconnect from MySQL Database. + <example> + <title>MySQL extension overview example</title> + <programlisting role="php"> +<?php + $link = mysql_connect("mysql_host", "mysql_login", "mysql_password") + or die ("Could not connect"); + print ("Connected successfully"); + mysql_select_db ("my_database") + or die ("Could not select database"); + + $query = "SELECT * FROM my_table"; + $result = mysql_query ($query) + or die ("Query failed"); + + // printing HTML result + + print "<table>\n"; + while($line = mysql_fetch_array($result)){ + print "\t<tr>\n"; + while(list($col_name, $col_value) = each($line)){ + print "\t\t<td>$col_value</td>\n"; + } + print "\t</tr>\n"; + } + print "</table>\n"; + + mysql_close($link); +?> + </programlisting> + </example> + </para> + </partintro> + + <refentry id="function.mysql-affected-rows"> + <refnamediv> + <refname>mysql_affected_rows</refname> + <refpurpose>Get number of affected rows in previous MySQL + operation</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_affected_rows</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_affected_rows</function> returns the number + of rows affected by the last INSERT, UPDATE or DELETE query + associated with <parameter>link_identifier</parameter>. If the + link identifier isn't specified, the last link opened by + <function>mysql_connect</function> is assumed. + </para> + <note> + <para> + If you are using transactions, you need to call + <function>mysql_affected_rows</function> after your INSERT, + UPDATE, or DELETE query, not after the commit. + </para> + </note> + <para> + If the last query was a DELETE query with no WHERE clause, all + of the records will have been deleted from the table but this + function will return zero. + </para> + <note> + <para> + When using UPDATE, MySQL will not update columns where the new + value is the same as the old value. This creates the possiblity + that <function>mysql_affected_rows</function> may not actually + equal the number of rows matched, only the number of rows that + were literally affected by the query. + </para> + </note> + <para> + <function>mysql_affected_rows</function> does not work with + SELECT statements; only on statements which modify records. To + retrieve the number of rows returned by a SELECT, use + <function>mysql_num_rows</function>. + </para> + <para> + If the last query failed, this function will return -1. + </para> + <para> + See also: <function>mysql_num_rows</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-change-user"> + <refnamediv> + <refname>mysql_change_user</refname> + <refpurpose> + Change logged in user of the active connection + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_change_user</function></funcdef> + <paramdef>string <parameter>user</parameter></paramdef> + <paramdef>string <parameter>password</parameter></paramdef> + <paramdef>string + <parameter> + <optional>database</optional> + </parameter> + </paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_change_user</function> changes the logged in user + of the current active connection, or the connection given by the + optional parameter link_identifier. If a database is + 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> + </refsect1> + </refentry> + + <refentry id="function.mysql-close"> + <refnamediv> + <refname>mysql_close</refname> + <refpurpose>Close MySQL connection</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_close</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on error. + </para> + <para> <function>mysql_close</function> closes the connection to + the MySQL server that's associated with the specified link + identifier. If <parameter>link_identifier</parameter> isn't + specified, the last opened link is used. + </para> + <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. See also + <link linkend="language.types.resource.self-destruct">freeing + resources</link>. + </para> + <note> + <para> + <function>mysql_close</function> will not close persistent links + created by <function>mysql_pconnect</function>. + </para> + </note> + <example> + <title>MySQL close example</title> + <programlisting role="php"> +<?php + $link = mysql_connect ("kraemer", "marliesle", "secret") + or die ("Could not connect"); + print ("Connected successfully"); + mysql_close ($link); +?> + </programlisting> + </example> + <para> + See also: <function>mysql_connect</function>, and + <function>mysql_pconnect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-connect"> + <refnamediv> + <refname>mysql_connect</refname> + <refpurpose>Open a connection to a MySQL Server</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_connect</function></funcdef> + <paramdef>string + <parameter> + <optional>hostname + <optional>:port</optional> + <optional>:/path/to/socket</optional> + </optional> + </parameter> + </paramdef> + <paramdef>string + <parameter> + <optional>username</optional> + </parameter> + </paramdef> + <paramdef>string + <parameter> + <optional>password</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns a MySQL link identifier on success, or &false; on failure. + </para> + <para> + <function>mysql_connect</function> establishes a connection + to a MySQL server. The following defaults are assumed for + missing optional parameters: <parameter>host:port</parameter> = + 'localhost:3306', <parameter>username</parameter> = name of the + user that owns the server process and + <parameter>password</parameter> = empty password. + </para> + <para> + The hostname string can also include a port + number. eg. "hostname:port" or a path to a socket + eg. ":/path/to/socket" for the localhost. + <note> + <para> + Support for ":port" was added in PHP 3.0B4. + </para> + <para> + Support for ":/path/to/socket" was added in + PHP 3.0.10. + </para> + <para> + You can suppress the error message on failure by prepending '@' + to the function name. + </para> + </note> + </para> + <para> + If a second call is made to <function>mysql_connect</function> + with the same arguments, no new link will be established, but + instead, the link identifier of the already opened link will be + returned. + </para> + <para> + The link to the server will be closed as soon as the execution of + the script ends, unless it's closed earlier by explicitly calling + <function>mysql_close</function>. + </para> + <example> + <title>MySQL connect example</title> + <programlisting role="php"> +<?php + + $link = mysql_connect ("localhost", "username", "secret") + or die ("Could not connect"); + print ("Connected successfully"); + mysql_close ($link); + +?> + </programlisting> + </example> + <para> See also + <function>mysql_pconnect</function>, and + <function>mysql_close</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-create-db"> + <refnamediv> + <refname>mysql_create_db</refname> + <refpurpose>Create a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_create_db</function></funcdef> + <paramdef>string <parameter>database name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_create_db</function> attempts to create a new + database on the server associated with the specified link + identifier. + </para> + <!-- returns?? bool -> succes? --> + <example> + <title>MySQL create database example</title> + <programlisting role="php"> +<?php + $link = mysql_pconnect ("kron", "jutta", "geheim") + or die ("Could not connect"); + if (mysql_create_db ("my_db")) { + print ("Database created successfully\n"); + } else { + printf ("Error creating database: %s\n", mysql_error ()); + } +?> + </programlisting> + </example> + <para> + For downwards compatibility <function>mysql_createdb</function> + can also be used. + </para> + <para> + See also: <function>mysql_drop_db</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-data-seek"> + <refnamediv> + <refname>mysql_data_seek</refname> + <refpurpose>Move internal result pointer</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_data_seek</function></funcdef> + <paramdef>resource <parameter>result_identifier</parameter></paramdef> + <paramdef>int <parameter>row_number</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on failure. + </para> + <para> + <function>mysql_data_seek</function> moves the internal row + pointer of the MySQL result associated with the specified result + identifier to point to the specified row number. The next call + to <function>mysql_fetch_row</function> would return that row. + </para> + <para> + <parameter>Row_number</parameter> starts at 0. + </para> + + <example> + <title>MySQL data seek example</title> + <programlisting role="php"> +<?php + $link = mysql_pconnect ("kron", "jutta", "geheim") + or die ("Could not connect"); + + mysql_select_db ("samp_db") + or die ("Could not select database"); + + $query = "SELECT last_name, first_name FROM friends"; + $result = mysql_query ($query) + or die ("Query failed"); + + # fetch rows in reverse order + + for ($i = mysql_num_rows ($result) - 1; $i >=0; $i--) { + if (!mysql_data_seek ($result, $i)) { + echo "Cannot seek to row $i\n"; + continue; + } + + if(!($row = mysql_fetch_object ($result))) + continue; + + echo ("$row->last_name $row->first_name<BR>\n"; + } + + mysql_free_result ($result); +?> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.mysql-db-name"> + <refnamediv> + <refname>mysql_db_name</refname> + <refpurpose>Get result data</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_db_name</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>field</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_db_name</function> takes as its first parameter + the result pointer from a call to + <function>mysql_list_dbs</function>. The + <parameter>row</parameter> parameter is an index into the result + set. + </para> + + <para> + If an error occurs, &false; is returned. Use + <function>mysql_errno</function> and + <function>mysql_error</function> to determine the nature of the + error. + </para> + + <example> + <title><function>mysql_db_name</function> example</title> + <programlisting role="php"> +<?php +error_reporting(E_ALL); + +mysql_connect('dbhost', 'username', 'password'); +$db_list = mysql_list_dbs(); + +$i = 0; +$cnt = mysql_num_rows($db_list); +while ($i < $cnt) { + echo mysql_db_name($db_list, $i) . "\n"; + $i++; +} +?> + </programlisting> + </example> + + <para> + For backward compatibility, <function>mysql_dbname</function> is + also accepted. This is deprecated, however. + </para> + + </refsect1> + </refentry> + + <refentry id="function.mysql-db-query"> + <refnamediv> + <refname>mysql_db_query</refname> + <refpurpose>Send a MySQL query</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_db_query</function></funcdef> + <paramdef>string <parameter>database</parameter></paramdef> + <paramdef>string <parameter>query</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: A positive MySQL result resource to the query result, + or &false; on error. + </para> + <para> + <function>mysql_db_query</function> selects a database and + executes a query on it. If the optional link identifier isn't + specified, the function will try to find an open link to the + MySQL server and if no such link is found it'll try to create one + as if <function>mysql_connect</function> was called with no + arguments + </para> + <para> + See also <function>mysql_connect</function> and + <function>mysql_query</function>. + </para> + <para> + <note> + <simpara> + This function has been deprecated since PHP 4.0.6. + Do not use this function. Use <function>mysql_select_db</function> + and <function>mysql_query</function> instead. + </simpara> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-drop-db"> + <refnamediv> + <refname>mysql_drop_db</refname> + <refpurpose>Drop (delete) a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_drop_db</function></funcdef> + <paramdef>string <parameter>database_name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on failure. + </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> + See also: <function>mysql_create_db</function>. For downward + compatibility <function>mysql_dropdb</function> can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-errno"> + <refnamediv> + <refname>mysql_errno</refname> + <refpurpose>Returns the numerical value of the error message from previous + MySQL operation</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_errno</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the error number from the last MySQL function, or + <literal>0</literal> (zero) if no error occurred. + </para> + <para> + Errors coming back from the MySQL database backend no longer + issue warnings. Instead, use <function>mysql_errno</function> to + retrieve the error code. Note that this function only returns the + error code from the most recently executed MySQL function (not + including <function>mysql_error</function> and + <function>mysql_errno</function>), so if you want to use it, + make sure you check the value before calling another mySQL + function. + <informalexample> + <programlisting role="php"> +<?php +mysql_connect("marliesle"); +echo mysql_errno().": ".mysql_error()."<BR>"; +mysql_select_db("nonexistentdb"); +echo mysql_errno().": ".mysql_error()."<BR>"; +$conn = mysql_query("SELECT * FROM nonexistenttable"); +echo mysql_errno().": ".mysql_error()."<BR>"; +?> + </programlisting> + </informalexample> + </para> + <para> + See also: <function>mysql_error</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-error"> + <refnamediv> + <refname>mysql_error</refname> + <refpurpose>Returns the text of the error message from previous + MySQL operation</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_error</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the error text from the last MySQL function, or + <literal>''</literal> (the empty string) if no error occurred. + </para> + <para> + Errors coming back from the MySQL database backend no longer + issue warnings. Instead, use <function>mysql_error</function> to + retrieve the error text. Note that this function only returns the + error text from the most recently executed MySQL function (not + including <function>mysql_error</function> and + <function>mysql_errno</function>), so if you want to use it, make + sure you check the value before calling another MySQL function. + <informalexample> + <programlisting role="php"> +<?php +mysql_connect("marliesle"); +echo mysql_errno().": ".mysql_error()."<BR>"; +mysql_select_db("nonexistentdb"); +echo mysql_errno().": ".mysql_error()."<BR>"; +$conn = mysql_query("SELECT * FROM nonexistenttable"); +echo mysql_errno().": ".mysql_error()."<BR>"; +?> + </programlisting> + </informalexample> + </para> + <para> + See also: <function>mysql_errno</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-escape-string"> + <refnamediv> + <refname>mysql_escape_string</refname> + <refpurpose> + Escapes a string for use in a mysql_query. + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_escape_string</function></funcdef> + <paramdef>string <parameter>unescaped_string</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + This function will escape the <parameter>unescaped_string</parameter>, + so that it is safe to place it in a <function>mysql_query</function>. + </para> + <note> + <simpara> + <function>mysql_escape_string</function> does not escape <literal>%</literal> + and <literal>_</literal>. + </simpara> + </note> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-array"> + <refnamediv> + <refname>mysql_fetch_array</refname> + <refpurpose> + Fetch a result row as an associative array, a numeric array, or both. + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_array</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int + <parameter> + <optional>result_type</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an array that corresponds to the fetched row, or &false; + if there are no more rows.</para> + <para> + <function>mysql_fetch_array</function> is an extended version of + <function>mysql_fetch_row</function>. In addition to storing the + data in the numeric indices of the result array, it also stores + the data in associative indices, using the field names as keys. + </para> + <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. + <informalexample> + <programlisting> +select t1.f1 as foo t2.f1 as bar from t1, t2 + </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. + </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) + </para> + <para> + For further details, see also + <function>mysql_fetch_row</function> and <function>mysql_fetch_assoc</function>. + </para> + <example> + <title><function>mysql_fetch_array</function> example</title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password); +$result = mysql_db_query ("database","select user_id, fullname from table"); +while ($row = mysql_fetch_array ($result)) { + echo "user_id: ".$row["user_id"]."<br>\n"; + echo "user_id: ".$row[0]."<br>\n"; + echo "fullname: ".$row["fullname"]."<br>\n"; + echo "fullname: ".$row[1]."<br>\n"; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-assoc"> + <refnamediv> + <refname>mysql_fetch_assoc</refname> + <refpurpose> + Fetch a result row as an associative array + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_assoc</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an associative array that corresponds to the fetched row, + or &false; if there are no more rows.</para> + <para> + <function>mysql_fetch_assoc</function> is equivalent to calling + <function>mysql_fetch_array</function> with MYSQL_ASSOC for the + optional second parameter. It only returns an associative array. + This is the way <function>mysql_fetch_array</function> originally + worked. If you need the numeric indices as well as the + associative, use <function>mysql_fetch_array</function>. + </para> + <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. + </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 + provides a significant added value. + </para> + <para> + For further details, see also + <function>mysql_fetch_row</function> and <function>mysql_fetch_array</function>. + </para> + <example> + <title><function>mysql_fetch_assoc</function></title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password); +$result = mysql_db_query ("database","select * from table"); +while ($row = mysql_fetch_assoc ($result)) { + echo $row["user_id"]; + echo $row["fullname"]; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-field"> + <refnamediv> + <refname>mysql_fetch_field</refname> + <refpurpose> + Get column information from a result and return as an object + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>object <function>mysql_fetch_field</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int + <parameter> + <optional>field_offset</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an object containing field information. + </para> + <para> + <function>mysql_fetch_field</function> can be used in order to + obtain information about fields in a certain query result. If + the field offset isn't specified, the next field that wasn't yet + retrieved by <function>mysql_fetch_field</function> is retrieved. + </para> + <para> + The properties of the object are: + <itemizedlist> + <listitem> + <simpara> + name - column name + </simpara> + </listitem> + <listitem> + <simpara> + table - name of the table the column belongs to + </simpara> + </listitem> + <listitem> + <simpara> + max_length - maximum length of the column + </simpara> + </listitem> + <listitem> + <simpara> + not_null - 1 if the column cannot be &null; + </simpara> + </listitem> + <listitem> + <simpara> + primary_key - 1 if the column is a primary key + </simpara> + </listitem> + <listitem> + <simpara> + unique_key - 1 if the column is a unique key + </simpara> + </listitem> + <listitem> + <simpara> + multiple_key - 1 if the column is a non-unique key + </simpara> + </listitem> + <listitem> + <simpara> + numeric - 1 if the column is numeric + </simpara> + </listitem> + <listitem> + <simpara> + blob - 1 if the column is a BLOB + </simpara> + </listitem> + <listitem> + <simpara> + type - the type of the column + </simpara> + </listitem> + <listitem> + <simpara> + unsigned - 1 if the column is unsigned + </simpara> + </listitem> + <listitem> + <simpara> + zerofill - 1 if the column is zero-filled + </simpara> + </listitem> + </itemizedlist> + </para> + <example> + <title><function>mysql_fetch_field</function></title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password) + or die ("Could not connect"); +$result = mysql_db_query ("database", "select * from table") + or die ("Query failed"); +# get column metadata +$i = 0; +while ($i < mysql_num_fields ($result)) { + echo "Information for column $i:<BR>\n"; + $meta = mysql_fetch_field ($result); + if (!$meta) { + echo "No information available<BR>\n"; + } + echo "<PRE> +blob: $meta->blob +max_length: $meta->max_length +multiple_key: $meta->multiple_key +name: $meta->name +not_null: $meta->not_null +numeric: $meta->numeric +primary_key: $meta->primary_key +table: $meta->table +type: $meta->type +unique_key: $meta->unique_key +unsigned: $meta->unsigned +zerofill: $meta->zerofill +</PRE>"; + $i++; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + <para> + See also <function>mysql_field_seek</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-lengths"> + <refnamediv> + <refname>mysql_fetch_lengths</refname> + <refpurpose> + Get the length of each output in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_lengths</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + 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> + <para> + <function>mysql_fetch_lengths</function> stores the lengths of + each result column in the last row returned by + <function>mysql_fetch_row</function>, + <function>mysql_fetch_array</function>, and + <function>mysql_fetch_object</function> in an array, starting at + offset 0. + </para> + <para> + See also: <function>mysql_fetch_row</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-object"> + <refnamediv> + <refname>mysql_fetch_object</refname> + <refpurpose>Fetch a result row as an object</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>object <function>mysql_fetch_object</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int + <parameter> + <optional>result_type</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an object with properties that correspond to the fetched + row, or &false; if there are no more rows. + </para> + <para> + <function>mysql_fetch_object</function> is similar to + <function>mysql_fetch_array</function>, with one difference - an + object is returned, instead of an array. Indirectly, that means + that you can only access the data by the field names, and not by + their offsets (numbers are illegal property names). + </para> + <para> + The optional argument <parameter>result_type</parameter> is a + constant and can take the following values: MYSQL_ASSOC, + MYSQL_NUM, and MYSQL_BOTH. + </para> + <para> + Speed-wise, the function is identical to + <function>mysql_fetch_array</function>, and almost as quick as + <function>mysql_fetch_row</function> (the difference is + insignificant). + <example> + <title><function>mysql_fetch_object</function> example</title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password); +$result = mysql_db_query ("database", "select * from table"); +while ($row = mysql_fetch_object ($result)) { + echo $row->user_id; + echo $row->fullname; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + </para> + <para> + See also: <function>mysql_fetch_array</function> and + <function>mysql_fetch_row</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-row"> + <refnamediv> + <refname>mysql_fetch_row</refname> + <refpurpose>Get a result row as an enumerated array</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_row</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: An array that corresponds to the fetched row, or &false; + if there are no more rows. + </para> + <para> + <function>mysql_fetch_row</function> fetches one row of data from + the result associated with the specified result identifier. The + row is returned as an array. Each result column is stored in an + array offset, starting at offset 0. + </para> + <para> + Subsequent call to <function>mysql_fetch_row</function> would + return the next row in the result set, or &false; if there are no + more rows. + </para> + <para> + See also: <function>mysql_fetch_array</function>, + <function>mysql_fetch_object</function>, + <function>mysql_data_seek</function>, + <function>mysql_fetch_lengths</function>, and + <function>mysql_result</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-flags"> + <refnamediv> + <refname>mysql_field_flags</refname> + <refpurpose> + Get the flags associated with the specified field in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_flags</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_flags</function> returns the field flags of + the specified field. The flags are reported as a single word + per flag separated by a single space, so that you can split the + returned value using <function>explode</function>. + </para> + <para>The following flags are reported, if your version of MySQL + is current enough to support them: "not_null", "primary_key", + "unique_key", "multiple_key", "blob", "unsigned", "zerofill", + "binary", "enum", "auto_increment", "timestamp". + </para> + <para> + For downward compatibility <function>mysql_fieldflags</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-name"> + <refnamediv> + <refname>mysql_field_name</refname> + <refpurpose> + Get the name of the specified field in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_name</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_index</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_name</function> returns the name of the + specified field index. <parameter>result</parameter> must be a + valid result identifier and <parameter>field_index</parameter> is + the numerical offset of the field. + </para> + <note> + <para> + <parameter>field_index</parameter> starts at 0. + </para> + <para> + e.g. The index of the third field would actually be 2, the index + of the fourth field would be 3 and so on. + </para> + </note> + <para> + <example> + <title><function>mysql_field_name</function> example</title> + <programlisting role="php"> +// The users table consists of three fields: +// user_id +// username +// password. + +$res = mysql_db_query("users", "select * from users", $link); + +echo mysql_field_name($res, 0) . "\n"; +echo mysql_field_name($res, 2); + </programlisting> + </example> + </para> + <para> + The above example would produce the following output: + <informalexample> + <programlisting> +user_id +password + </programlisting> + </informalexample> + </para> + <para> + For downwards compatibility <function>mysql_fieldname</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-len"> + <refnamediv> + <refname>mysql_field_len</refname> + <refpurpose> + Returns the length of the specified field + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_field_len</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_len</function> returns the length of the + specified field. + </para> + <para> + For downward compatibility <function>mysql_fieldlen</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-seek"> + <refnamediv> + <refname>mysql_field_seek</refname> + <refpurpose> + Set result pointer to a specified field offset + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_field_seek</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Seeks to the specified field offset. If the next call to + <function>mysql_fetch_field</function> doesn't include a field + offset, the field offset specified in + <function>mysql_field_seek</function> will be returned. + </para> + <para> + See also: <function>mysql_fetch_field</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-table"> + <refnamediv> + <refname>mysql_field_table</refname> + <refpurpose> + Get name of the table the specified field is in + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_table</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the name of the table that the specifed field is + in. + </para> + <para> + For downward compatibility <function>mysql_fieldtable</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-type"> + <refnamediv> + <refname>mysql_field_type</refname> + <refpurpose> + Get the type of the specified field in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_type</function></funcdef> + <paramdef>iresource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_type</function> is similar to the + <function>mysql_field_name</function> function. The arguments are + identical, but the field type is returned instead. The field type + will be one of "int", "real", "string", "blob", and others as + detailed in the <ulink url="&url.mysql.docs;">MySQL + documentation</ulink>. + <example> + <title>MySQL field types</title> + <programlisting role="php"> +<?php + +mysql_connect ("localhost:3306"); +mysql_select_db ("wisconsin"); +$result = mysql_query ("SELECT * FROM onek"); +$fields = mysql_num_fields ($result); +$rows = mysql_num_rows ($result); +$i = 0; +$table = mysql_field_table ($result, $i); +echo "Your '".$table."' table has ".$fields." fields and ".$rows." records <BR>"; +echo "The table has the following fields <BR>"; +while ($i < $fields) { + $type = mysql_field_type ($result, $i); + $name = mysql_field_name ($result, $i); + $len = mysql_field_len ($result, $i); + $flags = mysql_field_flags ($result, $i); + echo $type." ".$name." ".$len." ".$flags."<BR>"; + $i++; +} +mysql_close(); + +?> + </programlisting> + </example> + </para> + <para> + For downward compatibility <function>mysql_fieldtype</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-free-result"> + <refnamediv> + <refname>mysql_free_result</refname> + <refpurpose>Free result memory</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_free_result</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_free_result</function> will free all memory + associated with the result identifier <parameter>result</parameter>. + </para> + <para> + <function>mysql_free_result</function> only needs to be called if + 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. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-insert-id"> + <refnamediv> + <refname>mysql_insert_id</refname> + <refpurpose> + Get the id generated from the previous INSERT operation + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_insert_id</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_insert_id</function> returns the ID generated for + an AUTO_INCREMENT column by the previous INSERT query using the + given <parameter>link_identifier</parameter>. If + <parameter>link_identifier</parameter> isn't specified, the last + opened link is assumed. + </para> + <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. + </para> + <note> + <para> + The value of the MySQL SQL function + <literal>LAST_INSERT_ID()</literal> always contains the most + recently generated AUTO_INCREMENT value, and is not reset + between queries. + </para> + </note> + <warning> + <para> + <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>. + </para> + </warning> + </refsect1> + </refentry> + + <refentry id="function.mysql-list-dbs"> + <refnamediv> + <refname>mysql_list_dbs</refname> + <refpurpose> + List databases available on a MySQL server + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_list_dbs</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <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. + </para> + <para> + <example> + <title><function>mysql_list_dbs</function> example</title> + <programlisting role="php"> +$link = mysql_connect('localhost', 'myname', 'secret'); +$db_list = mysql_list_dbs($link); + +while ($row = mysql_fetch_object($db_list)) { + echo $row->Database . "\n"; +} + </programlisting> + </example> + </para> + <para> + The above example would produce the following output: + <informalexample> + <programlisting> +database1 +database2 +database3 +... + </programlisting> + </informalexample> + </para> + <note> + <para> + The above code would just as easily work with + <function>mysql_fetch_row</function> or other similar functions. + </para> + </note> + <para> + For downward compatibility <function>mysql_listdbs</function> can + also be used. + </para> + <para>See also <function>mysql_db_name</function></para> + </refsect1> + </refentry> + + <refentry id="function.mysql-list-fields"> + <refnamediv> + <refname>mysql_list_fields</refname> + <refpurpose>List MySQL result fields</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_list_fields</function></funcdef> + <paramdef>string <parameter>database_name</parameter></paramdef> + <paramdef>string <parameter>table_name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_list_fields</function> retrieves information + about the given tablename. Arguments are the database name and + the table name. A result pointer is returned which can be used + with <function>mysql_field_flags</function>, + <function>mysql_field_len</function>, + <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> + <programlisting role="php"> +$link = mysql_connect('localhost', 'myname', 'secret'); + +$fields = mysql_list_fields("database1", "table1", $link); +$columns = mysql_num_fields($fields); + +for ($i = 0; $i < $columns; $i++) { + echo mysql_field_name($fields, $i) . "\n";; +} + </programlisting> + </example> + </para> + <para> + The above example would produce the following output: + <informalexample> + <programlisting> +field1 +field2 +field3 +... + </programlisting> + </informalexample> + </para> + <para> + 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> + + <refentry id="function.mysql-list-tables"> + <refnamediv> + <refname>mysql_list_tables</refname> + <refpurpose>List tables in a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_list_tables</function></funcdef> + <paramdef>string <parameter>database</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <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. + </para> + <para> + For downward compatibility <function>mysql_listtables</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-num-fields"> + <refnamediv> + <refname>mysql_num_fields</refname> + <refpurpose>Get number of fields in result</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_num_fields</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_num_fields</function> returns the number of + fields in a result set. + </para> + <para> + See also: + <function>mysql_db_query</function>, + <function>mysql_query</function>, + <function>mysql_fetch_field</function>, + <function>mysql_num_rows</function>.</para> + <para> + For downward compatibility <function>mysql_numfields</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-num-rows"> + <refnamediv> + <refname>mysql_num_rows</refname> + <refpurpose>Get number of rows in result</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_num_rows</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <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 + DELETE query, use <function>mysql_affected_rows</function>. + <example> + <title><function>mysql_num_rows</function> example</title> + <programlisting role="php"> +<?php + +$link = mysql_connect("localhost", "username", "password"); +mysql_select_db("database", $link); + +$result = mysql_query("SELECT * FROM table1", $link); +$num_rows = mysql_num_rows($result); + +echo "$num_rows Rows\n"; + +?> + </programlisting> + </example> + </para> + <para> + See also: + <function>mysql_affected_rows</function>, + <function>mysql_connect</function>, + <function>mysql_select_db</function> and + <function>mysql_query</function>. + </para> + <para> + For downward compatibility <function>mysql_numrows</function> can + also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-pconnect"> + <refnamediv> + <refname>mysql_pconnect</refname> + <refpurpose> + Open a persistent connection to a MySQL Server + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_pconnect</function></funcdef> + <paramdef>string + <parameter> + <optional>hostname + <optional>:port</optional> + <optional>:/path/to/socket</optional> + </optional> + </parameter> + </paramdef> + <paramdef>string + <parameter><optional>username</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>password</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: A positive MySQL persistent link identifier on success, + or &false; on error. + </para> + <para> + <function>mysql_pconnect</function> establishes a connection + to a MySQL server. The following defaults are assumed for + missing optional parameters: <parameter>host:port</parameter> = + 'localhost:3306', <parameter>username</parameter> = name of the + user that owns the server process and + <parameter>password</parameter> = empty password. + </para> + <para> + The hostname string can also include a port + number. eg. "hostname:port" or a path to a socket + eg. ":/path/to/socket" for the localhost. + <note> + <para> + Support for ":port" was added in 3.0B4. + </para> + <para> + Support for the ":/path/to/socket" was added in + 3.0.10. + </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. + </para> + <para> + First, when connecting, the function would first try to find a + (persistent) link that's already open with the same host, + username and password. If one is found, an identifier for it + will be returned instead of opening a new connection. + </para> + <para> + Second, the connection to the SQL server will not be closed when + the execution of the script ends. Instead, the link will remain + open for future use (<function>mysql_close</function> will not + close links established by <function>mysql_pconnect</function>). + </para> + <para> + This type of links is therefore called 'persistent'. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-query"> + <refnamediv> + <refname>mysql_query</refname> + <refpurpose>Send a MySQL query</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_query</function></funcdef> + <paramdef>string <parameter>query</parameter></paramdef> + <paramdef>resource + <parameter><optional>link_identifier</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_query</function> sends a query to the currently + active database on the server that's associated with the + specified link identifier. If + <parameter>link_identifier</parameter> isn't specified, the last + opened link is assumed. If no link is open, the function tries + to establish a link as if <function>mysql_connect</function> was + called with no arguments, and use it. + </para> + <note> + <para> + The query string should not end with a semicolon. + </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 + 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. + </para> + <para> + The following query is syntactically invalid, so + <function>mysql_query</function> fails and returns &false;: + <example> + <title><function>mysql_query</function></title> + <programlisting role="php"> +<?php +$result = mysql_query ("SELECT * WHERE 1=1") + or die ("Invalid query"); +?> + </programlisting> + </example> + </para> + <para> + The following query is semantically invalid if + <literal>my_col</literal> is not a column in the table + <literal>my_tbl</literal>, so <function>mysql_query</function> + fails and returns &false;: + <example> + <title><function>mysql_query</function></title> + <programlisting role="php"> +<?php +$result = mysql_query ("SELECT my_col FROM my_tbl") + or die ("Invalid query"); +?> + </programlisting> + </example> + </para> + <para> + <function>mysql_query</function> will also fail and return &false; + if you don't have permission to access the table(s) referenced by + the query. + </para> + <para> + Assuming the query succeeds, you can call + <function>mysql_num_rows</function> to find out how many rows + were returned for a SELECT statment or + <function>mysql_affected_rows</function> to find out how many + rows were affected by a DELETE, INSERT, REPLACE, or UPDATE + statement. + </para> + <para> + 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 + result set, you can free the resources associated with it by + 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>, + <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 + <function>mysql_connect</function>. + </para> + </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>resource <function>mysql_unbuffered_query</function></funcdef> + <paramdef>string <parameter>query</parameter></paramdef> + <paramdef>resource + <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> + <refpurpose>Get result data</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>mysql_result</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>field</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_result</function> returns the contents of one + cell from a MySQL result set. The field argument can be the + field's offset, or the field's name, or the field's table dot + field's name (tabledname.fieldname). If the column name has been + aliased ('select foo as bar from...'), use the alias instead of + the column name. + </para> + <para> + When working on large result sets, you should consider using one + of the functions that fetch an entire row (specified below). As + these functions return the contents of multiple cells in one + function call, they're MUCH quicker than + <function>mysql_result</function>. Also, note that specifying a + numeric offset for the field argument is much quicker than + specifying a fieldname or tablename.fieldname argument. + </para> + <para> + Calls to <function>mysql_result</function> should not be mixed + with calls to other functions that deal with the result set. + </para> + <para> + Recommended high-performance alternatives: + <function>mysql_fetch_row</function>, + <function>mysql_fetch_array</function>, and + <function>mysql_fetch_object</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-select-db"> + <refnamediv> + <refname>mysql_select_db</refname> + <refpurpose>Select a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_select_db</function></funcdef> + <paramdef>string <parameter>database_name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on error. + </para> + <para> + <function>mysql_select_db</function> sets the current active + database on the server that's associated with the specified link + 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. + </para> + <para> + Every subsequent call to <function>mysql_query</function> will be + made on the active database. + </para> + <para> See also: + <function>mysql_connect</function>, + <function>mysql_pconnect</function>, and + <function>mysql_query</function>. + </para> + <para> + For downward compatibility <function>mysql_selectdb</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-tablename"> + <refnamediv> + <refname>mysql_tablename</refname> + <refpurpose>Get table name of field</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_tablename</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>i</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_tablename</function> takes a result pointer + returned by the <function>mysql_list_tables</function> function + as well as an integer index and returns the name of a table. The + <function>mysql_num_rows</function> function may be used to + determine the number of tables in the result pointer. + <example> + <title><function>mysql_tablename</function> Example</title> + <programlisting role="php"> +<?php +mysql_connect ("localhost:3306"); +$result = mysql_list_tables ("wisconsin"); +$i = 0; +while ($i < mysql_num_rows ($result)) { + $tb_names[$i] = mysql_tablename ($result, $i); + echo $tb_names[$i] . "<BR>"; + $i++; +} +?> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-client-info"> + <refnamediv> + <refname>mysql_get_client_info</refname> + <refpurpose>Get MySQL client info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_get_client_info</function></funcdef> + <void/> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_client_info</function> returns a string that represents + the client library version. + </para> + <para> + <function>mysql_get_client_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-host-info"> + <refnamediv> + <refname>mysql_get_host_info</refname> + <refpurpose>Get MySQL host info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_get_host_info</function></funcdef> + <paramdef>resource <parameter><optional>link_identifier</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_host_info</function> returns a string + describing the type of connection in use for the connection + <parameter>link_identifier</parameter>, including the server host name. + If <parameter>link_identifier</parameter> is omited, the last opened + connection will be used. + </para> + <para> + <function>mysql_get_host_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-proto-info"> + <refnamediv> + <refname>mysql_get_proto_info</refname> + <refpurpose>Get MySQL protocol info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_get_proto_info</function></funcdef> + <paramdef>resource <parameter><optional>link_identifier</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_proto_info</function> returns the protocol version + used by connection <parameter>link_identifier</parameter>. + If <parameter>link_identifier</parameter> is omited, the last opened + connection will be used. + </para> + <para> + <function>mysql_get_proto_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-server-info"> + <refnamediv> + <refname>mysql_get_server_info</refname> + <refpurpose>Get MySQL server info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_get_server_info</function></funcdef> + <paramdef>resource <parameter><optional>link_identifier</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_server_info</function> returns the server version + used by connection <parameter>link_identifier</parameter>. + If <parameter>link_identifier</parameter> is omited, the last opened + connection will be used. + </para> + <para> + <function>mysql_get_server_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vi: et:ts=1:sw=1:textwidth=78:syntax=sgml +-->
Index: phpdoc/en/functions/mysql.xml diff -u /dev/null phpdoc/en/functions/mysql.xml:1.62 --- /dev/null Thu Aug 30 12:51:12 2001 +++ phpdoc/en/functions/mysql.xml Thu Aug 30 12:51:12 2001 @@ -0,0 +1,2138 @@ +<?xml encoding="iso-8859-1"?> +<!-- $Revision: 1.62 $ --> + <reference id="ref.mysql"> + <title>MySQL functions</title> + <titleabbrev>MySQL</titleabbrev> + <partintro> + <simpara> + These functions allow you to access MySQL database servers. In + order to have these functions available, you must compile php + with MySQL support by using the + <option role="configure">--with-mysql</option> option. If you + use this option without specifying the path to MySQL, php will + use the built-in MySQL client libraries. Users who run other + applications that use MySQL (for example, running php3 and php4 + as concurrent apache modules, or auth-mysql) should always + specify the path to MySQL: + <option role="configure">--with-mysql=/path/to/mysql</option>. + This will force php to use the client libraries installed by + MySQL, avoiding any conflicts. + </simpara> + <simpara> + More information about MySQL can be found at <ulink + url="&url.mysql;">&url.mysql;</ulink>. + </simpara> + <simpara> + Documentation for MySQL can be found at <ulink + url="&url.mysql.docs;">&url.mysql.docs;</ulink>. + </simpara> + <para> + This simple example shows how to connect, execute a query, print + resulting rows and disconnect from MySQL Database. + <example> + <title>MySQL extension overview example</title> + <programlisting role="php"> +<?php + $link = mysql_connect("mysql_host", "mysql_login", "mysql_password") + or die ("Could not connect"); + print ("Connected successfully"); + mysql_select_db ("my_database") + or die ("Could not select database"); + + $query = "SELECT * FROM my_table"; + $result = mysql_query ($query) + or die ("Query failed"); + + // printing HTML result + + print "<table>\n"; + while($line = mysql_fetch_array($result)){ + print "\t<tr>\n"; + while(list($col_name, $col_value) = each($line)){ + print "\t\t<td>$col_value</td>\n"; + } + print "\t</tr>\n"; + } + print "</table>\n"; + + mysql_close($link); +?> + </programlisting> + </example> + </para> + </partintro> + + <refentry id="function.mysql-affected-rows"> + <refnamediv> + <refname>mysql_affected_rows</refname> + <refpurpose>Get number of affected rows in previous MySQL + operation</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_affected_rows</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_affected_rows</function> returns the number + of rows affected by the last INSERT, UPDATE or DELETE query + associated with <parameter>link_identifier</parameter>. If the + link identifier isn't specified, the last link opened by + <function>mysql_connect</function> is assumed. + </para> + <note> + <para> + If you are using transactions, you need to call + <function>mysql_affected_rows</function> after your INSERT, + UPDATE, or DELETE query, not after the commit. + </para> + </note> + <para> + If the last query was a DELETE query with no WHERE clause, all + of the records will have been deleted from the table but this + function will return zero. + </para> + <note> + <para> + When using UPDATE, MySQL will not update columns where the new + value is the same as the old value. This creates the possiblity + that <function>mysql_affected_rows</function> may not actually + equal the number of rows matched, only the number of rows that + were literally affected by the query. + </para> + </note> + <para> + <function>mysql_affected_rows</function> does not work with + SELECT statements; only on statements which modify records. To + retrieve the number of rows returned by a SELECT, use + <function>mysql_num_rows</function>. + </para> + <para> + If the last query failed, this function will return -1. + </para> + <para> + See also: <function>mysql_num_rows</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-change-user"> + <refnamediv> + <refname>mysql_change_user</refname> + <refpurpose> + Change logged in user of the active connection + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_change_user</function></funcdef> + <paramdef>string <parameter>user</parameter></paramdef> + <paramdef>string <parameter>password</parameter></paramdef> + <paramdef>string + <parameter> + <optional>database</optional> + </parameter> + </paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_change_user</function> changes the logged in user + of the current active connection, or the connection given by the + optional parameter link_identifier. If a database is + 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> + </refsect1> + </refentry> + + <refentry id="function.mysql-close"> + <refnamediv> + <refname>mysql_close</refname> + <refpurpose>Close MySQL connection</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_close</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on error. + </para> + <para> <function>mysql_close</function> closes the connection to + the MySQL server that's associated with the specified link + identifier. If <parameter>link_identifier</parameter> isn't + specified, the last opened link is used. + </para> + <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. See also + <link linkend="language.types.resource.self-destruct">freeing + resources</link>. + </para> + <note> + <para> + <function>mysql_close</function> will not close persistent links + created by <function>mysql_pconnect</function>. + </para> + </note> + <example> + <title>MySQL close example</title> + <programlisting role="php"> +<?php + $link = mysql_connect ("kraemer", "marliesle", "secret") + or die ("Could not connect"); + print ("Connected successfully"); + mysql_close ($link); +?> + </programlisting> + </example> + <para> + See also: <function>mysql_connect</function>, and + <function>mysql_pconnect</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-connect"> + <refnamediv> + <refname>mysql_connect</refname> + <refpurpose>Open a connection to a MySQL Server</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_connect</function></funcdef> + <paramdef>string + <parameter> + <optional>hostname + <optional>:port</optional> + <optional>:/path/to/socket</optional> + </optional> + </parameter> + </paramdef> + <paramdef>string + <parameter> + <optional>username</optional> + </parameter> + </paramdef> + <paramdef>string + <parameter> + <optional>password</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns a MySQL link identifier on success, or &false; on failure. + </para> + <para> + <function>mysql_connect</function> establishes a connection + to a MySQL server. The following defaults are assumed for + missing optional parameters: <parameter>host:port</parameter> = + 'localhost:3306', <parameter>username</parameter> = name of the + user that owns the server process and + <parameter>password</parameter> = empty password. + </para> + <para> + The hostname string can also include a port + number. eg. "hostname:port" or a path to a socket + eg. ":/path/to/socket" for the localhost. + <note> + <para> + Support for ":port" was added in PHP 3.0B4. + </para> + <para> + Support for ":/path/to/socket" was added in + PHP 3.0.10. + </para> + <para> + You can suppress the error message on failure by prepending '@' + to the function name. + </para> + </note> + </para> + <para> + If a second call is made to <function>mysql_connect</function> + with the same arguments, no new link will be established, but + instead, the link identifier of the already opened link will be + returned. + </para> + <para> + The link to the server will be closed as soon as the execution of + the script ends, unless it's closed earlier by explicitly calling + <function>mysql_close</function>. + </para> + <example> + <title>MySQL connect example</title> + <programlisting role="php"> +<?php + + $link = mysql_connect ("localhost", "username", "secret") + or die ("Could not connect"); + print ("Connected successfully"); + mysql_close ($link); + +?> + </programlisting> + </example> + <para> See also + <function>mysql_pconnect</function>, and + <function>mysql_close</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-create-db"> + <refnamediv> + <refname>mysql_create_db</refname> + <refpurpose>Create a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_create_db</function></funcdef> + <paramdef>string <parameter>database name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_create_db</function> attempts to create a new + database on the server associated with the specified link + identifier. + </para> + <!-- returns?? bool -> succes? --> + <example> + <title>MySQL create database example</title> + <programlisting role="php"> +<?php + $link = mysql_pconnect ("kron", "jutta", "geheim") + or die ("Could not connect"); + if (mysql_create_db ("my_db")) { + print ("Database created successfully\n"); + } else { + printf ("Error creating database: %s\n", mysql_error ()); + } +?> + </programlisting> + </example> + <para> + For downwards compatibility <function>mysql_createdb</function> + can also be used. + </para> + <para> + See also: <function>mysql_drop_db</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-data-seek"> + <refnamediv> + <refname>mysql_data_seek</refname> + <refpurpose>Move internal result pointer</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_data_seek</function></funcdef> + <paramdef>resource <parameter>result_identifier</parameter></paramdef> + <paramdef>int <parameter>row_number</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on failure. + </para> + <para> + <function>mysql_data_seek</function> moves the internal row + pointer of the MySQL result associated with the specified result + identifier to point to the specified row number. The next call + to <function>mysql_fetch_row</function> would return that row. + </para> + <para> + <parameter>Row_number</parameter> starts at 0. + </para> + + <example> + <title>MySQL data seek example</title> + <programlisting role="php"> +<?php + $link = mysql_pconnect ("kron", "jutta", "geheim") + or die ("Could not connect"); + + mysql_select_db ("samp_db") + or die ("Could not select database"); + + $query = "SELECT last_name, first_name FROM friends"; + $result = mysql_query ($query) + or die ("Query failed"); + + # fetch rows in reverse order + + for ($i = mysql_num_rows ($result) - 1; $i >=0; $i--) { + if (!mysql_data_seek ($result, $i)) { + echo "Cannot seek to row $i\n"; + continue; + } + + if(!($row = mysql_fetch_object ($result))) + continue; + + echo ("$row->last_name $row->first_name<BR>\n"; + } + + mysql_free_result ($result); +?> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.mysql-db-name"> + <refnamediv> + <refname>mysql_db_name</refname> + <refpurpose>Get result data</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_db_name</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>field</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_db_name</function> takes as its first parameter + the result pointer from a call to + <function>mysql_list_dbs</function>. The + <parameter>row</parameter> parameter is an index into the result + set. + </para> + + <para> + If an error occurs, &false; is returned. Use + <function>mysql_errno</function> and + <function>mysql_error</function> to determine the nature of the + error. + </para> + + <example> + <title><function>mysql_db_name</function> example</title> + <programlisting role="php"> +<?php +error_reporting(E_ALL); + +mysql_connect('dbhost', 'username', 'password'); +$db_list = mysql_list_dbs(); + +$i = 0; +$cnt = mysql_num_rows($db_list); +while ($i < $cnt) { + echo mysql_db_name($db_list, $i) . "\n"; + $i++; +} +?> + </programlisting> + </example> + + <para> + For backward compatibility, <function>mysql_dbname</function> is + also accepted. This is deprecated, however. + </para> + + </refsect1> + </refentry> + + <refentry id="function.mysql-db-query"> + <refnamediv> + <refname>mysql_db_query</refname> + <refpurpose>Send a MySQL query</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_db_query</function></funcdef> + <paramdef>string <parameter>database</parameter></paramdef> + <paramdef>string <parameter>query</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: A positive MySQL result resource to the query result, + or &false; on error. + </para> + <para> + <function>mysql_db_query</function> selects a database and + executes a query on it. If the optional link identifier isn't + specified, the function will try to find an open link to the + MySQL server and if no such link is found it'll try to create one + as if <function>mysql_connect</function> was called with no + arguments + </para> + <para> + See also <function>mysql_connect</function> and + <function>mysql_query</function>. + </para> + <para> + <note> + <simpara> + This function has been deprecated since PHP 4.0.6. + Do not use this function. Use <function>mysql_select_db</function> + and <function>mysql_query</function> instead. + </simpara> + </note> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-drop-db"> + <refnamediv> + <refname>mysql_drop_db</refname> + <refpurpose>Drop (delete) a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_drop_db</function></funcdef> + <paramdef>string <parameter>database_name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on failure. + </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> + See also: <function>mysql_create_db</function>. For downward + compatibility <function>mysql_dropdb</function> can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-errno"> + <refnamediv> + <refname>mysql_errno</refname> + <refpurpose>Returns the numerical value of the error message from previous + MySQL operation</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_errno</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the error number from the last MySQL function, or + <literal>0</literal> (zero) if no error occurred. + </para> + <para> + Errors coming back from the MySQL database backend no longer + issue warnings. Instead, use <function>mysql_errno</function> to + retrieve the error code. Note that this function only returns the + error code from the most recently executed MySQL function (not + including <function>mysql_error</function> and + <function>mysql_errno</function>), so if you want to use it, + make sure you check the value before calling another mySQL + function. + <informalexample> + <programlisting role="php"> +<?php +mysql_connect("marliesle"); +echo mysql_errno().": ".mysql_error()."<BR>"; +mysql_select_db("nonexistentdb"); +echo mysql_errno().": ".mysql_error()."<BR>"; +$conn = mysql_query("SELECT * FROM nonexistenttable"); +echo mysql_errno().": ".mysql_error()."<BR>"; +?> + </programlisting> + </informalexample> + </para> + <para> + See also: <function>mysql_error</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-error"> + <refnamediv> + <refname>mysql_error</refname> + <refpurpose>Returns the text of the error message from previous + MySQL operation</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_error</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the error text from the last MySQL function, or + <literal>''</literal> (the empty string) if no error occurred. + </para> + <para> + Errors coming back from the MySQL database backend no longer + issue warnings. Instead, use <function>mysql_error</function> to + retrieve the error text. Note that this function only returns the + error text from the most recently executed MySQL function (not + including <function>mysql_error</function> and + <function>mysql_errno</function>), so if you want to use it, make + sure you check the value before calling another MySQL function. + <informalexample> + <programlisting role="php"> +<?php +mysql_connect("marliesle"); +echo mysql_errno().": ".mysql_error()."<BR>"; +mysql_select_db("nonexistentdb"); +echo mysql_errno().": ".mysql_error()."<BR>"; +$conn = mysql_query("SELECT * FROM nonexistenttable"); +echo mysql_errno().": ".mysql_error()."<BR>"; +?> + </programlisting> + </informalexample> + </para> + <para> + See also: <function>mysql_errno</function> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-escape-string"> + <refnamediv> + <refname>mysql_escape_string</refname> + <refpurpose> + Escapes a string for use in a mysql_query. + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_escape_string</function></funcdef> + <paramdef>string <parameter>unescaped_string</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + This function will escape the <parameter>unescaped_string</parameter>, + so that it is safe to place it in a <function>mysql_query</function>. + </para> + <note> + <simpara> + <function>mysql_escape_string</function> does not escape <literal>%</literal> + and <literal>_</literal>. + </simpara> + </note> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-array"> + <refnamediv> + <refname>mysql_fetch_array</refname> + <refpurpose> + Fetch a result row as an associative array, a numeric array, or both. + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_array</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int + <parameter> + <optional>result_type</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an array that corresponds to the fetched row, or &false; + if there are no more rows.</para> + <para> + <function>mysql_fetch_array</function> is an extended version of + <function>mysql_fetch_row</function>. In addition to storing the + data in the numeric indices of the result array, it also stores + the data in associative indices, using the field names as keys. + </para> + <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. + <informalexample> + <programlisting> +select t1.f1 as foo t2.f1 as bar from t1, t2 + </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. + </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) + </para> + <para> + For further details, see also + <function>mysql_fetch_row</function> and <function>mysql_fetch_assoc</function>. + </para> + <example> + <title><function>mysql_fetch_array</function> example</title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password); +$result = mysql_db_query ("database","select user_id, fullname from table"); +while ($row = mysql_fetch_array ($result)) { + echo "user_id: ".$row["user_id"]."<br>\n"; + echo "user_id: ".$row[0]."<br>\n"; + echo "fullname: ".$row["fullname"]."<br>\n"; + echo "fullname: ".$row[1]."<br>\n"; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-assoc"> + <refnamediv> + <refname>mysql_fetch_assoc</refname> + <refpurpose> + Fetch a result row as an associative array + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_assoc</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an associative array that corresponds to the fetched row, + or &false; if there are no more rows.</para> + <para> + <function>mysql_fetch_assoc</function> is equivalent to calling + <function>mysql_fetch_array</function> with MYSQL_ASSOC for the + optional second parameter. It only returns an associative array. + This is the way <function>mysql_fetch_array</function> originally + worked. If you need the numeric indices as well as the + associative, use <function>mysql_fetch_array</function>. + </para> + <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. + </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 + provides a significant added value. + </para> + <para> + For further details, see also + <function>mysql_fetch_row</function> and <function>mysql_fetch_array</function>. + </para> + <example> + <title><function>mysql_fetch_assoc</function></title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password); +$result = mysql_db_query ("database","select * from table"); +while ($row = mysql_fetch_assoc ($result)) { + echo $row["user_id"]; + echo $row["fullname"]; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-field"> + <refnamediv> + <refname>mysql_fetch_field</refname> + <refpurpose> + Get column information from a result and return as an object + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>object <function>mysql_fetch_field</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int + <parameter> + <optional>field_offset</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an object containing field information. + </para> + <para> + <function>mysql_fetch_field</function> can be used in order to + obtain information about fields in a certain query result. If + the field offset isn't specified, the next field that wasn't yet + retrieved by <function>mysql_fetch_field</function> is retrieved. + </para> + <para> + The properties of the object are: + <itemizedlist> + <listitem> + <simpara> + name - column name + </simpara> + </listitem> + <listitem> + <simpara> + table - name of the table the column belongs to + </simpara> + </listitem> + <listitem> + <simpara> + max_length - maximum length of the column + </simpara> + </listitem> + <listitem> + <simpara> + not_null - 1 if the column cannot be &null; + </simpara> + </listitem> + <listitem> + <simpara> + primary_key - 1 if the column is a primary key + </simpara> + </listitem> + <listitem> + <simpara> + unique_key - 1 if the column is a unique key + </simpara> + </listitem> + <listitem> + <simpara> + multiple_key - 1 if the column is a non-unique key + </simpara> + </listitem> + <listitem> + <simpara> + numeric - 1 if the column is numeric + </simpara> + </listitem> + <listitem> + <simpara> + blob - 1 if the column is a BLOB + </simpara> + </listitem> + <listitem> + <simpara> + type - the type of the column + </simpara> + </listitem> + <listitem> + <simpara> + unsigned - 1 if the column is unsigned + </simpara> + </listitem> + <listitem> + <simpara> + zerofill - 1 if the column is zero-filled + </simpara> + </listitem> + </itemizedlist> + </para> + <example> + <title><function>mysql_fetch_field</function></title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password) + or die ("Could not connect"); +$result = mysql_db_query ("database", "select * from table") + or die ("Query failed"); +# get column metadata +$i = 0; +while ($i < mysql_num_fields ($result)) { + echo "Information for column $i:<BR>\n"; + $meta = mysql_fetch_field ($result); + if (!$meta) { + echo "No information available<BR>\n"; + } + echo "<PRE> +blob: $meta->blob +max_length: $meta->max_length +multiple_key: $meta->multiple_key +name: $meta->name +not_null: $meta->not_null +numeric: $meta->numeric +primary_key: $meta->primary_key +table: $meta->table +type: $meta->type +unique_key: $meta->unique_key +unsigned: $meta->unsigned +zerofill: $meta->zerofill +</PRE>"; + $i++; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + <para> + See also <function>mysql_field_seek</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-lengths"> + <refnamediv> + <refname>mysql_fetch_lengths</refname> + <refpurpose> + Get the length of each output in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_lengths</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + 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> + <para> + <function>mysql_fetch_lengths</function> stores the lengths of + each result column in the last row returned by + <function>mysql_fetch_row</function>, + <function>mysql_fetch_array</function>, and + <function>mysql_fetch_object</function> in an array, starting at + offset 0. + </para> + <para> + See also: <function>mysql_fetch_row</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-object"> + <refnamediv> + <refname>mysql_fetch_object</refname> + <refpurpose>Fetch a result row as an object</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>object <function>mysql_fetch_object</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int + <parameter> + <optional>result_type</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns an object with properties that correspond to the fetched + row, or &false; if there are no more rows. + </para> + <para> + <function>mysql_fetch_object</function> is similar to + <function>mysql_fetch_array</function>, with one difference - an + object is returned, instead of an array. Indirectly, that means + that you can only access the data by the field names, and not by + their offsets (numbers are illegal property names). + </para> + <para> + The optional argument <parameter>result_type</parameter> is a + constant and can take the following values: MYSQL_ASSOC, + MYSQL_NUM, and MYSQL_BOTH. + </para> + <para> + Speed-wise, the function is identical to + <function>mysql_fetch_array</function>, and almost as quick as + <function>mysql_fetch_row</function> (the difference is + insignificant). + <example> + <title><function>mysql_fetch_object</function> example</title> + <programlisting role="php"> +<?php +mysql_connect ($host, $user, $password); +$result = mysql_db_query ("database", "select * from table"); +while ($row = mysql_fetch_object ($result)) { + echo $row->user_id; + echo $row->fullname; +} +mysql_free_result ($result); +?> + </programlisting> + </example> + </para> + <para> + See also: <function>mysql_fetch_array</function> and + <function>mysql_fetch_row</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-fetch-row"> + <refnamediv> + <refname>mysql_fetch_row</refname> + <refpurpose>Get a result row as an enumerated array</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>mysql_fetch_row</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: An array that corresponds to the fetched row, or &false; + if there are no more rows. + </para> + <para> + <function>mysql_fetch_row</function> fetches one row of data from + the result associated with the specified result identifier. The + row is returned as an array. Each result column is stored in an + array offset, starting at offset 0. + </para> + <para> + Subsequent call to <function>mysql_fetch_row</function> would + return the next row in the result set, or &false; if there are no + more rows. + </para> + <para> + See also: <function>mysql_fetch_array</function>, + <function>mysql_fetch_object</function>, + <function>mysql_data_seek</function>, + <function>mysql_fetch_lengths</function>, and + <function>mysql_result</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-flags"> + <refnamediv> + <refname>mysql_field_flags</refname> + <refpurpose> + Get the flags associated with the specified field in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_flags</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_flags</function> returns the field flags of + the specified field. The flags are reported as a single word + per flag separated by a single space, so that you can split the + returned value using <function>explode</function>. + </para> + <para>The following flags are reported, if your version of MySQL + is current enough to support them: "not_null", "primary_key", + "unique_key", "multiple_key", "blob", "unsigned", "zerofill", + "binary", "enum", "auto_increment", "timestamp". + </para> + <para> + For downward compatibility <function>mysql_fieldflags</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-name"> + <refnamediv> + <refname>mysql_field_name</refname> + <refpurpose> + Get the name of the specified field in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_name</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_index</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_name</function> returns the name of the + specified field index. <parameter>result</parameter> must be a + valid result identifier and <parameter>field_index</parameter> is + the numerical offset of the field. + </para> + <note> + <para> + <parameter>field_index</parameter> starts at 0. + </para> + <para> + e.g. The index of the third field would actually be 2, the index + of the fourth field would be 3 and so on. + </para> + </note> + <para> + <example> + <title><function>mysql_field_name</function> example</title> + <programlisting role="php"> +// The users table consists of three fields: +// user_id +// username +// password. + +$res = mysql_db_query("users", "select * from users", $link); + +echo mysql_field_name($res, 0) . "\n"; +echo mysql_field_name($res, 2); + </programlisting> + </example> + </para> + <para> + The above example would produce the following output: + <informalexample> + <programlisting> +user_id +password + </programlisting> + </informalexample> + </para> + <para> + For downwards compatibility <function>mysql_fieldname</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-len"> + <refnamediv> + <refname>mysql_field_len</refname> + <refpurpose> + Returns the length of the specified field + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_field_len</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_len</function> returns the length of the + specified field. + </para> + <para> + For downward compatibility <function>mysql_fieldlen</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-seek"> + <refnamediv> + <refname>mysql_field_seek</refname> + <refpurpose> + Set result pointer to a specified field offset + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_field_seek</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Seeks to the specified field offset. If the next call to + <function>mysql_fetch_field</function> doesn't include a field + offset, the field offset specified in + <function>mysql_field_seek</function> will be returned. + </para> + <para> + See also: <function>mysql_fetch_field</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-table"> + <refnamediv> + <refname>mysql_field_table</refname> + <refpurpose> + Get name of the table the specified field is in + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_table</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns the name of the table that the specifed field is + in. + </para> + <para> + For downward compatibility <function>mysql_fieldtable</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-field-type"> + <refnamediv> + <refname>mysql_field_type</refname> + <refpurpose> + Get the type of the specified field in a result + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_field_type</function></funcdef> + <paramdef>iresource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>field_offset</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_field_type</function> is similar to the + <function>mysql_field_name</function> function. The arguments are + identical, but the field type is returned instead. The field type + will be one of "int", "real", "string", "blob", and others as + detailed in the <ulink url="&url.mysql.docs;">MySQL + documentation</ulink>. + <example> + <title>MySQL field types</title> + <programlisting role="php"> +<?php + +mysql_connect ("localhost:3306"); +mysql_select_db ("wisconsin"); +$result = mysql_query ("SELECT * FROM onek"); +$fields = mysql_num_fields ($result); +$rows = mysql_num_rows ($result); +$i = 0; +$table = mysql_field_table ($result, $i); +echo "Your '".$table."' table has ".$fields." fields and ".$rows." records <BR>"; +echo "The table has the following fields <BR>"; +while ($i < $fields) { + $type = mysql_field_type ($result, $i); + $name = mysql_field_name ($result, $i); + $len = mysql_field_len ($result, $i); + $flags = mysql_field_flags ($result, $i); + echo $type." ".$name." ".$len." ".$flags."<BR>"; + $i++; +} +mysql_close(); + +?> + </programlisting> + </example> + </para> + <para> + For downward compatibility <function>mysql_fieldtype</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-free-result"> + <refnamediv> + <refname>mysql_free_result</refname> + <refpurpose>Free result memory</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_free_result</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_free_result</function> will free all memory + associated with the result identifier <parameter>result</parameter>. + </para> + <para> + <function>mysql_free_result</function> only needs to be called if + 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. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-insert-id"> + <refnamediv> + <refname>mysql_insert_id</refname> + <refpurpose> + Get the id generated from the previous INSERT operation + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_insert_id</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_insert_id</function> returns the ID generated for + an AUTO_INCREMENT column by the previous INSERT query using the + given <parameter>link_identifier</parameter>. If + <parameter>link_identifier</parameter> isn't specified, the last + opened link is assumed. + </para> + <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. + </para> + <note> + <para> + The value of the MySQL SQL function + <literal>LAST_INSERT_ID()</literal> always contains the most + recently generated AUTO_INCREMENT value, and is not reset + between queries. + </para> + </note> + <warning> + <para> + <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>. + </para> + </warning> + </refsect1> + </refentry> + + <refentry id="function.mysql-list-dbs"> + <refnamediv> + <refname>mysql_list_dbs</refname> + <refpurpose> + List databases available on a MySQL server + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_list_dbs</function></funcdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <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. + </para> + <para> + <example> + <title><function>mysql_list_dbs</function> example</title> + <programlisting role="php"> +$link = mysql_connect('localhost', 'myname', 'secret'); +$db_list = mysql_list_dbs($link); + +while ($row = mysql_fetch_object($db_list)) { + echo $row->Database . "\n"; +} + </programlisting> + </example> + </para> + <para> + The above example would produce the following output: + <informalexample> + <programlisting> +database1 +database2 +database3 +... + </programlisting> + </informalexample> + </para> + <note> + <para> + The above code would just as easily work with + <function>mysql_fetch_row</function> or other similar functions. + </para> + </note> + <para> + For downward compatibility <function>mysql_listdbs</function> can + also be used. + </para> + <para>See also <function>mysql_db_name</function></para> + </refsect1> + </refentry> + + <refentry id="function.mysql-list-fields"> + <refnamediv> + <refname>mysql_list_fields</refname> + <refpurpose>List MySQL result fields</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_list_fields</function></funcdef> + <paramdef>string <parameter>database_name</parameter></paramdef> + <paramdef>string <parameter>table_name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_list_fields</function> retrieves information + about the given tablename. Arguments are the database name and + the table name. A result pointer is returned which can be used + with <function>mysql_field_flags</function>, + <function>mysql_field_len</function>, + <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> + <programlisting role="php"> +$link = mysql_connect('localhost', 'myname', 'secret'); + +$fields = mysql_list_fields("database1", "table1", $link); +$columns = mysql_num_fields($fields); + +for ($i = 0; $i < $columns; $i++) { + echo mysql_field_name($fields, $i) . "\n";; +} + </programlisting> + </example> + </para> + <para> + The above example would produce the following output: + <informalexample> + <programlisting> +field1 +field2 +field3 +... + </programlisting> + </informalexample> + </para> + <para> + 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> + + <refentry id="function.mysql-list-tables"> + <refnamediv> + <refname>mysql_list_tables</refname> + <refpurpose>List tables in a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_list_tables</function></funcdef> + <paramdef>string <parameter>database</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <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. + </para> + <para> + For downward compatibility <function>mysql_listtables</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-num-fields"> + <refnamediv> + <refname>mysql_num_fields</refname> + <refpurpose>Get number of fields in result</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_num_fields</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_num_fields</function> returns the number of + fields in a result set. + </para> + <para> + See also: + <function>mysql_db_query</function>, + <function>mysql_query</function>, + <function>mysql_fetch_field</function>, + <function>mysql_num_rows</function>.</para> + <para> + For downward compatibility <function>mysql_numfields</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-num-rows"> + <refnamediv> + <refname>mysql_num_rows</refname> + <refpurpose>Get number of rows in result</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_num_rows</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <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 + DELETE query, use <function>mysql_affected_rows</function>. + <example> + <title><function>mysql_num_rows</function> example</title> + <programlisting role="php"> +<?php + +$link = mysql_connect("localhost", "username", "password"); +mysql_select_db("database", $link); + +$result = mysql_query("SELECT * FROM table1", $link); +$num_rows = mysql_num_rows($result); + +echo "$num_rows Rows\n"; + +?> + </programlisting> + </example> + </para> + <para> + See also: + <function>mysql_affected_rows</function>, + <function>mysql_connect</function>, + <function>mysql_select_db</function> and + <function>mysql_query</function>. + </para> + <para> + For downward compatibility <function>mysql_numrows</function> can + also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-pconnect"> + <refnamediv> + <refname>mysql_pconnect</refname> + <refpurpose> + Open a persistent connection to a MySQL Server + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_pconnect</function></funcdef> + <paramdef>string + <parameter> + <optional>hostname + <optional>:port</optional> + <optional>:/path/to/socket</optional> + </optional> + </parameter> + </paramdef> + <paramdef>string + <parameter><optional>username</optional></parameter> + </paramdef> + <paramdef>string + <parameter><optional>password</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: A positive MySQL persistent link identifier on success, + or &false; on error. + </para> + <para> + <function>mysql_pconnect</function> establishes a connection + to a MySQL server. The following defaults are assumed for + missing optional parameters: <parameter>host:port</parameter> = + 'localhost:3306', <parameter>username</parameter> = name of the + user that owns the server process and + <parameter>password</parameter> = empty password. + </para> + <para> + The hostname string can also include a port + number. eg. "hostname:port" or a path to a socket + eg. ":/path/to/socket" for the localhost. + <note> + <para> + Support for ":port" was added in 3.0B4. + </para> + <para> + Support for the ":/path/to/socket" was added in + 3.0.10. + </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. + </para> + <para> + First, when connecting, the function would first try to find a + (persistent) link that's already open with the same host, + username and password. If one is found, an identifier for it + will be returned instead of opening a new connection. + </para> + <para> + Second, the connection to the SQL server will not be closed when + the execution of the script ends. Instead, the link will remain + open for future use (<function>mysql_close</function> will not + close links established by <function>mysql_pconnect</function>). + </para> + <para> + This type of links is therefore called 'persistent'. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-query"> + <refnamediv> + <refname>mysql_query</refname> + <refpurpose>Send a MySQL query</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>mysql_query</function></funcdef> + <paramdef>string <parameter>query</parameter></paramdef> + <paramdef>resource + <parameter><optional>link_identifier</optional></parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_query</function> sends a query to the currently + active database on the server that's associated with the + specified link identifier. If + <parameter>link_identifier</parameter> isn't specified, the last + opened link is assumed. If no link is open, the function tries + to establish a link as if <function>mysql_connect</function> was + called with no arguments, and use it. + </para> + <note> + <para> + The query string should not end with a semicolon. + </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 + 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. + </para> + <para> + The following query is syntactically invalid, so + <function>mysql_query</function> fails and returns &false;: + <example> + <title><function>mysql_query</function></title> + <programlisting role="php"> +<?php +$result = mysql_query ("SELECT * WHERE 1=1") + or die ("Invalid query"); +?> + </programlisting> + </example> + </para> + <para> + The following query is semantically invalid if + <literal>my_col</literal> is not a column in the table + <literal>my_tbl</literal>, so <function>mysql_query</function> + fails and returns &false;: + <example> + <title><function>mysql_query</function></title> + <programlisting role="php"> +<?php +$result = mysql_query ("SELECT my_col FROM my_tbl") + or die ("Invalid query"); +?> + </programlisting> + </example> + </para> + <para> + <function>mysql_query</function> will also fail and return &false; + if you don't have permission to access the table(s) referenced by + the query. + </para> + <para> + Assuming the query succeeds, you can call + <function>mysql_num_rows</function> to find out how many rows + were returned for a SELECT statment or + <function>mysql_affected_rows</function> to find out how many + rows were affected by a DELETE, INSERT, REPLACE, or UPDATE + statement. + </para> + <para> + 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 + result set, you can free the resources associated with it by + 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>, + <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 + <function>mysql_connect</function>. + </para> + </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>resource <function>mysql_unbuffered_query</function></funcdef> + <paramdef>string <parameter>query</parameter></paramdef> + <paramdef>resource + <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> + <refpurpose>Get result data</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>mysql_result</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>row</parameter></paramdef> + <paramdef>mixed + <parameter> + <optional>field</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_result</function> returns the contents of one + cell from a MySQL result set. The field argument can be the + field's offset, or the field's name, or the field's table dot + field's name (tabledname.fieldname). If the column name has been + aliased ('select foo as bar from...'), use the alias instead of + the column name. + </para> + <para> + When working on large result sets, you should consider using one + of the functions that fetch an entire row (specified below). As + these functions return the contents of multiple cells in one + function call, they're MUCH quicker than + <function>mysql_result</function>. Also, note that specifying a + numeric offset for the field argument is much quicker than + specifying a fieldname or tablename.fieldname argument. + </para> + <para> + Calls to <function>mysql_result</function> should not be mixed + with calls to other functions that deal with the result set. + </para> + <para> + Recommended high-performance alternatives: + <function>mysql_fetch_row</function>, + <function>mysql_fetch_array</function>, and + <function>mysql_fetch_object</function>. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-select-db"> + <refnamediv> + <refname>mysql_select_db</refname> + <refpurpose>Select a MySQL database</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>bool <function>mysql_select_db</function></funcdef> + <paramdef>string <parameter>database_name</parameter></paramdef> + <paramdef>resource + <parameter> + <optional>link_identifier</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns: &true; on success, &false; on error. + </para> + <para> + <function>mysql_select_db</function> sets the current active + database on the server that's associated with the specified link + 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. + </para> + <para> + Every subsequent call to <function>mysql_query</function> will be + made on the active database. + </para> + <para> See also: + <function>mysql_connect</function>, + <function>mysql_pconnect</function>, and + <function>mysql_query</function>. + </para> + <para> + For downward compatibility <function>mysql_selectdb</function> + can also be used. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-tablename"> + <refnamediv> + <refname>mysql_tablename</refname> + <refpurpose>Get table name of field</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_tablename</function></funcdef> + <paramdef>resource <parameter>result</parameter></paramdef> + <paramdef>int <parameter>i</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_tablename</function> takes a result pointer + returned by the <function>mysql_list_tables</function> function + as well as an integer index and returns the name of a table. The + <function>mysql_num_rows</function> function may be used to + determine the number of tables in the result pointer. + <example> + <title><function>mysql_tablename</function> Example</title> + <programlisting role="php"> +<?php +mysql_connect ("localhost:3306"); +$result = mysql_list_tables ("wisconsin"); +$i = 0; +while ($i < mysql_num_rows ($result)) { + $tb_names[$i] = mysql_tablename ($result, $i); + echo $tb_names[$i] . "<BR>"; + $i++; +} +?> + </programlisting> + </example> + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-client-info"> + <refnamediv> + <refname>mysql_get_client_info</refname> + <refpurpose>Get MySQL client info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_get_client_info</function></funcdef> + <void/> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_client_info</function> returns a string that represents + the client library version. + </para> + <para> + <function>mysql_get_client_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-host-info"> + <refnamediv> + <refname>mysql_get_host_info</refname> + <refpurpose>Get MySQL host info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>mysql_get_host_info</function></funcdef> + <paramdef>resource <parameter><optional>link_identifier</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_host_info</function> returns a string + describing the type of connection in use for the connection + <parameter>link_identifier</parameter>, including the server host name. + If <parameter>link_identifier</parameter> is omited, the last opened + connection will be used. + </para> + <para> + <function>mysql_get_host_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-proto-info"> + <refnamediv> + <refname>mysql_get_proto_info</refname> + <refpurpose>Get MySQL protocol info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_get_proto_info</function></funcdef> + <paramdef>resource <parameter><optional>link_identifier</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_proto_info</function> returns the protocol version + used by connection <parameter>link_identifier</parameter>. + If <parameter>link_identifier</parameter> is omited, the last opened + connection will be used. + </para> + <para> + <function>mysql_get_proto_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + + <refentry id="function.mysql-get-server-info"> + <refnamediv> + <refname>mysql_get_server_info</refname> + <refpurpose>Get MySQL server info</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>mysql_get_server_info</function></funcdef> + <paramdef>resource <parameter><optional>link_identifier</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>mysql_get_server_info</function> returns the server version + used by connection <parameter>link_identifier</parameter>. + If <parameter>link_identifier</parameter> is omited, the last opened + connection will be used. + </para> + <para> + <function>mysql_get_server_info</function> was added in PHP 4.0.5. + </para> + </refsect1> + </refentry> + </reference> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../../manual.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +vi: et:ts=1:sw=1:textwidth=78:syntax=sgml +-->