Firebird 2.0
PHP5 Programming
Manual

FBIRD_PCONNECT

Purpose

Use the fbird_pconnect_function to create a persistent connection to a Firebird server and open a database on that server.

Syntax

<pconnect> ::=
   fbird_pconnect ( [server_db
                   [, username
                   [, password
                   [, charset
                   [, buffers
                   [, dialect
                   [, role
                   [, sync]]]]]]]] )


Element 
Type
Description
server_db
string
Server/database name pair
username
string
User login name
password
string
User password
charset
string
Client character set
buffers
int
Number of client buffers
dialect
int
SQL dialect number
role
string
User role
sync
int
Specifies (a)synchroneous writes
<return>
mixed
A connection handle on success, False on failure

Semantics

The parameters of fbird_pconnect are identical to those for fbird_connect. Refer to that section for more information on the meaning of these parameters.

Persistent connections are connections that do not close when the execution of your script ends. Note that the fbird_close function does NOT close connections created with fbird_pconnect.

When a persistent connection is requested, the Firebird PHP driver checks if there's already an identical persistent connection that remained open from earlier, and if it exists, it uses it. If it does not exist, it creates the connection.

Persistent connections have the advantage that they reduce the overhead related to setting up a database connection. In the case of Firebird running in Classic mode this overhead is substantial, as a new server process is created for each connection. Also, persistent connection allow the server to build up its internal metadata cache across page accesses.

Persistent conncetions only work if the web server / PHP server is set up to support this feature:

  • Web servers that execute PHP pages as CGI scripts do not support persistent links. Instead, they will function as regular links.

  • Web servers that execute PHP pages as a persistent child process (such Apache) or as a thread within the server (such a Microsoft's IIS) so support persistent links.

  • Web servers that execute PHP pages by refering to a PHP FastCGI server (such as for instance Firebird's PHPServer) do support persistent links.

With persistent links, some of the responsibility for managing connections shifts to the application code. The maximum number of simultaneous connections can be limited by the PHP configuration file and by available memory on the database server.

When using persistent connections, make sure that you leave the connection in a “clean” state at the end of your script. This can be achieved by committing or rolling back all transactions that you used during execution of the script.

Example

The below example creates a persistent connection to a server running on the local machine, using the TCP/IP protocol, executes a query and fetches the result:

$srv_db = 'localhost:/path/to/your.fdb';

$conn = fbird_pconnect($srv_db, $username, $password);
$sql = 'SELECT email FROM tblname';
$res = fbird_query($conn, $sql);
while ($row = fbird_fetch_object($res)) {
   echo $row->EMAIL, "\n";
}
fbird_free_result($res);
fbird_commit($conn);
// close the link in case pconnect acted as connect (CGI server)
fbird_close($conn);



See also

fbird_connect, fbird_close


previous page goto index next page

Legal information