# Firebird/InterBase Functions

## Introduction

Firebird/InterBase is a relational database offering many ANSI SQL-92 features that runs on Linux, Windows, and a variety of Unix platforms. Firebird/InterBase offers excellent concurrency, high performance, and powerful language support for stored procedures and triggers. It has been used in production systems, under a variety of names since 1981.

InterBase is the name of the closed-source variant of this RDBMS that was developed by Borland/Inprise. More information about InterBase is available at » http://www.borland.com/interbase/.

Firebird is a commercially independent project of C and C++ programmers, technical advisors and supporters developing and enhancing a multi-platform relational database management system based on the source code released by Inprise Corp (now known as Borland Software Corp) under the InterBase Public License v.1.0 on 25 July, 2000. More information about Firebird is available at » http://www.firebirdsql.org/.

> Note: This extension supports InterBase versions 5 and up and all versions of Firebird. Support for InterBase version 5.x will be dropped in PHP 5.
> This database uses a single quote (') character for escaping, a behavior similar to the Sybase database, add to your php.ini the following directive:

> `magic_quotes_sybase = On`

## Requirements

## Installation

To enable InterBase support configure PHP --with-interbase[=DIR], where DIR is the InterBase base install directory, which defaults to /usr/interbase.

> Note: Note to Win32 Users In order for this extension to work, there are DLL files that must be available to the Windows system PATH. See the FAQ titled "How do I add my PHP directory to the PATH on Windows" for information on how to do this. Although copying DLL files from the PHP folder into the Windows system directory also works (because the system directory is by default in the systems PATH), it is not recommended. This extension requires the following files to be in the PATH: gds32.dll
> In case you installed the InterBase database server on the same machine PHP is running on, you will have this DLL already. Therefore you don't need to worry because gds32.dll will already be in the PATH.

## Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

InterBase configuration options
Name | Default | Changeable | Changelog
--- | --- | --- | ---
ibase.allow_persistent | "1" | PHP_INI_SYSTEM |
ibase.max_persistent | "-1" | PHP_INI_SYSTEM |
ibase.max_links | "-1" | PHP_INI_SYSTEM |
ibase.default_db | NULL | PHP_INI_SYSTEM | Available since PHP 5.0.0.
ibase.default_user | NULL | PHP_INI_ALL |
ibase.default_password | NULL | PHP_INI_ALL |
ibase.default_charset | NULL | PHP_INI_ALL | Available since PHP 5.0.0.
ibase.timestampformat | "%Y-%m-%d %H:%M:%S" | PHP_INI_ALL |
ibase.dateformat | "%Y-%m-%d" | PHP_INI_ALL |
ibase.timeformat | "%H:%M:%S" | PHP_INI_ALL |

For further details and definitions of the PHP_INI_* constants, see the php.ini directives.

Here's a short explanation of the configuration directives.

`ibase.allow_persistent` boolean

  Whether to allow persistent connections to Firebird/InterBase.

`ibase.max_persistent` integer

  The maximum number of persistent Firebird/InterBase connections per process. New connections created with ibase_pconnect() will be non-persistent if this number would be exceeded.

`ibase.max_links` integer

  The maximum number of Firebird/InterBase connections per process, including persistent connections.

`ibase.default_db` string

  The default database to connect to when ibase_[p]connect() is called without specifying a database name. If this value is set and SQL safe mode is enabled, no other connections than to this database will be allowed.

`ibase.default_user` string

  The user name to use when connecting to a database if no user name is specified.

`ibase.default_password` string

  The password to use when connecting to a database if no password is specified.

`ibase.default_charset` string

  The character set to use when connecting to a database if no character set is specified.

`ibase.timestampformat` string

`ibase.dateformat` string

`ibase.timeformat` string

  These directives are used to set the date and time formats that are used when returning dates and times from a result set, or when binding arguments to date and time parameters.

## Resource Types

## Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

The following constants can be passed to ibase_trans() to specify transaction behaviour.

Firebird/InterBase transaction flags
Constant | Description
--- | ---
IBASE_DEFAULT | The default transaction settings are to be used. This default is determined by the client library, which defines it as IBASE_WRITE|IBASE_CONCURRENCY|IBASE_WAIT in most cases.
IBASE_READ | Starts a read-only transaction.
IBASE_WRITE | Starts a read-write transaction.
IBASE_CONSISTENCY | Starts a transaction with the isolation level set to 'consistency', which means the transaction cannot read from tables that are being modified by other concurrent transactions.
IBASE_CONCURRENCY | Starts a transaction with the isolation level set to 'concurrency' (or 'snapshot'), which means the transaction has access to all tables, but cannot see changes that were committed by other transactions after the transaction was started.
IBASE_COMMITTED | Starts a transaction with the isolation level set to 'read committed'. This flag should be combined with either `IBASE_REC_VERSION` or `IBASE_REC_NO_VERSION`. This isolation level allows access to changes that were committed after the transaction was started. If `IBASE_REC_NO_VERSION` was specified, only the latest version of a row can be read. If `IBASE_REC_VERSION` was specified, a row can even be read when a modification to it is pending in a concurrent transaction.
IBASE_WAIT | Indicated that a transaction should wait and retry when a conflict occurs.
IBASE_NOWAIT | Indicated that a transaction should fail immediately when a conflict occurs.

The following constants can be passed to ibase_fetch_row(), ibase_fetch_assoc() or ibase_fetch_object() to specify fetch behaviour.

Firebird/InterBase fetch flags
Constant | Description
--- | ---
IBASE_FETCH_BLOBS | Also available as `IBASE_TEXT`for backward compatibility. Causes BLOB contents to be fetched inline, instead of being fetched as BLOB identifiers.
IBASE_FETCH_ARRAYS | Causes arrays to be fetched inline. Otherwise, array identifiers are returned. Array identifiers can only be used as arguments to INSERT operations, as no functions to handle array identifiers are currently available.
IBASE_UNIXTIME | Causes date and time fields not to be returned as strings, but as UNIX timestamps (the number of seconds since the epoch, which is 1-Jan-1970 0:00 UTC). Might be problematic if used with dates before 1970 on some systems.

The following constants are used to pass requests and options to the service API functions (ibase_server_info(), ibase_db_info(), ibase_backup(), ibase_restore() and ibase_maintain_db()). Please refer to the Firebird/InterBase manuals for the meaning of these options.

`IBASE_BKP_IGNORE_CHECKSUMS`
`IBASE_BKP_IGNORE_LIMBO`
`IBASE_BKP_METADATA_ONLY`
`IBASE_BKP_NO_GARBAGE_COLLECT`
`IBASE_BKP_OLD_DESCRIPTIONS`
`IBASE_BKP_NON_TRANSPORTABLE`
`IBASE_BKP_CONVERT`
  Options to ibase_backup()
`IBASE_RES_DEACTIVATE_IDX`
`IBASE_RES_NO_SHADOW`
`IBASE_RES_NO_VALIDITY`
`IBASE_RES_ONE_AT_A_TIME`
`IBASE_RES_REPLACE`
`IBASE_RES_CREATE`
`IBASE_RES_USE_ALL_SPACE`
  Options to ibase_restore()
`IBASE_PRP_PAGE_BUFFERS`
`IBASE_PRP_SWEEP_INTERVAL`
`IBASE_PRP_SHUTDOWN_DB`
`IBASE_PRP_DENY_NEW_TRANSACTIONS`
`IBASE_PRP_DENY_NEW_ATTACHMENTS`
`IBASE_PRP_RESERVE_SPACE`
`IBASE_PRP_RES_USE_FULL`
`IBASE_PRP_RES`
`IBASE_PRP_WRITE_MODE`
`IBASE_PRP_WM_ASYNC`
`IBASE_PRP_WM_SYNC`
`IBASE_PRP_ACCESS_MODE`
`IBASE_PRP_AM_READONLY`
`IBASE_PRP_AM_READWRITE`
`IBASE_PRP_SET_SQL_DIALECT`
`IBASE_PRP_ACTIVATE`
`IBASE_PRP_DB_ONLINE`
`IBASE_RPR_CHECK_DB`
`IBASE_RPR_IGNORE_CHECKSUM`
`IBASE_RPR_KILL_SHADOWS`
`IBASE_RPR_MEND_DB`
`IBASE_RPR_VALIDATE_DB`
`IBASE_RPR_FULL`
`IBASE_RPR_SWEEP_DB`
  Options to ibase_maintain_db()
`IBASE_STS_DATA_PAGES`
`IBASE_STS_DB_LOG`
`IBASE_STS_HDR_PAGES`
`IBASE_STS_IDX_PAGES`
`IBASE_STS_SYS_RELATIONS`
  Options to ibase_db_info()
`IBASE_SVC_SERVER_VERSION`
`IBASE_SVC_IMPLEMENTATION`
`IBASE_SVC_GET_ENV`
`IBASE_SVC_GET_ENV_LOCK`
`IBASE_SVC_GET_ENV_MSG`
`IBASE_SVC_USER_DBPATH`
`IBASE_SVC_SVR_DB_INFO`
`IBASE_SVC_GET_USERS`
  Options to ibase_server_info()

## Table of Contents

- ibase_add_user — Add a user to a security database (only for IB6 or later)
- ibase_affected_rows — Return the number of rows that were affected by the previous query
- ibase_backup — Initiates a backup task in the service manager and returns immediately
- ibase_blob_add — Add data into a newly created blob
- ibase_blob_cancel — Cancel creating blob
- ibase_blob_close — Close blob
- ibase_blob_create — Create a new blob for adding data
- ibase_blob_echo — Output blob contents to browser
- ibase_blob_get — Get len bytes data from open blob
- ibase_blob_import — Create blob, copy file in it, and close it
- ibase_blob_info — Return blob length and other useful info
- ibase_blob_open — Open blob for retrieving data parts
- ibase_close — Close a connection to an InterBase database
- ibase_commit_ret — Commit a transaction without closing it
- ibase_commit — Commit a transaction
- ibase_connect — Open a connection to an InterBase database
- ibase_db_info — Request statistics about a database
- ibase_delete_user — Delete a user from a security database (only for IB6 or later)
- ibase_drop_db — Drops a database
- ibase_errcode — Return an error code
- ibase_errmsg — Return error messages
- ibase_execute — Execute a previously prepared query
- ibase_fetch_assoc — Fetch a result row from a query as an associative array
- ibase_fetch_object — Get an object from a InterBase database
- ibase_fetch_row — Fetch a row from an InterBase database
- ibase_field_info — Get information about a field
- ibase_free_event_handler — Cancels a registered event handler
- ibase_free_query — Free memory allocated by a prepared query
- ibase_free_result — Free a result set
- ibase_gen_id — Increments the named generator and returns its new value
- ibase_maintain_db — Execute a maintenance command on the database server
- ibase_modify_user — Modify a user to a security database (only for IB6 or later)
- ibase_name_result — Assigns a name to a result set
- ibase_num_fields — Get the number of fields in a result set
- ibase_num_params — Return the number of parameters in a prepared query
- ibase_param_info — Return information about a parameter in a prepared query
- ibase_pconnect — Open a persistent connection to an InterBase database
- ibase_prepare — Prepare a query for later binding of parameter placeholders and execution
- ibase_query — Execute a query on an InterBase database
- ibase_restore — Initiates a restore task in the service manager and returns immediately
- ibase_rollback_ret — Roll back a transaction without closing it
- ibase_rollback — Roll back a transaction
- ibase_server_info — Request information about a database server
- ibase_service_attach — Connect to the service manager
- ibase_service_detach — Disconnect from the service manager
- ibase_set_event_handler — Register a callback function to be called when events are posted
- ibase_timefmt — Sets the format of timestamp, date and time type columns returned from queries
- ibase_trans — Begin a transaction
- ibase_wait_event — Wait for an event to be posted by the database