<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.88 $ -->
 <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 PHP 3 and PHP 4
    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>
    The behaviour of the MySQL functions is affected by settings in the global
    <link linkend="configuration">configuration</link> file.
    <table>
     <title><link linkend="ini.sect.mysql">MySQL Configuration </link> Options</title>
     <tgroup cols="3">
      <thead>
       <row>
        <entry>Name</entry>
        <entry>Default</entry>
        <entry>Changeable</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>mysql.allow_persistent</entry>
        <entry>"On"</entry>
        <entry>PHP_INI_SYSTEM</entry>
       </row>
       <row>
        <entry>mysql.max_persistent</entry>
        <entry>"-1"</entry>
        <entry>PHP_INI_SYSTEM</entry>
       </row>
       <row>
        <entry>mysql.max_links</entry>
        <entry>"-1"</entry>
        <entry>PHP_INI_SYSTEM</entry>
       </row>
       <row>
        <entry>mysql.default_port</entry>
        <entry>NULL</entry>
        <entry>PHP_INI_ALL</entry>
       </row>
       <row>
        <entry>mysql.default_socket</entry>
        <entry>NULL</entry>
        <entry>PHP_INI_ALL</entry>
       </row>
       <row>
        <entry>mysql.default_host</entry>
        <entry>NULL</entry>
        <entry>PHP_INI_ALL</entry>
       </row>
       <row>
        <entry>mysql.default_user</entry>
        <entry>NULL</entry>
        <entry>PHP_INI_ALL</entry>
       </row>
      </tbody>
     </tgroup>
    </table>
    For further details and definition of the PHP_INI_* constants see <function>ini_set</function>.
   </para>
   <para>
    This simple example shows how to connect, execute a query, print
    resulting rows and disconnect from a MySQL database.
    <example>
     <title>MySQL extension overview example</title>
     <programlisting role="php">
<![CDATA[
<?php
// Connecting, selecting database
$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");

// Performing SQL query
$query = "SELECT * FROM my_table";
$result = mysql_query($query)
    or die("Query failed");

// Printing results in HTML
print "<table>\n";
while ($line = mysql_fetch_array($result, MYSQL_ASSOC)) {
    print "\t<tr>\n";
    foreach ($line as $col_value) {
        print "\t\t<td>$col_value</td>\n";
    }
    print "\t</tr>\n";
}
print "</table>\n";

// Free resultset
mysql_free_result($result);

// Closing connection
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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_affected_rows</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_change_user</methodname>
      <methodparam><type>string</type><parameter>user</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>
        database
       </parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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</parameter> parameter. 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? -->
     <!-- in PHP 3 int and in PHP 4 bool -->

    <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>
     <methodsynopsis>
      <type>bool</type><methodname>mysql_close</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     &return.success;
    </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">
<![CDATA[
<?php
    $link = mysql_connect("kraemer", "marliesle", "secret")
        or exit("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>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_connect</methodname>
      <methodparam choice="opt"><type>string</type><parameter>
        server
       </parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>
        username
       </parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>
        password
       </parameter></methodparam>
      <methodparam choice="opt"><type>bool</type><parameter>
        new_link
       </parameter></methodparam>
     </methodsynopsis>
    <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>server</parameter> =
     'localhost:3306', <parameter>username</parameter> = name of the
     user that owns the server process and
     <parameter>password</parameter> = empty password.
    </para>
    <para>
     The <parameter>server</parameter> parameter can also include a port
     number. eg. &quot;hostname:port&quot; or a path to a socket
     eg. &quot;:/path/to/socket&quot; for the localhost.
     <note>
      <para>
       Support for &quot;:port&quot; was added in PHP 3.0B4.
      </para>
      <para>
       Support for &quot;:/path/to/socket&quot; was added in
       PHP 3.0.10.
      </para>
      <para>
       You can suppress the error message on failure by prepending 
       a <link linkend="language.operators.errorcontrol">@</link>
       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. The <parameter>new_link</parameter> parameter modifies this 
     behavior and makes <function>mysql_connect</function> always open 
     a new link, even if <function>mysql_connect</function> was called 
     before with the same parameters.
    </para>
    <note>
     <para>
      The <parameter>new_link</parameter> parameter became available 
      in PHP 4.2.0
     </para>
    </note>
    <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">
<![CDATA[
<?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>
     <methodsynopsis>
      <type>bool</type><methodname>mysql_create_db</methodname>
      <methodparam><type>string</type><parameter>database name</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>mysql_create_db</function> attempts to create a new
     database on the server associated with the specified link
     identifier.
    </para>
    <para>
     &return.success;
    </para>
    <example>
     <title>MySQL create database example</title>
     <programlisting role="php">
<![CDATA[
<?php
    $link = mysql_pconnect("kron", "jutta", "geheim")
        or exit("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. This is deprecated, however.
    </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>
     <methodsynopsis>
      <type>bool</type><methodname>mysql_data_seek</methodname>
      <methodparam><type>resource</type><parameter>result_identifier</parameter></methodparam>
      <methodparam><type>int</type><parameter>row_number</parameter></methodparam>
     </methodsynopsis>
    <para>
     &return.success;
    </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">
<![CDATA[
<?php
    $link = mysql_pconnect("kron", "jutta", "geheim")
        or die("Could not connect");

    mysql_select_db("samp_db")
        or exit("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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_db_name</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>
        field
       </parameter></methodparam>
     </methodsynopsis>
    <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">
<![CDATA[
<?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>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_db_query</methodname>
      <methodparam><type>string</type><parameter>database</parameter></methodparam>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>bool</type><methodname>mysql_drop_db</methodname>
      <methodparam><type>string</type><parameter>database_name</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     &return.success;
    </para>
    <para>
     <function>mysql_drop_db</function> attempts to drop (remove) an
     entire database from the server associated with the specified
     link identifier.
    </para>
    <para>
     For downward compatibility <function>mysql_dropdb</function>
     can also be used. This is deprecated, however.
    </para>
    <para>
     See also: <function>mysql_create_db</function>.
    </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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_errno</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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">
<![CDATA[
<?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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_error</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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">
<![CDATA[
<?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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_escape_string</methodname>
      <methodparam><type>string</type><parameter>unescaped_string</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>array</type><methodname>mysql_fetch_array</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        result_type
       </parameter></methodparam>
     </methodsynopsis>
    <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 use the numeric index of the column or
     make an alias for the column. For aliased columns, you cannot
     access the contents with the original column name (by using
     <literal>'field'</literal> in this example).
     <informalexample>
      <programlisting role="sql">
<![CDATA[
select tone.field as foo ttwo.field as bar from tone, ttwo
]]>
      </programlisting>
     </informalexample>
    </para>
    <para>
     An important thing to note is that using
     <function>mysql_fetch_array</function> is <emphasis>not
     significantly</emphasis> slower than using
     <function>mysql_fetch_row</function>, while it provides
     a significant added value.
    </para>
    <para>
     The optional second argument <parameter>result_type</parameter>
     in <function>mysql_fetch_array</function> is a constant and can
     take the following values: MYSQL_ASSOC, MYSQL_NUM, and
     MYSQL_BOTH. This feature was added in PHP 3.0.7. MYSQL_BOTH
     is the default for this argument.
    </para>
    <para>
     By using MYSQL_BOTH, you'll get an array with both associative
     and number indices. Using MYSQL_ASSOC, you only get associative
     indices (as <function>mysql_fetch_assoc</function> works),
     using MYSQL_NUM, you only get number indices (as
     <function>mysql_fetch_row</function> works).
    </para>
    <para>
     For further details, see also
     <function>mysql_fetch_row</function> and
     <function>mysql_fetch_assoc</function>.
    </para>
    <example>
     <title><function>mysql_fetch_array</function> example</title>
     <programlisting role="php">
<![CDATA[
<?php
mysql_connect($host, $user, $password);
mysql_select_db("database");
$result = mysql_query("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>
     <methodsynopsis>
      <type>array</type><methodname>mysql_fetch_assoc</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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 either need to access the
     result with numeric indices by using
     <function>mysql_fetch_row</function> or add alias names.
     See the example at the <function>mysql_fetch_array</function>
     description about aliases.
    </para>
    <para>
     An important thing to note is that using
     <function>mysql_fetch_assoc</function> is <emphasis>not
     significantly</emphasis> 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">
<![CDATA[
<?php
mysql_connect($host, $user, $password);
mysql_select_db($database);
$query = "select * from table";
$result = mysql_query($query);
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>
     <methodsynopsis>
      <type>object</type><methodname>mysql_fetch_field</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        field_offset
       </parameter></methodparam>
     </methodsynopsis>
    <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">
<![CDATA[
<?php
mysql_connect('localhost:3306', $user, $password)
    or die ("Could not connect");
mysql_select_db("database");
$result = mysql_query("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>
     <methodsynopsis>
      <type>array</type><methodname>mysql_fetch_lengths</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>object</type><methodname>mysql_fetch_object</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>
        result_type
       </parameter></methodparam>
     </methodsynopsis>
    <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. See
     <function>mysql_fetch_array</function> for explanation
     of these constants.
    </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">
<![CDATA[
<?php
mysql_connect("hostname", "user", "password");
mysql_select_db($db);
$result = mysql_query("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>
     <methodsynopsis>
      <type>array</type><methodname>mysql_fetch_row</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_field_flags</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_offset</parameter></methodparam>
     </methodsynopsis>
    <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. This is deprecated, however.
    </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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_field_name</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_index</parameter></methodparam>
     </methodsynopsis>
    <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">
<![CDATA[
// The users table consists of three fields:
//   user_id
//   username
//   password.
$link = mysql_connect('localhost', $user, "secret");
mysql_select_db($dbname, $link)
    or die("Could not set $dbname");
$res = mysql_query("select * from users", $link);

echo mysql_field_name($res, 0) . "\n";
echo mysql_field_name($res, 2);
]]>
      </programlisting>
      <para>
       The above example would produce the following output:
       <screen>
<![CDATA[
user_id
password
]]>
       </screen>
      </para>
     </example>
    </para>
    <para>
     For downwards compatibility <function>mysql_fieldname</function>
     can also be used. This is deprecated, however.
    </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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_field_len</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_offset</parameter></methodparam>
     </methodsynopsis>
    <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. This is deprecated, however.
    </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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_field_seek</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_offset</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_field_table</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_offset</parameter></methodparam>
     </methodsynopsis>
    <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. This is deprecated, however.
    </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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_field_type</methodname>
      <methodparam><type>iresource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_offset</parameter></methodparam>
     </methodsynopsis>
    <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">
<![CDATA[
<?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. This is deprecated, however.
    </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>
     <methodsynopsis>
      <type>bool</type><methodname>mysql_free_result</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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>
    <para>
     &return.success;
    </para>
    <para>
     For downward compatibility <function>mysql_freeresult</function>
     can also be used. This is deprecated, however.
    </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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_insert_id</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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
     <function>mysql_insert_id</function> 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> (named <type>int</type> in PHP).
      If your AUTO_INCREMENT column has a column type of BIGINT,
      the value returned by <function>mysql_insert_id</function>
      will be incorrect. Instead, use the internal MySQL SQL function
      <literal>LAST_INSERT_ID()</literal> in an SQL query.
     </para>
    </warning>
   </refsect1>
  </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>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_list_dbs</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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, or any function for result tables.
    </para>
    <para>
     <example>
      <title><function>mysql_list_dbs</function> example</title>
      <programlisting role="php">
<![CDATA[
<?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>
      <para>
       The above example would produce the following output:
       <screen>
<![CDATA[
database1
database2
database3
...
]]>
       </screen>
      </para>
     </example>
    </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. This is deprecated however.
    </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>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_list_fields</methodname>
      <methodparam><type>string</type><parameter>database_name</parameter></methodparam>
      <methodparam><type>string</type><parameter>table_name</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <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>
    <para>
     <example>
      <title><function>mysql_list_fields</function> example</title>
      <programlisting role="php">
<![CDATA[
<?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>
      <para>
       The above example would produce the following output:
       <screen>
<![CDATA[
field1
field2
field3
...
]]>
       </screen>
      </para>
     </example>
    </para>
    <para>
     For downward compatibility <function>mysql_listfields</function>
     can also be used. This is deprecated however.
    </para>
    <!-- TODO: this is equiv. with 'select * from $table where &false;,'
         which implies you can better use the field-research functions
         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>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_list_tables</methodname>
      <methodparam><type>string</type><parameter>database</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>mysql_list_tables</function> takes a database name and
     returns a result pointer much like the
     <function>mysql_db_query</function> function. You can use the
     <function>mysql_tablename</function> function to extract the
     actual table names from the result pointer, or any other result
     table function.
    </para>
    <para>
     For downward compatibility <function>mysql_listtables</function>
     can also be used. This is deprecated however.
    </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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_num_fields</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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. This is deprecated however.
    </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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_num_rows</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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 affected by a INSERT, UPDATE or
     DELETE query, use <function>mysql_affected_rows</function>.
     <example>
      <title><function>mysql_num_rows</function> example</title>
      <programlisting role="php">
<![CDATA[
<?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. This is deprecated however.
    </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>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_pconnect</methodname>
      <methodparam choice="opt"><type>string</type><parameter>
        server
       </parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>username</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>password</parameter></methodparam>
     </methodsynopsis>
    <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>server</parameter> =
     'localhost:3306', <parameter>username</parameter> = name of the
     user that owns the server process and
     <parameter>password</parameter> = empty password.
    </para>
    <para>
     The <parameter>server</parameter> parameter can also include a port
     number. eg. &quot;hostname:port&quot; or a path to a socket
     eg. &quot;:/path/to/socket&quot; for the localhost.
     <note>
      <para>
       Support for &quot;:port&quot; was added in 3.0B4.
      </para>
      <para>
       Support for the &quot;:/path/to/socket&quot; 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 link is therefore called 'persistent'.
    </para>
    <note>
     <para>
      Note, that these kind of links only work if you are using
      a module version of PHP. See the
      <link linkend="features.persistent-connections">Persistent
      Database Connections</link> section for more information.
     </para>
    </note>
    <warning>
     <para>
      Using persistent connections can require a bit of tuning of your Apache
      and MySQL configurations to ensure that you do not exceed the number of
      connections allowed by MySQL.
     </para>
    </warning>
   </refsect1>
  </refentry>

  <refentry id="function.mysql-query">
   <refnamediv>
    <refname>mysql_query</refname>
    <refpurpose>Send a MySQL query</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_query</methodname>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <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>
     Only for SELECT,SHOW,EXPLAIN or DESCRIBE statements
     <function>mysql_query</function>
     returns a resource identifier or &false; if the query was
     not executed correctly. For other type of SQL statements,
     <function>mysql_query</function> returns &true; on success
     and &false; on error. A non-&false; return value
     means that the query was legal and could be executed by
     the server.  It does not indicate anything about the number of
     rows affected or returned. It is perfectly possible for a query
     to succeed but affect no rows or return no rows.
    </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">
<![CDATA[
<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">
<![CDATA[
<?php
$result = mysql_query("SELECT my_col FROM my_tbl")
    or exit ("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>
     Only for SELECT,SHOW,DESCRIBE or EXPLAIN statements,
     <function>mysql_query</function> 
     returns a new result identifier that you can pass to
     <function>mysql_fetch_array</function> and other
     functions dealing with result tables. When you are done with the
     result set, you can free the resources associated with it by
     calling <function>mysql_free_result</function>. Although, the
     memory will automatically be freed at the end of the script's
     execution.
    </para>
    <para>
     See also: <function>mysql_num_rows</function>
     <function>mysql_affected_rows</function>,
     <function>mysql_unbuffered_query</function>,
     <function>mysql_free_result</function>,
     <function>mysql_fetch_array</function>,
     <function>mysql_fetch_row</function>,
     <function>mysql_fetch_assoc</function>,
     <function>mysql_result</function>,
     <function>mysql_select_db</function>, and
     <function>mysql_connect</function>.
    </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>
     <methodsynopsis>
      <type>resource</type><methodname>mysql_unbuffered_query</methodname>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>mysql_unbuffered_query</function> sends a SQL query
     <parameter>query</parameter> 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.  When using multiple DB-connects, you
     have to specify the optional parameter
     <parameter>link_identifier</parameter>.
    </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>
     <methodsynopsis>
      <type>mixed</type><methodname>mysql_result</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row</parameter></methodparam>
      <methodparam choice="opt"><type>mixed</type><parameter>
        field
       </parameter></methodparam>
     </methodsynopsis>
    <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 name (tablename.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>
     <methodsynopsis>
      <type>bool</type><methodname>mysql_select_db</methodname>
      <methodparam><type>string</type><parameter>database_name</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>
        link_identifier
       </parameter></methodparam>
     </methodsynopsis>
    <para>
     &return.success;
    </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 without arguments, 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. This is deprecated however.
    </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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_tablename</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>i</parameter></methodparam>
     </methodsynopsis>
    <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">
<![CDATA[
<?php
mysql_connect("host");
$result = mysql_list_tables("wisconsin");
for ($i = 0; $i < mysql_num_rows($result); $i++) {
    $tb_names[$i] = mysql_tablename($result, $i);
    echo $tb_names[$i] . "<BR>";
}
?>
]]>
      </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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_get_client_info</methodname>
      <void/>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>mysql_get_host_info</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_get_proto_info</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>mysql_get_server_info</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <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
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->