php-doc-en/reference/dbx/functions/dbx-connect.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
  <refentry id="function.dbx-connect">
   <refnamediv>
    <refname>dbx_connect</refname>
    <refpurpose>Open a connection/database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>object</type><methodname>dbx_connect</methodname>
      <methodparam><type>mixed</type><parameter>module</parameter></methodparam>
      <methodparam><type>string</type><parameter>host</parameter></methodparam>
      <methodparam><type>string</type><parameter>database</parameter></methodparam>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>persistent</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>dbx_connect</function> returns an object on success, &false; on
     error. If a connection has been made but the database could not be 
     selected, the connection is closed and &false; is returned. 
     The <parameter>persistent</parameter> parameter can be set to 
     <constant>DBX_PERSISTENT</constant>, if so, a persistent connection will be
     created.
    </simpara>
    <simpara>
     The <parameter>module</parameter> parameter can be either a string or a
     constant, though the latter form is preferred. The possible values are 
     given below, but keep in mind that they only work if the module is 
     actually loaded.
    </simpara>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_MYSQL</constant> or "mysql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_ODBC</constant> or "odbc"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_PGSQL</constant> or "pgsql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_MSSQL</constant> or "mssql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_FBSQL</constant> or "fbsql" (available from PHP 4.1.0)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_SYBASECT</constant> or "sybase_ct" (available from PHP
        4.2.0)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_OCI8</constant> or "oci8" (available from PHP 4.3.0)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_SQLITE</constant> or "sqlite" (PHP 5)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     The <parameter>host</parameter>, <parameter>database</parameter>, 
     <parameter>username</parameter> and <parameter>password</parameter> 
     parameters are expected, but not always used depending on the connect
     functions for the abstracted module.
    </para>
    <para>
     The returned <varname>object</varname> has three properties:
     <variablelist>
      <varlistentry>
       <term>
        <property>database</property>
       </term>
       <listitem>
        <simpara>
         It is the name of the currently selected database. 
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>handle</property>
       </term>
       <listitem>
        <para>
         It is a valid handle for the connected database, and as such it can be
         used in module-specific functions (if required).
         <informalexample>
          <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password");
mysql_close($link->handle); // dbx_close($link) would be better here
?>
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>module</property>
       </term>
       <listitem>
        <simpara>
         It is used internally by dbx only, and is actually the module number
         mentioned above.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
    <para>
     <example>
      <title><function>dbx_connect</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect(DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT)
    or die("Could not connect");

echo "Connected successfully";
dbx_close($link);
?>
]]>
      </programlisting>
     </example>
     <note>
      <para>
       Always refer to the module-specific documentation as well.
      </para>
     </note>
    </para>
    <para>
     See also <function>dbx_close</function>.
    </para>
   </refsect1>
  </refentry>

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