<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 332026 $ -->

<refentry xml:id="function.cubrid-pconnect-with-url" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>cubrid_pconnect_with_url</refname>
  <refpurpose>Open a persistent connection to CUBRID server</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>cubrid_pconnect_with_url</methodname>
   <methodparam><type>string</type><parameter>conn_url</parameter></methodparam>  
   <methodparam choice="opt"><type>string</type><parameter>userid</parameter></methodparam>  
   <methodparam choice="opt"><type>string</type><parameter>passwd</parameter></methodparam>  
  </methodsynopsis>
  <para>
   Establishes a persistent connection to a CUBRID server.
  </para>
  <para>
   <function>cubrid_pconnect_with_url</function> acts very much like
   <function>cubrid_connect_with_url</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, port, dbname and userid. 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>cubrid_close</function> or
   <function>cubrid_disconnect</function> will not close links established by
   <function>cubrid_pconnect_with_url</function>).
  </para>
  <para>
   This type of link is therefore called 'persistent'.
  </para>
  <para>
   &lt;url&gt; ::= CUBRID:&lt;host&gt;:&lt;db_name&gt;:&lt;db_user&gt;:&lt;db_password&gt;:[?&lt;properties&gt;]
  </para>
  <para>
   &lt;properties&gt; ::= &lt;property&gt; [&amp;&lt;property&gt;]
  </para>
  <para>
   &lt;properties&gt; ::= alhosts=&lt;alternative_hosts&gt;[ &amp;rctime=&lt;time&gt;]
  </para>
  <para>
   &lt;properties&gt; ::= login_timeout=&lt;milli_sec&gt;
  </para>
  <para>
   &lt;properties&gt; ::= query_timeout=&lt;milli_sec&gt;
  </para>
  <para>
   &lt;properties&gt; ::= disconnect_on_query_timeout=true|false
  </para>
  <para>
   &lt;alternative_hosts&gt; ::= &lt;standby_broker1_host&gt;:&lt;port&gt; [,&lt;standby_broker2_host&gt;:&lt;port&gt;]
  </para>
  <para>
   &lt;host&gt; := HOSTNAME | IP_ADDR
  </para>
  <para>
   &lt;time&gt; := SECOND
  </para>
  <para>
   &lt;milli_sec&gt; := MILLI SECOND
  </para>
  <para>
   <simplelist>
    <member>host : A host name or IP address of the master database</member>
    <member>db_name : A name of the database</member>
    <member>db_user : A name of the database user</member>
    <member>db_password : A database user password</member>
    <member>
     alhosts : Specifies the broker information of the standby server, which is
     used for failover when it is impossible to connect to the active server. 
     You can specify multiple brokers for failover, and the connection to the brokers
     is attempted in the order listed in alhosts</member>
    <member>
     rctime : An interval between the attempts to connect to the active broker in
     which failure occurred. After a failure occurs, the system connects to the 
     broker specified by althosts (failover), terminates the transaction, and then
     attempts to connect to the active broker of the master database at every rctime. 
     The default value is 600 seconds.</member>
    <member>
     login_timeout : Timeout value (unit: msec.) for database login. The default
     value is 0, which means infinite postponement.
    </member>
    <member>
     query_timeout : Timeout value (unit: msec.) for query request. Upon timeout,
     a message to cancel requesting a query transferred to server is sent. The return 
     value can depend on the disconnect_on_query_timeout configuration; even though the
     message to cancel a request is sent to server, that request may succeed.
    </member>
    <member>
     disconnect_on_query_timeout : Configures a value whether to immediately return
     an error of function being executed upon timeout. The default value is false.
    </member>
   </simplelist>
  </para>
  <note>
   <para>
    <literal>?</literal> and <literal>:</literal> that are used as identifiers
    in PHP connection URL can't be included in the password. The following is
    an example of a password that is invalid to use as connection URL because it contains
    "<literal>?:</literal>".
   </para>
   <para>
    $url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100";
   </para>
   <para>
    Passwords that contain <literal>?</literal> or <literal>:</literal> may be
    passed as a separate parameter.
   </para>
   <para>
    $url = "CUBRID:localhost:33000:tbd:::?login_timeout=100";
   </para>
   <para>
    $conn = cubrid_pconnect_with_url ($url, "dba", "12?");
   </para>
   <para>
    If user or password is empty,you can't delete "<literal>:</literal>",the following is
    an example.
   </para>
   <para>
    $url = "CUBRID:localhost:33000:demodb:::";
   </para>
  </note>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>conn_url</parameter></term>
     <listitem><para>A character string that contains server connection information.</para></listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>userid</parameter></term>
     <listitem><para>User name for the database.</para></listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>passwd</parameter></term>
     <listitem><para>User password.</para></listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Connection identifier, when process is successful. 
  </para>
  <para>
   &false;, when process is unsuccessful.
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>cubrid_pconnect_with_url</function> url without properties example</title>
   <programlisting role="php">
<![CDATA[
<?php
$conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::"
$con = cubrid_pconnect_with_url ($conn_url);

if ($con) {
   echo "connected successfully";
   cubrid_execute($con, "create table person(id int,name char(16))");
   $req =cubrid_execute($con, "insert into person values(1,'James')");

   if ($req) {
      cubrid_close_request ($req);
      cubrid_commit ($con);
   } else {
      cubrid_rollback ($con);
   }
   cubrid_disconnect ($con);
}
?>
]]>
   </programlisting>
  </example>
  
  <example>
   <title><function>cubrid_pconnect_with_url</function> url with properties example</title>
   <programlisting role="php">
<![CDATA[
<?php
$conn_url = "CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100"
$con = cubrid_pconnect_with_url ($conn_url);

if ($con) {
   echo "connected successfully";
   $req =cubrid_execute($con, "insert into person values(1,'James')");

   if ($req) {
      cubrid_close_request ($req);
      cubrid_commit ($con);
   } else {
      cubrid_rollback ($con);
   }
   cubrid_disconnect ($con);
}
?>
]]>
   </programlisting>
  </example>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>cubrid_connect</function></member>
    <member><function>cubrid_pconnect</function></member>
    <member><function>cubrid_pconnect_with_url</function></member>
    <member><function>cubrid_disconnect</function></member>
    <member><function>cubrid_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
-->