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
[, 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  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);