php-doc-en/reference/oci8/functions/oci-connect.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<refentry xml:id="function.oci-connect" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>oci_connect</refname>
  <refpurpose>Establishes a connection to the Oracle server</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>oci_connect</methodname>
   <methodparam><type>string</type><parameter>username</parameter></methodparam>
   <methodparam><type>string</type><parameter>password</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>db</parameter></methodparam>
   <methodparam choice="opt"><type>string</type><parameter>charset</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>session_mode</parameter></methodparam>
  </methodsynopsis>
  <para>
   Returns a connection identifier needed for most other OCI calls. 
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>username</parameter></term>
     <listitem>
      <para>
       The Oracle user name.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>password</parameter></term>
     <listitem>
      <para>
       The password for <parameter>username</parameter>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>db</parameter></term>
     <listitem>
      <para>
       This optional parameter can either contain the name of the local
       Oracle instance or the name of the entry in
       <filename>tnsnames.ora</filename>.
      </para>
      <para>
       If the not specified, PHP uses environment variables
       <constant>ORACLE_SID</constant> and <constant>TWO_TASK</constant> to
       determine the name of local <literal>Oracle instance</literal> and
       location of <filename>tnsnames.ora</filename> accordingly.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>charset</parameter></term>
     <listitem>
      &oci.charset;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>session_mode</parameter></term>
     <listitem>
      <para>
       This parameter is available since version 1.1 and accepts the
       following values: <constant>OCI_DEFAULT</constant>,
       <constant>OCI_SYSOPER</constant> and <constant>OCI_SYSDBA</constant>.
       If either <constant>OCI_SYSOPER</constant> or
       <constant>OCI_SYSDBA</constant> were specified, this function will try
       to establish privileged connection using external credentials. 
       Privileged connections are disabled by default. To enable them you
       need to set <link
        linkend="ini.oci8.privileged-connect">oci8.privileged_connect</link>
       to <literal>On</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a connection identifier or &false; on error.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>oci_connect</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
echo "<pre>";
$db = "";

$c1 = oci_connect("scott", "tiger", $db);
$c2 = oci_connect("scott", "tiger", $db);

function create_table($conn)
{
  $stmt = oci_parse($conn, "create table scott.hallo (test varchar2(64))");
  oci_execute($stmt);
  echo $conn . " created table\n\n";
}

function drop_table($conn)
{
  $stmt = oci_parse($conn, "drop table scott.hallo");
  oci_execute($stmt);
  echo $conn . " dropped table\n\n";
}

function insert_data($conn)
{
  $stmt = oci_parse($conn, "insert into scott.hallo
            values('$conn' || ' ' || to_char(sysdate,'DD-MON-YY HH24:MI:SS'))");
  oci_execute($stmt, OCI_DEFAULT);
  echo $conn . " inserted hallo\n\n";
}

function delete_data($conn)
{
  $stmt = oci_parse($conn, "delete from scott.hallo");
  oci_execute($stmt, OCI_DEFAULT);
  echo $conn . " deleted hallo\n\n";
}

function commit($conn)
{
  oci_commit($conn);
  echo $conn . " committed\n\n";
}

function rollback($conn)
{
  oci_rollback($conn);
  echo $conn . " rollback\n\n";
}

function select_data($conn)
{
  $stmt = oci_parse($conn, "select * from scott.hallo");
  oci_execute($stmt, OCI_DEFAULT);
  echo $conn."----selecting\n\n";
  while (oci_fetch($stmt)) {
    echo $conn . " [" . oci_result($stmt, "TEST") . "]\n\n";
  }
  echo $conn . "----done\n\n";
}

create_table($c1);
insert_data($c1);   // Insert a row using c1
insert_data($c2);   // Insert a row using c2

select_data($c1);   // Results of both inserts are returned
select_data($c2);

rollback($c1);      // Rollback using c1

select_data($c1);   // Both inserts have been rolled back
select_data($c2);

insert_data($c2);   // Insert a row using c2
commit($c2);        // Commit using c2

select_data($c1);   // Result of c2 insert is returned

delete_data($c1);   // Delete all rows in table using c1
select_data($c1);   // No rows returned
select_data($c2);   // No rows returned
commit($c1);        // Commit using c1

select_data($c1);   // No rows returned
select_data($c2);   // No rows returned

drop_table($c1);
echo "</pre>";
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    If you're using PHP with Oracle Instant Client, you can use easy connect
    naming method described here:
    <link xlink:href="&url.oracle.oic.connect;">&url.oracle.oic.connect;</link>.
    Basically this means you can specify "//db_host[:port]/database_name"
    as database name. But if you want to use the old way of naming you
    <emphasis>must</emphasis> set either <constant>ORACLE_HOME</constant> or
    <constant>TNS_ADMIN</constant>.
   </simpara>
  </note>
  <note>
   <simpara>
    The second and subsequent calls to <function>oci_connect</function>
    with the same parameters will return the connection handle returned
    from the first call. This means that queries issued against one
    handle are also applied to the other handles, because they are the
    <emphasis>same</emphasis> handle. This behaviour is demonstrated in
    Example 1 below. If you require two handles to be transactionally
    isolated from each other, you should use
    <function>oci_new_connect</function> instead.
   </simpara>
  </note>
  <note>
   <para>
    In PHP versions before 5.0.0 you must use <function>ocilogon</function> instead.
    This name still can be used, it was left as the alias of
    <function>oci_connect</function> for downwards compatability.
    This, however, is deprecated and not recommended.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>oci_pconnect</function></member>
    <member><function>oci_new_connect</function></member>
    <member><function>oci_close</function></member>
   </simplelist>
  </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:"~/.phpdoc/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
-->