<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Open a persistent connection to CUBRID server</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.cubrid-num-rows.html">cubrid_num_rows</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.cubrid-pconnect.html">cubrid_pconnect</a></div>
<div class="up"><a href="ref.cubrid.html">CUBRID Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.cubrid-pconnect-with-url" class="refentry">
<div class="refnamediv">
<h1 class="refname">cubrid_pconnect_with_url</h1>
<p class="verinfo">(PECL CUBRID >= 8.3.1)</p><p class="refpurpose"><span class="refname">cubrid_pconnect_with_url</span> — <span class="dc-title">Open a persistent connection to CUBRID server</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.cubrid-pconnect-with-url-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">resource</span> <span class="methodname"><strong>cubrid_pconnect_with_url</strong></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$conn_url</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$userid</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$passwd</code></span>
]] )</div>
<p class="para rdfs-comment">
Establishes a persistent connection to a CUBRID server.
</p>
<p class="para">
<span class="function"><strong>cubrid_pconnect_with_url()</strong></span> acts very much like
<span class="function"><a href="function.cubrid-connect-with-url.html" class="function">cubrid_connect_with_url()</a></span> with two major differences.
</p>
<p class="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.
</p>
<p class="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 ( <span class="function"><a href="function.cubrid-close.html" class="function">cubrid_close()</a></span> or
<span class="function"><a href="function.cubrid-disconnect.html" class="function">cubrid_disconnect()</a></span> will not close links established by
<span class="function"><strong>cubrid_pconnect_with_url()</strong></span>).
</p>
<p class="para">
This type of link is therefore called 'persistent'.
</p>
<p class="para">
<url> ::= CUBRID:<host>:<db_name>:<db_user>:<db_password>:[?<properties>]
</p>
<p class="para">
<properties> ::= <property> [&<property>]
</p>
<p class="para">
<properties> ::= alhosts=<alternative_hosts>[ &rctime=<time>]
</p>
<p class="para">
<properties> ::= login_timeout=<milli_sec>
</p>
<p class="para">
<properties> ::= query_timeout=<milli_sec>
</p>
<p class="para">
<properties> ::= disconnect_on_query_timeout=true|false
</p>
<p class="para">
<alternative_hosts> ::= <standby_broker1_host>:<port> [,<standby_broker2_host>:<port>]
</p>
<p class="para">
<host> := HOSTNAME | IP_ADDR
</p>
<p class="para">
<time> := SECOND
</p>
<p class="para">
<milli_sec> := MILLI SECOND
</p>
<p class="para">
<ul class="simplelist">
<li class="member">host : A host name or IP address of the master database</li>
<li class="member">db_name : A name of the database</li>
<li class="member">db_user : A name of the database user</li>
<li class="member">db_password : A database user password</li>
<li class="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</li>
<li class="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.</li>
<li class="member">
login_timeout : Timeout value (unit: msec.) for database login. The default
value is 0, which means infinite postponement.
</li>
<li class="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.
</li>
<li class="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.
</li>
</ul>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
<em>?</em> and <em>:</em> 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
"<em>?:</em>".
</p>
<p class="para">
$url = "CUBRID:localhost:33000:tdb:dba:12?:?login_timeout=100";
</p>
<p class="para">
Passwords that contain <em>?</em> or <em>:</em> may be
passed as a separate parameter.
</p>
<p class="para">
$url = "CUBRID:localhost:33000:tbd:::?login_timeout=100";
</p>
<p class="para">
$conn = cubrid_pconnect_with_url ($url, "dba", "12?");
</p>
<p class="para">
If user or password is empty,you can't delete "<em>:</em>",the following is
an example.
</p>
<p class="para">
$url = "CUBRID:localhost:33000:demodb:::";
</p>
</p></blockquote>
</div>
<div class="refsect1 parameters" id="refsect1-function.cubrid-pconnect-with-url-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">conn_url</code></em></span>
<dd>
<p class="para">A character string that contains server connection information.</p></dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">userid</code></em></span>
<dd>
<p class="para">User name for the database.</p></dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">passwd</code></em></span>
<dd>
<p class="para">User password.</p></dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.cubrid-pconnect-with-url-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Connection identifier, when process is successful.
</p>
<p class="para">
<strong><code>FALSE</code></strong>, when process is unsuccessful.
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.cubrid-pconnect-with-url-examples">
<h3 class="title">Examples</h3>
<div class="example" id="example-1049">
<p><strong>Example #1 <span class="function"><strong>cubrid_pconnect_with_url()</strong></span> url without properties example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$conn_url </span><span style="color: #007700">= </span><span style="color: #DD0000">"CUBRID:127.0.0.1:33000:demodb:dba::"<br /></span><span style="color: #0000BB">$con </span><span style="color: #007700">= </span><span style="color: #0000BB">cubrid_pconnect_with_url </span><span style="color: #007700">(</span><span style="color: #0000BB">$conn_url</span><span style="color: #007700">);<br /><br />if (</span><span style="color: #0000BB">$con</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"connected successfully"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">cubrid_execute</span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">, </span><span style="color: #DD0000">"create table person(id int,name char(16))"</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$req </span><span style="color: #007700">=</span><span style="color: #0000BB">cubrid_execute</span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">, </span><span style="color: #DD0000">"insert into person values(1,'James')"</span><span style="color: #007700">);<br /><br /> if (</span><span style="color: #0000BB">$req</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">cubrid_close_request </span><span style="color: #007700">(</span><span style="color: #0000BB">$req</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">cubrid_commit </span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">);<br /> } else {<br /> </span><span style="color: #0000BB">cubrid_rollback </span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">);<br /> }<br /> </span><span style="color: #0000BB">cubrid_disconnect </span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">);<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="example-1050">
<p><strong>Example #2 <span class="function"><strong>cubrid_pconnect_with_url()</strong></span> url with properties example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$conn_url </span><span style="color: #007700">= </span><span style="color: #DD0000">"CUBRID:127.0.0.1:33000:demodb:dba::?althost=10.34.63.132:33088&rctime=100"<br /></span><span style="color: #0000BB">$con </span><span style="color: #007700">= </span><span style="color: #0000BB">cubrid_pconnect_with_url </span><span style="color: #007700">(</span><span style="color: #0000BB">$conn_url</span><span style="color: #007700">);<br /><br />if (</span><span style="color: #0000BB">$con</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"connected successfully"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$req </span><span style="color: #007700">=</span><span style="color: #0000BB">cubrid_execute</span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">, </span><span style="color: #DD0000">"insert into person values(1,'James')"</span><span style="color: #007700">);<br /><br /> if (</span><span style="color: #0000BB">$req</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">cubrid_close_request </span><span style="color: #007700">(</span><span style="color: #0000BB">$req</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">cubrid_commit </span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">);<br /> } else {<br /> </span><span style="color: #0000BB">cubrid_rollback </span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">);<br /> }<br /> </span><span style="color: #0000BB">cubrid_disconnect </span><span style="color: #007700">(</span><span style="color: #0000BB">$con</span><span style="color: #007700">);<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-function.cubrid-pconnect-with-url-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.cubrid-connect.html" class="function" rel="rdfs-seeAlso">cubrid_connect()</a> - Open a connection to a CUBRID Server</span></li>
<li class="member"> <span class="function"><a href="function.cubrid-pconnect.html" class="function" rel="rdfs-seeAlso">cubrid_pconnect()</a> - Open a persistent connection to a CUBRID server</span></li>
<li class="member"> <span class="function"><strong>cubrid_pconnect_with_url()</strong></span></li>
<li class="member"> <span class="function"><a href="function.cubrid-disconnect.html" class="function" rel="rdfs-seeAlso">cubrid_disconnect()</a> - Close a database connection</span></li>
<li class="member"> <span class="function"><a href="function.cubrid-close.html" class="function" rel="rdfs-seeAlso">cubrid_close()</a> - Close CUBRID connection</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.cubrid-num-rows.html">cubrid_num_rows</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.cubrid-pconnect.html">cubrid_pconnect</a></div>
<div class="up"><a href="ref.cubrid.html">CUBRID Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
