<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
 <reference id="ref.mysql">
  <title>MySQL Functions</title>
  <titleabbrev>MySQL</titleabbrev>

  <partintro>
   <para id="mysql.intro">
    These functions allow you to access MySQL database servers.
    More information about MySQL can be found at <ulink
    url="&url.mysql;">&url.mysql;</ulink>.
   </para>
   <para>
    Documentation for MySQL can be found at <ulink
    url="&url.mysql.docs;">&url.mysql.docs;</ulink>.
   </para>
   
   <section id="mysql.requirements">
    <title>Requirements</title>
    <para>
     In order to have these functions available, you must compile PHP with
     MySQL support
    </para>
   </section>
    
   <section id="mysql.installation">
    <title>Installation</title>
    <para>
     By using the <option role="configure">--with-mysql</option> configuration
     option you enable PHP to access MySQL databases. If you use this option
     without specifying the path to MySQL, PHP will use the built-in MySQL
     client libraries. With PHP4 MySQL support is always eanbled; if you don't
     specify the configure option, the bundled libraries are used. 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.
    </para>
   </section>

   <section id="mysql.configuration">
    <title>Runtime Configuration</title>
    <para>
     The behaviour of the MySQL functions is affected by settings in the
     global <link linkend="configuration.file">configuration file</link> &php.ini;.
     <table>
      <title>MySQL Configuration 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>
        <row>
         <entry>mysql.default_password</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>
    Here is a short explanation of the configuration directives.
    <variablelist>

     <varlistentry id="ini.mysql.allow-persistent">
      <term>
       <parameter>mysql.allow_persistent</parameter>
       <type>boolean</type>
      </term>
      <listitem>
       <para>
        Wether to allow
        <link linkend="features.persistent-connections">persistent connections</link>
        to MySQL.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.mysql.max-persistent">
      <term>
       <parameter>mysql.max_persistent</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
        The maximum number of persistent MySQL connections per
        process.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.mysql.max-links">
      <term>
       <parameter>mysql.max_links</parameter>
       <type>integer</type>
      </term>
      <listitem>
       <para>
        The maximum number of MySQL connections per process, including
        persistent connections.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ini.mysql.default-port">
      <term>
       <parameter>mysql.default_port</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        The default TCP port number to use when connecting to
        the database server if no other port is specified. If
        no default is specified, the port will be obtained
        from the <literal>MYSQL_TCP_PORT</literal> environment
        variable, the <literal>mysql-tcp</literal> entry in
        <filename>/etc/services</filename> or the compile-time
        <literal>MYSQL_PORT</literal> constant, in that order. Win32
        will only use the <literal>MYSQL_PORT</literal> constant.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.mysql.default-socket">
      <term>
       <parameter>mysql.default_socket</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        The default socket name to use when connecting to a local
        database server if no other socket name is specified.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="ini.mysql.default-host">
      <term>
       <parameter>mysql.default_host</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        The default server host to use when connecting to the database
        server if no other host is specified. Doesn't apply in
        <link linkend="ini.safe-mode">safe mode</link>.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.mysql.default-user">
      <term>
       <parameter>mysql.default_user</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        The default user name to use when connecting to the database
        server if no other name is specified. Doesn't apply in
        <link linkend="ini.safe-mode">safe mode</link>.
       </para>
      </listitem>
     </varlistentry>
     
     <varlistentry id="ini.mysql.default-password">
      <term>
       <parameter>mysql.default_password</parameter>
       <type>string</type>
      </term>
      <listitem>
       <para>
        The default password to use when connecting to the database
        server if no other password is specified. Doesn't apply in
        <link linkend="ini.safe-mode">safe mode</link>.
       </para>
      </listitem>
     </varlistentry>
     
    </variablelist>
    </para>
   </section>

   <section id="mysql.resources">
    <title>Resource types</title>
    <para>
     There are two resource types used in the MySQL module. The first one
     is the link identifier for a database connection, the second a resource
     which helds the result of a query.
    </para>
   </section>

   <section id="mysql.constants">
    <title>Predefined constants</title>
    <para>
     The function <function>mysql_fetch_array</function> uses a constant for
     the different types of result arrays. The following constants are
     defined:
     <table>
      <title>MySQL fetch constants</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>constant</entry>
         <entry>meaning</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry>MYSQL_ASSOC</entry>
         <entry>
          Columns are returned into the array having the fieldname as the array
          index.
         </entry>
        </row>
        <row>
         <entry>MYSQL_BOTH</entry>
         <entry>
          Columns are returned into the array having both a numerical index
          and the fieldname as the array index.
         </entry>
        </row>
        <row>
         <entry>MYSQL_NUM</entry>
         <entry>
          Columns are returned into the array having a numerical index to the
          fields. This index starts with 0, the first field in the result.
         </entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
   </section>
    
   <section id="mysql.examples">
    <title>Examples</title>
    <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_user", "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>
   </section>
  </partintro>

&reference.mysql.functions;

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