Firebird 2.0
PHP5 Programming
Manual

FBIRD_MAINTAIN_DB

Purpose

Use the fbird_maintain_db function to perform DBA operations on a database. Similar to using the gfix tool.

Syntax

<maintain_db> ::=
   fbird_maintain_db( svc_hndl, db, action [, arg] )


Element 
Type
Description
svc_hndl
resource
A valid service handle
db
string
A database name
action
int
Requested action
arg
int
Optional argument
<return>
bool
True on success, False on failure

Semantics

The fbird_maintain_db function allows to maintain a database, similar to using the 'gfix' command. The db parameter is a path to a database or a database alias. Note that it is not necessary to specify the server portion, as you would in a connection string: the service handle already specifies which server you are talking to.

The service handle must be associated with the SYSDBA user or the database owner in order to perform DBA actions successfully. There must be no active connections during DBA actions. If these conditions are not met, the function returns False.

The first set of actions are for repairing, cleaning and activating a database file. The following table lists the options that can be specified for the action parameter. The optional argument parameter is OR'ed together with the action parameter to request multiple data items at once:

Flag
Meaning

IBASE_RPR_CHECK_DB

Request read-only validation of the database, without correcting any problems; corresponds to 'gfix -no_update'

IBASE_RPR_IGNORE_CHECKSUM

Ignore all checksum errors; corresponds to 'gfix -ignore'

IBASE_RPR_KILL_SHADOWS

Remove references to unavailable shadow files; corresponds to 'gfix -kill'

IBASE_RPR_MEND_DB

Mark corrupted records as unavailable, so that subsequent operations skip them; corresponds to 'gfix -mend'

IBASE_RPR_VALIDATE_DB

Locate and release pages that are allocated but unassigned to any data structures; corresponds to 'gfix -validate'

IBASE_RPR_FULL

Check record and page structures, releasing unassigned record fragments; use with IBASE_RPR_VALIDATE_DB; corresponds to 'gfix -full'

IBASE_PRP_ACTIVATE

Activate shadow file for use as a database; corresponds to 'gfix -activate'

IBASE_PRP_DB_ONLINE

Bring a shutdown database back online; corresponds to 'gfix -online'



The second set of actions are for setting certain operational parameters associated with the database. The following table lists the options that can be specified for the action parameter. The optional argument parameter specifies the value for the parameter. The default value is zero.

Flag
Meaning

IBASE_PRP_PAGE_BUFFERS

Set the default number of cache buffers to the specified number; corresponds to 'gfix -buffers <arg>'

IBASE_PRP_SWEEP_INTERVAL

Set the sweep interval to the specified number; specify zero to disable sweeping; corresponds to 'gfix -housekeeping <arg>'

IBASE_PRP_SHUTDOWN_DB

Shuts down the database:

  • If argument is zero, when there are no connections to the database, or

  • If argument is non-zero, at the end of a <arg> second the timeout period

Corresponds to 'gfix -shut -force <arg>'

IBASE_PRP_
DENY_NEW_TRANSACTIONS

Shuts down the database if there are no active transactions at the end of the timeout period you specify; deny new transactions during this timeout period; fail if there are active transactions at the end of the timeout period; corresponds to 'gfix -shut -tran <arg>'

IBASE_PRP_DENY_NEW_ATTACHMENTS

Shuts down the database if there are no active transactions at the end of the timeout period you specify; deny new database attachments during this timeout period; fail if there are active database attachments at the end of the timeout period; corresponds to 'gfix -shut -attach <arg>'



The third set of actions are for setting certain operational parameters associated with the database. Other than the second set, the argument value is obligatory and must be selected from a few specific values. The following table lists the options that can be specified for the action parameter.

Flag
Meaning

IBASE_PRP_SET_SQL_DIALECT

Set the SQL dialect for the database; Argument must be either 1 or 3.

IBASE_PRP_RESERVE_SPACE

Configure the database to fill data pages when inserting new records, or reserve 20% of each page for later record deltas; The argument must be one of:

  • IBASE_PRP_RES_USE_FULL

  • IBASE_PRP_RES

Corresponds to 'gfix -use'

IBASE_PRP_WRITE_MODE

Set the write mode for the database. Argument must be one of:

  • IBASE_PRP_WM_ASYNC

  • IBASE_PRP_WM_SYNC

Corresponds to 'gfix -write'

IBASE_PRP_ACCESS_MODE

Set the write mode for the database. Argument must be one of:

  • IBASE_PRP_AM_READONLY

  • IBASE_PRP_AM_READWRITE

Corresponds to 'gfix -mode'


If the argument does not match one of the prescribed options, the function will fail and return False.


Example

The below example retrieves the information located on the database header pages:

$svc = fbird_service_attach('localhost', 'sysdba', 'masterkey')
$info = fbird_db_info($svc, 'path/to/db.fdb', IBASE_STS_HDR_PAGES);
fbird_service_detach($svc);
echo $db_info;



See also

fbird_service_attach, fbird_service_detach, fbird_server_info, fbird_db_info


previous page goto index next page

Legal information