Firebird 2.0
PHP5 Programming
Manual

FBIRD_CONNECT

Purpose

Use the fbird_connect_function to connect to a Firebird server and open a database on that server.

Syntax

<connect> ::=
   fbird_connect ( [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

Use this function to establishes a connection to a Firebird server.

  • The server_db argument has to be a valid path to database file on the server. The format of this string determines the connection protocol used by the Firebird client library:

Protocol
Server/database name pair format
local
path/to/database.fdb
TCP/IP
server:path/to/database.fdb
NETBEUI
//server/path/to/database.fdb
IPX/SPX
server@path/to/database.fdb


Directory path separators can be either forward or backward slashes. Note that on Windows servers the path may start with a drive letter (e.g. “c:\path\to\db.fdb”). The path can alternatively be an alias name.

The server_db name is obligatory, unless the the ibase.default_db parameter has been set in the PHP configuration file. In that case, an ommitted server_db parameter will cause the default to be used.

If SQL safe mode has been been set, the server_db name (if given) is ignored and the ibase.default_db name is used instead.

  • The username and password specify the login credentials to be used for this connection. The parameters are obligatory, unless specified with the PHP configuration directives ibase.default_user and ibase.default_password.

  • The charset parameter specifies the default character set for this connection. Firebird will transliterate between the character set of the server data and the client character set if possible. If no character set is specified, the PHP configuration setting ibase.default_charset will be used. If not defined or Null, the default charset of “none” will be used.

  • The buffers parameter specifies the number of connection buffers to allocate for the client side of the connection. If 0 or omitted, the default from the Firebird configuration file is used. If no Firebird configuration file can be located, a default of ..KB is used.

  • The dialect parameter selects the default SQL dialect for any statement executed within a connection, and it defaults to dialect 3 with Firebird 2.0 installations. Values 1 and 2 are only relevant to legacy installations dating back to the late 90's.

  • The role parameter specifies the user role as an additional login credential. Roles are part of Firebirds SQL200x compliant security features.

  • The sync parameter specifies if the Firebird server should use asynchroneous writes. If you set this parameter to 38 the server will operate in synchroneous mode, any other value or ommiting a value will cause the server to operate in asynchroneous mode.

    Asynchroneous mode is faster than synchroneous, but has a higher chance of leaving the database file in an inconsistent state if the server system crashes. Synchroneous mode is not recommended on Windows.

The fbird_connect function returns a “connection handle”. The connection handle is passed to other functions in the Firebird PHP5 driver as a way to identify a specific database connection. The driver keeps the last connection made (using fbird_connect or fbird_pconnect) as the default database connection and this handle is used as the default of no other handle is specified.

In case another call is made to ibase_connect() with the same arguments, no new connection will be established, but instead, the handle of the already opened connection will be returned. The connection to the server will be closed as soon as the execution of the script ends, unless it's closed earlier by explicitly calling fbird_close().

Example

The below example connects 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_connect($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_close($conn);



See also

fbird_pconnect, fbird_close


previous page goto index next page

Legal information