<reference id="ref.mysql">
  <title>MySQL functions</title>
  <titleabbrev>MySQL</titleabbrev>
  <partintro>
   <simpara>
    These functions allow you to access MySQL database servers.
   <simpara>
    More information about MySQL can be found at <ulink
      url="http://www.mysql.com/">http://www.mysql.com/</ulink>.
  </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>
     <funcdef>int <function>mysql_affected_rows</function></funcdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para> 
     <function>mysql_affected_rows</function> returns the number of
     rows affected by the last INSERT, UPDATE or DELETE query on the
     server associated with the specified link identifier.  If the
     link identifier isn't specified, the last opened link is assumed.
    <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>
     This command is not effective for SELECT statements, only on
     statements which modify records. To retrieve the number of rows
     returned from a SELECT, use <function>mysql_num_rows</function>.
   </refsect1>
  </refentry>

  <refentry id="function.mysql-close">
   <refnamediv>
    <refname>mysql_close</refname>
    <refpurpose>close MySQL connection</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mysql_close</function></funcdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns: true on success, false on error
    <para> 
     <function>mysql_close</function> closes the link to a MySQL
     database that's associated with the specified link identifier.
     If the link identifier isn't specified, the last opened link is
     assumed.
    <para> 
     Note that this isn't usually necessary, as non-persistent open
     links are automatically closed at the end of the script's
     execution.
    <para> 
     <function>mysql_close</function> will not close persistent links
     generated by mysql_pconnect().
    <para> 
     See also: <function>mysql_connect</function>, and
               <function>mysql_pconnect</function>.
   </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>
     <funcdef>int <function>mysql_connect</function></funcdef>
     <paramdef>string <parameter><optional>hostname</optional>
                      <optional>:port</optional></parameter>
                      </paramdef>
     <paramdef>string <parameter><optional>username</optional>
                      </parameter></paramdef>
     <paramdef>string <parameter><optional>password</optional>
                      </parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns: A positive MySQL link identifier on success, or false on
     error.
    <para> 
     <function>mysql_connect</function> establishes a connection to a
     MySQL server.  All of the arguments are optional, and if they're
     missing, defaults are assumed ('localhost', user name of the user
     that owns the server process, empty password).  The hostname
     string can also include a port number.
     eg. &quot;hostname:port&quot;
    <para> 
     In case 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> 
     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> 
     See also <function>mysql_pconnect</function>, and 
              <function>mysql_close</function>.
   </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>
     <funcdef>int <function>mysql_create_db</function></funcdef>
     <paramdef>string <parameter>database name</parameter></paramdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para> 
     <function>mysql_create_db</function> attempts to create a new
     database on the server associated with the specified link
     identifier.
    <para> 
     See also: <function>mysql_drop_db</function>.  For downwards
     compatibility <function>mysql_createdb</function> can also be
     used.
   </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>
     <funcdef>int <function>mysql_data_seek</function></funcdef>
     <paramdef>int <parameter>result_identifier</parameter></paramdef>
     <paramdef>int <parameter>row_number</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns: true on success, false on failure
    <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.
   </refsect1>
  </refentry>

<!--
  <refentry id="function.mysql-dbname">
   <refnamediv>
    <refname>mysql_dbname</refname>
    <refpurpose>get current MySQL database name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>mysql_dbname</function></funcdef>
     <paramdef>string <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>i</parameter></paramdef>
    </funcsynopsis>
    <para> 
     <function>mysql_dbname</function> returns the database name
     stored in position <parameter>i</parameter> of the result pointer
     returned from the <function>mysql_list_dbs</function>
     function. The <function>mysql_num_rows</function> function can be
     used to determine how many database names are available.
   </refsect1>
  </refentry>
-->

  <refentry id="function.mysql-db-query">
   <refnamediv>
    <refname>mysql_db_query</refname>
    <refpurpose>Send an MySQL query to MySQL</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mysql_db_query</function></funcdef>
     <paramdef>string <parameter>database</parameter></paramdef>
     <paramdef>string <parameter>query</parameter></paramdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns: A positive MySQL result identifier to the query result,
     or false on error.
    <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> 
     See also <function>mysql_connect</function>.  For downwards
     compatibility <function>mysql</function> can also be used.
   </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>
     <funcdef>int <function>mysql_drop_db</function></funcdef>
     <paramdef>string <parameter>database_name</parameter></paramdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns: true on success, false on failure.  
    <para> 
     <function>mysql_drop_db</function> attempts to drop (remove) an
     entire database from the server associated with the specified
     link identifier.
    <para> 
     See also: <function>mysql_create_db</function>. For downward
     compatibility <function>mysql_dropdb</function> can also be used.
   </refsect1>
  </refentry>


  <refentry id="function.mysql-errno">
   <refnamediv>
    <refname>mysql_errno</refname> 
    <refpurpose>Returns the number of the error message from previous
     MySQL operation</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mysql_errno</function></funcdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para>
     Errors coming back from the mySQL database backend no longer
     issue warnings. Instead, use these functions to retrieve the
     error number.

     <informalexample>
      <programlisting role=php>
&lt;?php
mysql_connect("marliesle");
echo mysql_errno().": ".mysql_error()."&lt;BR>";
mysql_select_db("nonexistentdb");
echo mysql_errno().": ".mysql_error()."&lt;BR>";
$conn = mysql_query("SELECT * FROM nonexistenttable");
echo mysql_errno().": ".mysql_error()."&lt;BR>";
?>
</programlisting>
     </informalexample>

    <para> 
     See also: <function>mysql_error</function>
   </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>
     <funcdef>string <function>mysql_error</function></funcdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para>
     Errors coming back from the mySQL database backend no longer
     issue warnings. Instead, use these functions to retrieve the
     error string.

     <informalexample>
      <programlisting role=php>
&lt;?php
mysql_connect("marliesle");
echo mysql_errno().": ".mysql_error()."&lt;BR>";
mysql_select_db("nonexistentdb");
echo mysql_errno().": ".mysql_error()."&lt;BR>";
$conn = mysql_query("SELECT * FROM nonexistenttable");
echo mysql_errno().": ".mysql_error()."&lt;BR>";
?>
</programlisting>
     </informalexample>

    <para> 
     See also: <function>mysql_errno</function>
   </refsect1>
  </refentry>

  <refentry id="function.mysql-fetch-array">
   <refnamediv>
    <refname>mysql_fetch_array</refname>
    <refpurpose>Fetch a result row as an associative array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>mysql_fetch_array</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter><optional>result_typ</optional></parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns an array that corresponds to the fetched row, or false
     if there are no more rows.
    <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>
     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>
     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>
     The optional second argument <parameter>result_typ</parameter> in
     <function>mysql_fetch_array</function> is a constant and can take
     the following values: MYSQL_ASSOC, MYSQL_NUM, and MYSQL_BOTH.
    <para>
     For further details, also see
     <function>mysql_fetch_row</function>
    </para>
    <example>
     <title>mysql fetch array</title>
     <programlisting role=php>
&lt;?php 
mysql_connect($host,$user,$password);
$result = mysql_db_query("database","select * from table");
while($row = mysql_fetch_array($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>
     <funcdef>object <function>mysql_fetch_field</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter><optional>field_offset</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns an object containing field information.  
    <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>
     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>
     See also <function>mysql_field_seek</function>

   </refsect1>
  </refentry>

  <refentry id="function.mysql-fetch-lengths">
   <refnamediv>
    <refname>mysql_fetch_lengths</refname>
    <refpurpose>Get max data size of each output in a
     result</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>mysql_fetch_lengths</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
    </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>
     <function>mysql_fetch_lengths</function> stores the lengths of
     each result column in the last row returned by
     <function>mysql_fetch_row</function> in an array, starting at
     offset 0.
    <para> 
     See also: <function>mysql_fetch_row</function>.
   </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>
     <funcdef>object <function>mysql_fetch_object</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter><optional>result_typ</optional></parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns an object with properties that correspond to the fetched
     row, or false if there are no more rows.
    <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>
     The optional argument <parameter>result_typ</parameter> is a
     constant and can take the following values: MYSQL_ASSOC,
     MYSQL_NUM, and MYSQL_BOTH.
    <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>mysql fetch object</title>
     <programlisting role=php>
&lt;?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> See also: <function>mysql_fetch_array</function> and
                     <function>mysql_fetch_row</function>.
   </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>
     <funcdef>array <function>mysql_fetch_row</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns: An array that corresponds to the fetched row, or false
     if there are no more rows.
    <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>
     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>
     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>.
   </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>
     <funcdef>string <function>mysql_field_name</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>field_index</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>mysql_field_name</function> returns the name of the
     specified field. Arguments to the function is the result
     identifier and the field index, ie.
     <literal>mysql_field_name($result,2);</literal>
    <para>
     Will return the name of the second field in the result associated
     with the result identifier.
    <para>
     For downwards compatibility <function>mysql_fieldname</function>
     can also be used.
   </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>
     <funcdef>int <function>mysql_field_seek</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>field_offset</parameter></paramdef>
    </funcsynopsis>
    <para>
     Seeks to the specified field offset.  If the next call to
     <function>mysql_fetch_field</function> won't include a field
     offset, this field would be returned.
    <para>
     See also: <function>mysql_fetch_field</function>.
   </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>
     <funcdef>string <function>mysql_field_table</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>field_offset</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Get the table name for field. For downward compatibility
     <function>mysql_fieldtable</function> can also be used.
   </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>
     <funcdef>string <function>mysql_field_type</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>field_offset</parameter></paramdef>
    </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. This will be one of
     "int", "real", "string", "blob", or others as detailed in the
     MySQL documentation.
 
    <example>
     <title>mysql field types</title>
     <programlisting role=php>
&lt;?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 &lt;BR>";
echo "The table has the following fields &lt;BR>"; 
while ($i &lt; $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."&lt;BR>";
    $i++;
}
mysql_close();
?>
</programlisting>
    </example>

    <para> 
     For downward compatibility <function>mysql_fieldtype</function>
     can also be used.

   </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>
     <funcdef>string <function>mysql_field_flags</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>field_offset</parameter></paramdef>
    </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>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> 
     For downward compatibility <function>mysql_fieldflags</function>
     can also be used.
   </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>
     <funcdef>int <function>mysql_field_len</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>field_offset</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>mysql_field_len</function> returns the length of the
     specified field.  For downward compatibility
     <function>mysql_fieldlen</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>
     <funcdef>int <function>mysql_free_result</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>mysql_free_result</function> only needs to be called if
     you are worried about using too much memory while your script is
     running. All associated result memory for the specified result
     identifier will automatically be freed.
    <para>
     For downward compatibility <function>mysql_freeresult</function>
     can also be used.
   </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>
     <funcdef>int <function>mysql_insert_id</function></funcdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para> 
     <function>mysql_insert_id</function> returns the ID generated for
     an AUTO_INCREMENTED field. This function takes no arguments. It
     will return the auto-generated ID returned by the last INSERT
     query performed.
   </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>
     <funcdef>int <function>mysql_list_fields</function></funcdef>
     <paramdef>string <parameter>database_name</parameter></paramdef>
     <paramdef>string <parameter>table_name</parameter></paramdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </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>
     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>
     For downward compatibility <function>mysql_listfields</function>
     can also be used.
   </refsect1>
  </refentry>


  <refentry id="function.mysql-list-dbs">
   <refnamediv>
    <refname>mysql_list_dbs</refname>
    <refpurpose>List databases available on on MySQL server</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mysql_list_dbs</function></funcdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </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>
     For downward compatibility <function>mysql_listdbs</function> can
     also be used.
   </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>
     <funcdef>int <function>mysql_list_tables</function></funcdef>
     <paramdef>string <parameter>database</parameter></paramdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para> 
     <function>mysql_list_tables</function> takes a database name and
     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>
     For downward compatibility <function>mysql_listtables</function>
     can also be used.
   </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>
     <funcdef>int <function>mysql_num_fields</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
    </funcsynopsis>
    <para> 
     <function>mysql_num_fields</function> returns the number of
     fields in a result set.
    <para> 
     See also: 
     <function>mysql_db_query</function>,
     <function>mysql_query</function>,
     <function>mysql_fetch_field</function>,
     <function>mysql_num_rows</function>.
    <para>
     For downward compatibility <function>mysql_numfields</function>
     can also be used.
   </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>
     <funcdef>int <function>mysql_num_rows</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>mysql_num_rows</function> returns the number of rows in
     a result set.
    <para>
     See also:  
     <function>mysql_db_query</function>, 
     <function>mysql_query</function> and, 
     <function>mysql_fetch_row</function>.
    <para>
     For downward compatibility <function>mysql_numrows</function> can
     also be used.
   </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>
     <funcdef>int <function>mysql_pconnect</function></funcdef>
     <paramdef>string <parameter><optional>hostname</optional>
                                 <optional>:port</optional>  
                      </parameter></paramdef>
     <paramdef>string <parameter><optional>username</optional>
                      </parameter></paramdef>
     <paramdef>string <parameter><optional>password</optional>
                      </parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns: A positive MySQL persistent link identifier on success,
     or false on error
    <para>
     <function>mysql_pconnect</function> acts very much like
     <function>mysql_connect</function> with two major differences.
    <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> 
     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 <literal>mysql_pconnect()</literal>).
    <para> 
     This type of links is therefore called 'persistent'.
   </refsect1>
  </refentry>

  <refentry id="function.mysql-query">
   <refnamediv>
    <refname>mysql_query</refname>
    <refpurpose>Send an SQL query to MySQL</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mysql_query</function></funcdef>
     <paramdef>string <parameter>query</parameter></paramdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </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, and use it.
    <para>
     The query string should not end with a semicolon.
    <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>
     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">
&lt;?php
$result = mysql_query ("SELECT * WHERE 1=1")
    or die ("Invalid query");
?>
      </programlisting>
     </example>

    <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">
&lt;?php
$result = mysql_query ("SELECT * WHERE 1=1")
    or die ("Invalid query");
?>
      </programlisting>
     </example>
    <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">
&lt;?php
$result = mysql_query ("SELECT my_col FROM my_tbl")
    or die ("Invalid query");
?>
      </programlisting>
     </example>

    <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>
     Assuming the query succeeds, you can call
     <function>mysql_affected_rows</function> to find out how many
     rows were affected (for DELETE, INSERT, REPLACE, or UPDATE
     statements).  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>.
    <para>
     See also: <function>mysql_affected_rows</function>,
     <function>mysql_db_query</function>,
     <function>mysql_free_result</function>,
     <function>mysql_result</function>,
     <function>mysql_select_db</function>, and
     <function>mysql_connect</function>.
   </refsect1>
  </refentry>

  <refentry id="function.mysql-result">
   <refnamediv>
    <refname>mysql_result</refname>
    <refpurpose>Get result data</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mysql_result</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>row</parameter></paramdef>
     <paramdef>mixed <parameter>field</parameter></paramdef>
    </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 (fieldname.tablename).  If the column name has been
     aliased ('select foo as bar from...'), use the alias instead of
     the column name.
    <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>
     Calls <function>mysql_result</function> should not be mixed
     with calls to other functions that deal with the result set.
    <para>
     Recommended high-performance alternatives:
     <function>mysql_fetch_row</function>, 
     <function>mysql_fetch_array</function>, and
     <function>mysql_fetch_object</function>.
   </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>
     <funcdef>int <function>mysql_select_db</function></funcdef>
     <paramdef>string <parameter>database_name</parameter></paramdef>
     <paramdef>int <parameter><optional>link_identifier</optional>
                   </parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns: true on success, false on error
    <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>
     Every subsequent call to <function>mysql_query</function> will be
     made on the active database.
    <para> See also:
     <function>mysql_connect</function>, 
     <function>mysql_pconnect</function>, and
     <function>mysql_query</function>
    <para>
     For downward compatibility <function>mysql_selectdb</function>
     can also be used.
   </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>
     <funcdef>string <function>mysql_tablename</function></funcdef>
     <paramdef>int <parameter>result</parameter></paramdef>
     <paramdef>int <parameter>i</parameter></paramdef>
    </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>mysql_tablename() example</title>
      <programlisting role=php>
&lt;?php 
mysql_connect ("localhost:3306");
$result = mysql_listtables ("wisconsin");
$i = 0;
while ($i &lt; mysql_num_rows ($result)) {
    $tb_names[$i] = mysql_tablename ($result, $i);
    echo $tb_names[$i] . "&lt;BR>";
    $i++;
}
?>
</programlisting></example>

   </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:
-->