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

User comments:

Extend this topic - Post a comment