Invoking Database Maintenance Using the Services API

From InterBase

Go Up to Invoking Service Tasks with isc_service_start( )


This section describes how to use isc_service_start() to perform database validation, sweep garbage collection, and resolve limbo transactions. These tasks correspond to several of the options of the gfix command-line utility.

Invoking a Database Validation Using the Services API

You can request a database validation with the cluster identifier isc_action_svc_repair. Database validation scans internal data structures for specific types of corruption. In some cases, the validation operation can repair corruption.

Important:
The validation operation cannot guarantee to repair all cases of corruption. Do not rely on database validation as a disaster recovery policy in lieu of making regular backups of your database.

The following table lists arguments to isc_action_svc_repair to validate a database:

Services API database validation arguments
Argument Purpose Argument length Argument
value

isc_spb_dbname

Path of the primary file of the database, from the server’s point of view

2 bytes + string

String

isc_spb_options

The following value is a bitmask of isc_spb_rpr_xxxx options below

4 bytes

Bitmask

isc_spb_rpr_check_db

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

Bit

isc_spb_rpr_ignore_checksum

Ignore all checksum errors; corresponds to gfix -ignore

Bit

isc_spb_rpr_kill_shadows

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

Bit

isc_spb_rpr_mend_db

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

Bit

isc_spb_rpr_validate_db

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

Bit

isc_spb_rpr_full

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

Bit

Invoking a Database Sweep Using the Services API

You can invoke a database sweep with the cluster identifier isc_action_svc_repair. Sweeping attempts to scan the database for outdated record versions and mark them as free space. The following table lists arguments to isc_action_svc_repair to sweep a database:

Services API database sweep arguments
Argument Purpose Argument length Argument value

isc_spb_dbname

Path of the primary file of the database, from the server’s point of view

2 bytes + string

String

isc_spb_options

The following value is a bitmask of isc_spb_rpr_xxxx options below

4 bytes

Bitmask

isc_spb_rpr_sweep_db

Request database sweep to mark outdated records as free space; corresponds to gfix -sweep

Bit

Resolving Limbo Transactions Using the Services API

You can list and correct transactions in a limbo state using the cluster identifier isc_action_svc_repair.

Limbo transactions are the result of interruptions in the two-phase commit process of InterBase. Most client interfaces, including BDE and ODBC, do not exercise the two-phase commit or distributed transaction capabilities of InterBase, therefore applications using such client interfaces never create limbo transactions.

The following table lists arguments to isc_action_svc_repair to resolve limbo transactions in a database:

Services API limbo transaction arguments
Argument Purpose Argument length Argument value

isc_spb_dbname

Path of the primary file of the database, from the point of view of the server.

2 bytes + string

String

isc_spb_rpr_commit_trans

Request that the Services Manager commit the transactions that follow.

isc_spb_rpr_rollback_trans

Request that the Services Manager roll back the transactions that follow.

isc_spb_rpr_recover_two_phase

Request that the Services Manager use automatic two-phase commit recovery on the specified transactions.

isc_spb_tra_id

Precedes a transaction ID number.

4 bytes

Unsigned long

Advance To: