Structure of a header page
<< Implementing a Soundex function | Database technology articles | Structure of a data page >>
Structure of a header page
By Ann Harrison
A Firebird database has one header page per file, but the first one is by far the most important. When Firebird opens a database, it reads the first 1024 bytes of the file to determine whether the file is actually a database, whether its format (i.e. On Disk Structure or ODS) is one that the current engine understands, the size of a database page, whether the database is read/only, whether forced writes are required, and many other important bits of information. Subsequent header pages contain only the page number of the header of the next file, the sequence number of this file in the database, and the name of the next file.
The individual fields on the primary header page are:
| Field type | Size in bytes | Function |
|---|---|---|
hdr_header | 16 | This structure is defined on every page and includes the information below. |
hdr_page_size | 2 | Length of a database page in bytes. |
hdr_ods_version | 2 | Major and minor On Disk Structure version number. |
hdr_PAGES | 4 | The page number of the first pointer page for the RDB$PAGES table. The format format of the RDB$PAGES table is fixed for any ODS. The first pointer page allows the system to read the RDB$PAGES table and find all other parts of the metadata. |
hdr_next_page | 4 | Page number of the header page of the next file in the database. |
hdr_oldest_transaction | 4 | Oldest uncommitted transaction, whether rolled back, limbo, or active. |
hdr_oldest_active | 4 | Oldest transaction active when any active transaction started. |
hdr_next_transaction | 4 | Transaction id to be assigned to the next transaction when it starts. |
hdr_sequence | 2 | Sequence number of this file in the database. |
hdr_flags | 4 | Flag settings, see below. |
hdr_creation_date | 8 | Timestamp of database creation. |
hdr_attachment_id | 4 | Identifier to assign to the next connection. |
hdr_shadow_count | 4 | Event count for shadow synchronization. |
hdr_implementation | 2 | Implementation number of the database engine which created the database. |
hdr_ods_minor | 2 | Current minor on disk structure version number. |
hdr_ods_minor_original | 2 | Minor on disk structure version at the time of database creation. |
hdr_end | 2 | Offset of the last entry in the variable length portion of the header. |
hdr_page_buffers | 4 | Maximum number of pages in the database cache. |
hdr_bumped_transaction | 4 | Unused, part of the abandoned write-ahead log. |
hdr_oldest_snapshot | 4 | Confusing and redundant variant of oldest active. |
hdr_backup_pages | 4 | Number of pages in files locked for backup (NBAK?). |
hdr_misc | 12 | Stuff to be named later, present for alignment, I think. |
hdr_data[1] | 1 | Clumplet data. |
Header page clumpets
Clumplets are optional extensions of the header information and start at the end of the fixed portion of the header. Clumplet data items have the format:
<type_byte> <length_byte> <data...>
New clumplet types can be added without invalidating the on disk structure because the engine skips unrecognized clumplets.
| Clumplet name | Value | Meaning |
|---|---|---|
HDR_end | 0 | Last clumplet in the header. |
HDR_root_file_name | 1 | Original name of root file. |
HDR_journal_server | 2 | Name of journal server. |
HDR_file | 3 | Secondary file. |
HDR_last_page | 4 | Last logical page number of file. |
HDR_unlicensed | 5 | Count of unlicensed activity. |
HDR_sweep_interval | 6 | Transactions between sweeps. |
HDR_log_name | 7 | Replay log name. |
HDR_journal_file | 8 | Intermediate journal file. |
HDR_password_file_key | 9 | Key to compare to password db. |
HDR_backup_info | 10 | WAL backup information. |
HDR_cache_file | 11 | Shared cache file – unused. |
HDR_max | 11 | Maximum HDR_clump value. |
Standard page header
Every page in the database starts with the standard page header, containing the following fields. The values present in the standard header for the first header page of a database are listed.
| Field type | Size in bytes | Function |
|---|---|---|
page type | 1 | Value 1 meaning header page. |
page flags | 1 | Not used for header pages. |
page checksum | 2 | The value 12345. |
page generation | 4 | A value incremented each time the page is written. |
page sequence number | 4 | Reserved for future use. |
page offset | 4 | Reserved for future use. |
Header page flags
Possible settings for the flag field in the database header:
| Flag name | Hex value | Decimal value | Meaning |
|---|---|---|---|
hdr_active_shadow | 0x1 | 1 | File is an active shadow file. |
hdr_force_write | 0x2 | 2 | Forced writes are enabled if this flag is set. |
hdr_short_journal | 0x4 | 4 | Short-term journaling. Part of an abandoned journaling subsystem. |
hdr_long_journal | 0x8 | 8 | Long-term journaling. Part of an abandoned journaling subsystem. |
hdr_no_checksums | 0x10 | 16 | Don't calculate checksums. Checksums are no longer calculated. |
hdr_no_reserve | 0x20 | 32 | Don't reserve space on each page for record versions created by updates and deletes. |
hdr_disable_cache | 0x40 | 64 | Disable shared cache file. Another abandoned project. |
hdr_shutdown | 0x80 | 128 | Database is shutdown. |
hdr_SQL_dialect_3 | 0x100 | 256 | Database SQL dialect 3. |
hdr_read_only | 0x200 | 512 | Database in ReadOnly. If not set, DB is RW. |
This paper was written by Ann Harrison and is copyright Ms. Harrison and IBPhoenix Inc. You may republish it verbatim, including this notation. You may update, correct, or expand the material, provided that you include a notation that the original work was produced by Ms. Harrison and IBPhoenix Inc.
See also:
Structure of a data page
Firebird Internals
Firebird for the database expert: Episode 2 - Page Types
back to top of page
<< Implementing a Soundex function | Database technology articles | Structure of a data page >>
