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 typeSize in bytesFunction
hdr_header16This structure is defined on every page and includes the information below.
hdr_page_size2Length of a database page in bytes.
hdr_ods_version2Major and minor On Disk Structure version number.
hdr_PAGES4The 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_page4Page number of the header page of the next file in the database.
hdr_oldest_transaction4Oldest uncommitted transaction, whether rolled back, limbo, or active.
hdr_oldest_active4Oldest transaction active when any active transaction started.
hdr_next_transaction4Transaction id to be assigned to the next transaction when it starts.
hdr_sequence2Sequence number of this file in the database.
hdr_flags4Flag settings, see below.
hdr_creation_date8Timestamp of database creation.
hdr_attachment_id4Identifier to assign to the next connection.
hdr_shadow_count4Event count for shadow synchronization.
hdr_implementation2Implementation number of the database engine which created the database.
hdr_ods_minor2Current minor on disk structure version number.
hdr_ods_minor_original2Minor on disk structure version at the time of database creation.
hdr_end2Offset of the last entry in the variable length portion of the header.
hdr_page_buffers4Maximum number of pages in the database cache.
hdr_bumped_transaction4Unused, part of the abandoned write-ahead log.
hdr_oldest_snapshot4Confusing and redundant variant of oldest active.
hdr_backup_pages4Number of pages in files locked for backup (NBAK?).
hdr_misc12Stuff to be named later, present for alignment, I think.
hdr_data[1]1Clumplet 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 nameValueMeaning
HDR_end0Last clumplet in the header.
HDR_root_file_name1Original name of root file.
HDR_journal_server2Name of journal server.
HDR_file3Secondary file.
HDR_last_page4Last logical page number of file.
HDR_unlicensed5Count of unlicensed activity.
HDR_sweep_interval6Transactions between sweeps.
HDR_log_name7Replay log name.
HDR_journal_file8Intermediate journal file.
HDR_password_file_key9Key to compare to password db.
HDR_backup_info10WAL backup information.
HDR_cache_file11Shared cache file – unused.
HDR_max11Maximum 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 typeSize in bytesFunction
page type1Value 1 meaning header page.
page flags1Not used for header pages.
page checksum2The value 12345.
page generation4A value incremented each time the page is written.
page sequence number4Reserved for future use.
page offset4Reserved for future use.

Header page flags

Possible settings for the flag field in the database header:

Flag nameHex valueDecimal valueMeaning
hdr_active_shadow0x11File is an active shadow file.
hdr_force_write0x22Forced writes are enabled if this flag is set.
hdr_short_journal0x44Short-term journaling. Part of an abandoned journaling subsystem.
hdr_long_journal0x88Long-term journaling. Part of an abandoned journaling subsystem.
hdr_no_checksums0x1016Don't calculate checksums. Checksums are no longer calculated.
hdr_no_reserve0x2032Don't reserve space on each page for record versions created by updates and deletes.
hdr_disable_cache0x4064Disable shared cache file. Another abandoned project.
hdr_shutdown0x80128Database is shutdown.
hdr_SQL_dialect_30x100256Database SQL dialect 3.
hdr_read_only0x200512Database 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 >>