ToC path:

mco_restore

Internal function. This is a low-level runtime routine used by the eXtremeDB backup subsystem to restore database state from backup chunks or verify backup integrity. It is invoked internally by mco_backup_restore() and mco_backup_verify() and should not be called directly by applications.

For an overview see page Incremental Online Backup in C

Prototype

    MCO_RET mco_restore(
        /*IN*/ mco_db_h connection,
        /*IN*/ const mco_backup_info_t *backup_info,
        /*IN*/ mco_restore_chunk_proc_t proc_chunk,
        /*IN*/ void *proc_arg
    );

Arguments

connection

Valid database connection handle for the target database to restore into.

backup_info

Pointer to a mco_backup_info_t structure containing metadata of the backup record being processed (e.g., page sizes, transaction number, protocol version).

proc_chunk

Callback function that provides the next data chunk from the backup stream. Must not be NULL.

proc_arg

Opaque context pointer passed to the proc_chunk callback.

Description

This internal function implements the core logic for restoring a database from a sequence of backup chunks or validating their integrity. It is called during both restore (do_restore = 1) and verify (do_restore = 0) operations initiated by mco_backup_restore() and mco_backup_verify(), respectively.

The function:
Validates compatibility between the backup metadata and the current database configuration (page sizes, memory layout, etc.),
Locks the database exclusively during restoration,
Iteratively processes backup chunks (pages, dictionary, indexes, transaction logs, etc.) via the proc_chunk callback,
Reconstructs the database state in memory and on disk,
Updates internal backup flags upon successful snapshot restoration.

Direct use of this function may lead to database corruption or undefined behavior. Applications should use the public API functions mco_backup_restore() and mco_backup_verify() instead.

See Incremental Backup and Restore in C for usage examples.

Return Codes

MCO_S_OK

Restore or verification completed successfully.

MCO_E_ILLEGAL_PARAM

Invalid argument (e.g., NULL connection, missing callbacks, or invalid backup_info).

MCO_E_BACKUP_INVALID_PARAM

Incremental backup is not enabled in the database configuration (MCO_DB_INCREMENTAL_BACKUP_ENABLED flag missing).

MCO_E_BACKUP_PROTOCOL

Backup format is incompatible with the current database (e.g., mismatched page sizes, protocol version, or transaction counter).

Other error codes

May include I/O errors, memory allocation failures, or internal system errors.

Files

Header file:

mco.h

Source file:

mcoabst.c

Library:

libmcolib.a