Database Management

Persistent and in-memory chess database storage, fast header indexing, game serialization, and metadata.

Types

	Name
typedef int()(void user_data)	scid_should_cancel_fn Function pointer type for querying early cancellation of long-running operations.
typedef void()(size_t done, size_t total, const char message, void *user_data)	scid_progress_report_callback Function pointer type for long-running asynchronous progress notifications.
typedef struct scid_database	scid_database Opaque handle representing an open chess database.

Functions

	Name
scid_error	scid_database_type_get(const scid_database * database, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the database storage backend type string (e.g.
scid_error	scid_database_status_open_get(const scid_database * database, scid_error * out_status) Queries the initial open status code (e.g.
scid_error	scid_database_status_is_read_only(const scid_database * database, int * out_is_read_only) Checks whether the database session is operating in read-only mode.
scid_error	scid_database_status_is_dirty(const scid_database * database, int * out_is_dirty) Checks whether the database session contains unpersisted in-memory modifications.
scid_error	scid_database_status_bad_name_count_get(const scid_database * database, size_t * out_count) Returns the count of corrupted or unresolvable name identifiers encountered during open.
scid_error	scid_database_stats_result_count_get(const scid_database * database, const char * result, size_t * out_count) Retrieves the total number of games matching a specific outcome result string.
scid_error	scid_database_stats_date_range_get(const scid_database * database, char * out_min_date, size_t out_min_date_capacity, size_t * out_min_date_size, char * out_max_date, size_t out_max_date_capacity, size_t * out_max_date_size) Retrieves the chronological date span (earliest and latest game dates) in the database.
scid_error	scid_database_save(scid_database * database) Explicitly persists pending database modifications, header index updates, and name caches to disk.
scid_error	scid_database_read_only_get(const scid_database * database, int * out_read_only) Checks if the database is opened in read-only mode.
scid_error	scid_database_open_scid5_read_only(const char * path, scid_progress_report_callback progress_report, void * progress_report_user_data, scid_should_cancel_fn should_cancel, void * should_cancel_user_data, scid_database ** out_database) Opens an existing Scid 5 database in read-only mode.
scid_error	scid_database_open_scid5(const char * path, scid_progress_report_callback progress_report, void * progress_report_user_data, scid_should_cancel_fn should_cancel, void * should_cancel_user_data, scid_database ** out_database) Opens an existing Scid 5 database for read-write operations.
scid_error	scid_database_open_pgn_read_only(const char * path, scid_progress_report_callback progress_report, void * progress_report_user_data, scid_should_cancel_fn should_cancel, void * should_cancel_user_data, scid_database ** out_database) Opens and indexes a plain-text PGN file in read-only mode.
scid_error	scid_database_metadata_set(scid_database * database, const char * key, const char * value) Sets or updates a custom metadata property in the database.
scid_error	scid_database_metadata_get(const scid_database * database, const char * key, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves a custom metadata property value by key name.
scid_error	scid_database_metadata_count_get(const scid_database * database, size_t * out_count) Retrieves the total number of custom metadata entries stored in the database.
scid_error	scid_database_metadata_at_get(const scid_database * database, size_t index, char * out_key, size_t out_key_capacity, size_t * out_key_size, char * out_value, size_t out_value_capacity, size_t * out_value_size) Retrieves a metadata key-value pair by zero-based index.
scid_error	scid_database_is_open(const scid_database * database, int * out_is_open) Checks whether the database is currently open and accessible.
scid_error	scid_database_import_pgn(scid_database * database, const char * pgn, size_t pgn_size, char * out_diagnostic, size_t out_diagnostic_capacity, size_t * out_diagnostic_size, size_t * out_imported_count) Parses and imports one or more PGN games from a text buffer into the database.
scid_error	scid_database_game_undelete(scid_database * database, size_t index) Clears the deleted flag for a game (restores a soft-deleted game).
scid_error	scid_database_game_tag_get(const scid_database * database, size_t index, const char * name, char * out_text, size_t out_text_capacity, size_t * out_text_size) Queries a specific header tag value directly from the fast database index without loading the game.
scid_error	scid_database_game_result_get(const scid_database * database, size_t index, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the game outcome result string directly from the database header index.
scid_error	scid_database_game_replace(scid_database * database, size_t index, const scid_game * game, const char * flags) Replaces an existing game at a specified zero-based index.
scid_error	scid_database_game_number_get(const scid_database * database, size_t index, size_t * out_number) Retrieves the 1-based sequential game number (`index + 1`).
scid_error	scid_database_game_halfmove_count_get(const scid_database * database, size_t index, size_t * out_count) Retrieves the halfmove (ply) count of a game directly from the database header index.
scid_error	scid_database_game_get(const scid_database * database, size_t index, scid_game ** out_game, char * out_flags, size_t out_flags_capacity, size_t * out_flags_size) Decodes and retrieves a full scid_game entity from the database by index.
scid_error	scid_database_game_export_pgn(const scid_database * database, size_t index, char * out_text, size_t out_text_capacity, size_t * out_text_size) Exports a game from the database directly into PGN text format.
scid_error	scid_database_game_eco_get(const scid_database * database, size_t index, scid_eco_code * out_code) Retrieves the classified ECO code of a game directly from the database header index.
scid_error	scid_database_game_deleted_get(const scid_database * database, size_t index, int * out_deleted) Checks if a game at a specified index is marked as deleted.
scid_error	scid_database_game_delete(scid_database * database, size_t index) Marks a game as deleted (soft deletion).
scid_error	scid_database_game_date_get(const scid_database * database, size_t index, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the played date of a game directly from the database header index.
scid_error	scid_database_game_count_get(const scid_database * database, size_t * out_count) Retrieves the total number of games stored in the database.
scid_error	scid_database_game_add(scid_database * database, const scid_game * game, const char * flags) Appends a new game to the end of the database.
void	scid_database_free(scid_database * database) Releases a database handle, closing underlying files if still open.
scid_error	scid_database_filename_get(const scid_database * database, char * out_text, size_t out_text_capacity, size_t * out_text_size) Retrieves the filesystem path or name of the database.
scid_error	scid_database_create_scid5(const char * path, scid_database ** out_database) Creates a new, empty persistent Scid 5 binary database on disk.
scid_error	scid_database_create_memory(const char * name, scid_database ** out_database) Creates a new empty in-memory chess database.
scid_error	scid_database_close(scid_database * database) Flushes unwritten changes and closes all underlying storage files.

Types Documentation

typedef scid_should_cancel_fn

typedef int(* scid_should_cancel_fn) (void *user_data);

Function pointer type for querying early cancellation of long-running operations.

Parameters:

user_data User context pointer passed to the initiating function.

Return: Non-zero (1) to request immediate cooperative cancellation; zero (0) to proceed.

typedef scid_progress_report_callback

typedef void(* scid_progress_report_callback) (size_t done, size_t total, const char *message, void *user_data);

Function pointer type for long-running asynchronous progress notifications.

Parameters:

done Count of items completed so far (e.g. bytes parsed, games scanned).
total Total expected item count, or 0 if unknown.
message Optional descriptive phase message (may be NULL).
user_data User context pointer passed to the initiating function.

typedef scid_database

typedef struct scid_database scid_database;

Opaque handle representing an open chess database.

See:

Manages a collection of indexed chess games, header caches, name dictionaries, and custom metadata. Supports multiple underlying storage engines:

In-Memory: Volatile, high-speed RAM-backed storage.
Scid 5 (.si5, .sg5, .sn5): High-performance binary database with fast header indices.
PGN (.pgn): Read-only plain-text Portable Game Notation archive with in-memory index.

Database handles are created via factory functions (scid_database_create_memory(), scid_database_create_scid5(), scid_database_open_scid5(), etc.) and must be released using scid_database_free().

Functions Documentation

function scid_database_type_get

scid_error scid_database_type_get(
    const scid_database * database,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the database storage backend type string (e.g.

Parameters:

database Pointer to the database. Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated type string. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Type string retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

"memory", "scid5", "pgn").

function scid_database_status_open_get

scid_error scid_database_status_open_get(
    const scid_database * database,
    scid_error * out_status
)

Queries the initial open status code (e.g.

Parameters:

database Pointer to the database handle. Must not be NULL.
out_status Pointer receiving the initial open status code. Must not be NULL.

Returns:

SCID_OK Status code retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_status is NULL.

SCID_OK or SCID_WARNING_NAME_DATA_LOSS).

function scid_database_status_is_read_only

scid_error scid_database_status_is_read_only(
    const scid_database * database,
    int * out_is_read_only
)

Checks whether the database session is operating in read-only mode.

Parameters:

database Pointer to the database handle. Must not be NULL.
out_is_read_only Pointer receiving non-zero (1) if read-only; zero (0) if writable. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If database or out_is_read_only is NULL.

function scid_database_status_is_dirty

scid_error scid_database_status_is_dirty(
    const scid_database * database,
    int * out_is_dirty
)

Checks whether the database session contains unpersisted in-memory modifications.

Parameters:

database Pointer to the database handle. Must not be NULL.
out_is_dirty Pointer receiving non-zero (1) if modifications exist; zero (0) if clean. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If database or out_is_dirty is NULL.

function scid_database_status_bad_name_count_get

scid_error scid_database_status_bad_name_count_get(
    const scid_database * database,
    size_t * out_count
)

Returns the count of corrupted or unresolvable name identifiers encountered during open.

Parameters:

database Pointer to the database handle. Must not be NULL.
out_count Pointer receiving the count of invalid name references (0 if clean). Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_count is NULL.

function scid_database_stats_result_count_get

scid_error scid_database_stats_result_count_get(
    const scid_database * database,
    const char * result,
    size_t * out_count
)

Retrieves the total number of games matching a specific outcome result string.

Parameters:

database Pointer to the database. Must not be NULL.
result Result filter string ("1-0", "0-1", "1/2-1/2", or "*"). Must not be NULL.
out_count Pointer receiving the matching game count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If database, result, or out_count is NULL, or result is invalid.

function scid_database_stats_date_range_get

scid_error scid_database_stats_date_range_get(
    const scid_database * database,
    char * out_min_date,
    size_t out_min_date_capacity,
    size_t * out_min_date_size,
    char * out_max_date,
    size_t out_max_date_capacity,
    size_t * out_max_date_size
)

Retrieves the chronological date span (earliest and latest game dates) in the database.

Parameters:

database Pointer to the database. Must not be NULL.
out_min_date Caller-allocated buffer receiving the earliest date string. May be NULL if out_min_date_capacity is 0.
out_min_date_capacity Capacity of out_min_date in bytes.
out_min_date_size Pointer receiving bytes written for min date. Must not be NULL.
out_max_date Caller-allocated buffer receiving the latest date string. May be NULL if out_max_date_capacity is 0.
out_max_date_capacity Capacity of out_max_date in bytes.
out_max_date_size Pointer receiving bytes written for max date. Must not be NULL.

Returns:

SCID_OK Date range retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory pointer argument is NULL.
SCID_ERROR_BUFFER_FULL If either buffer capacity is insufficient.

Dates are formatted in standard PGN date notation ("YYYY.MM.DD").

function scid_database_save

scid_error scid_database_save(
    scid_database * database
)

Explicitly persists pending database modifications, header index updates, and name caches to disk.

Parameters:

database Pointer to the database to save. Must not be NULL.

Returns:

SCID_OK Database saved successfully.
SCID_ERROR_BAD_ARG If database is NULL.
SCID_ERROR If the database is read-only or an I/O error occurs.

function scid_database_read_only_get

scid_error scid_database_read_only_get(
    const scid_database * database,
    int * out_read_only
)

Checks if the database is opened in read-only mode.

Parameters:

database Pointer to the database. Must not be NULL.
out_read_only Pointer receiving non-zero (1) if read-only; zero (0) if read-write. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If database or out_read_only is NULL.

function scid_database_open_scid5_read_only

scid_error scid_database_open_scid5_read_only(
    const char * path,
    scid_progress_report_callback progress_report,
    void * progress_report_user_data,
    scid_should_cancel_fn should_cancel,
    void * should_cancel_user_data,
    scid_database ** out_database
)

Opens an existing Scid 5 database in read-only mode.

Parameters:

path Base filesystem path without extension (or with .si5). Must not be NULL.
progress_report Optional callback for opening progress notifications (may be NULL).
progress_report_user_data Context pointer passed to progress_report.
should_cancel Optional cancellation callback (may be NULL).
should_cancel_user_data Context pointer passed to should_cancel.
out_database Pointer to a handle pointer receiving the opened database handle. Must not be NULL.

Returns:

SCID_OK Database opened successfully.
SCID_WARNING_NAME_DATA_LOSS Database opened in degraded read-only mode due to unresolvable name records. out_database is valid.
SCID_ERROR_BAD_ARG If path or out_database is NULL.
SCID_ERROR If the database files cannot be found or read.
SCID_ERROR_USER_CANCEL If opening was cancelled by should_cancel.

See:

Note: On SCID_OK and SCID_WARNING_NAME_DATA_LOSS, the caller acquires ownership of out_database and must release it with scid_database_free(). On fatal errors, out_database is set to NULL.

Prevents accidental modification and allows concurrent read access from multiple processes.

function scid_database_open_scid5

scid_error scid_database_open_scid5(
    const char * path,
    scid_progress_report_callback progress_report,
    void * progress_report_user_data,
    scid_should_cancel_fn should_cancel,
    void * should_cancel_user_data,
    scid_database ** out_database
)

Opens an existing Scid 5 database for read-write operations.

Parameters:

path Base filesystem path without extension (or with .si5). Must not be NULL.
progress_report Optional callback for opening progress notifications (may be NULL).
progress_report_user_data Context pointer passed to progress_report.
should_cancel Optional cancellation callback (may be NULL).
should_cancel_user_data Context pointer passed to should_cancel.
out_database Pointer to a handle pointer receiving the opened database handle. Must not be NULL.

Returns:

SCID_OK Database opened successfully.
SCID_WARNING_NAME_DATA_LOSS Database opened in degraded read-only mode due to unresolvable name records. out_database is valid.
SCID_ERROR_BAD_ARG If path or out_database is NULL.
SCID_ERROR If the database files cannot be found or read.
SCID_ERROR_USER_CANCEL If opening was cancelled by should_cancel.

See:

Note: On SCID_OK and SCID_WARNING_NAME_DATA_LOSS, the caller acquires ownership of out_database and must release it with scid_database_free(). On fatal errors, out_database is set to NULL.

function scid_database_open_pgn_read_only

scid_error scid_database_open_pgn_read_only(
    const char * path,
    scid_progress_report_callback progress_report,
    void * progress_report_user_data,
    scid_should_cancel_fn should_cancel,
    void * should_cancel_user_data,
    scid_database ** out_database
)

Opens and indexes a plain-text PGN file in read-only mode.

Parameters:

path Filesystem path to the .pgn file. Must not be NULL.
progress_report Optional callback for indexing progress notifications (may be NULL).
progress_report_user_data Context pointer passed to progress_report.
should_cancel Optional cancellation callback (may be NULL).
should_cancel_user_data Context pointer passed to should_cancel.
out_database Pointer to a handle pointer receiving the opened database handle. Must not be NULL.

Returns:

SCID_OK Database opened and indexed successfully.
SCID_ERROR_BAD_ARG If path or out_database is NULL.
SCID_ERROR If the file cannot be opened or parsed.
SCID_ERROR_USER_CANCEL If indexing was cancelled by should_cancel.

Note: The caller acquires ownership of out_database and must release it with scid_database_free(). On fatal errors, out_database is set to NULL.

Parses all PGN game headers in the file to construct an in-memory index for fast random access without pre-loading full movetexts into memory.

function scid_database_metadata_set

scid_error scid_database_metadata_set(
    scid_database * database,
    const char * key,
    const char * value
)

Sets or updates a custom metadata property in the database.

Parameters:

database Pointer to the database. Must not be NULL.
key Null-terminated metadata key name. Must not be NULL.
value Null-terminated property value string. Must not be NULL.

Returns:

SCID_OK Property set successfully.
SCID_ERROR_BAD_ARG If database, key, or value is NULL.
SCID_ERROR If the database is read-only.

See: scid_database_metadata_get()

function scid_database_metadata_get

scid_error scid_database_metadata_get(
    const scid_database * database,
    const char * key,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves a custom metadata property value by key name.

Parameters:

database Pointer to the database. Must not be NULL.
key Null-terminated metadata key name (e.g. "description", "type"). Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated property value. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Property retrieved successfully.
SCID_ERROR_BAD_ARG If database, key, or out_text_size is NULL.
SCID_ERROR_NOT_FOUND If no metadata property exists with the given key.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_database_metadata_set()

function scid_database_metadata_count_get

scid_error scid_database_metadata_count_get(
    const scid_database * database,
    size_t * out_count
)

Retrieves the total number of custom metadata entries stored in the database.

Parameters:

database Pointer to the database. Must not be NULL.
out_count Pointer receiving the metadata entry count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_count is NULL.

See: scid_database_metadata_at_get()

function scid_database_metadata_at_get

scid_error scid_database_metadata_at_get(
    const scid_database * database,
    size_t index,
    char * out_key,
    size_t out_key_capacity,
    size_t * out_key_size,
    char * out_value,
    size_t out_value_capacity,
    size_t * out_value_size
)

Retrieves a metadata key-value pair by zero-based index.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the metadata entry (0..metadata_count - 1).
out_key Caller-allocated buffer receiving the key string. May be NULL if capacity is 0.
out_key_capacity Capacity of out_key in bytes.
out_key_size Pointer receiving key bytes written (excluding null terminator). Must not be NULL.
out_value Caller-allocated buffer receiving the value string. May be NULL if capacity is 0.
out_value_capacity Capacity of out_value in bytes.
out_value_size Pointer receiving value bytes written (excluding null terminator). Must not be NULL.

Returns:

SCID_OK Metadata pair retrieved successfully.
SCID_ERROR_BAD_ARG If any mandatory argument is NULL, or index is out of bounds.
SCID_ERROR_BUFFER_FULL If out_key_capacity or out_value_capacity is insufficient.

function scid_database_is_open

scid_error scid_database_is_open(
    const scid_database * database,
    int * out_is_open
)

Checks whether the database is currently open and accessible.

Parameters:

database Pointer to the database handle. Must not be NULL.
out_is_open Pointer receiving non-zero (1) if open; zero (0) if closed. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If database or out_is_open is NULL.

function scid_database_import_pgn

scid_error scid_database_import_pgn(
    scid_database * database,
    const char * pgn,
    size_t pgn_size,
    char * out_diagnostic,
    size_t out_diagnostic_capacity,
    size_t * out_diagnostic_size,
    size_t * out_imported_count
)

Parses and imports one or more PGN games from a text buffer into the database.

Parameters:

database Pointer to the database to append games to. Must not be NULL.
pgn Buffer containing raw PGN text. Must not be NULL.
pgn_size Size of the pgn buffer in bytes.
out_diagnostic Caller-allocated buffer receiving parser diagnostics on error. May be NULL if out_diagnostic_capacity is 0.
out_diagnostic_capacity Capacity of out_diagnostic in bytes.
out_diagnostic_size Pointer receiving diagnostic bytes written. May be NULL if unneeded.
out_imported_count Pointer receiving count of games successfully imported. Must not be NULL.

Returns:

SCID_OK PGN stream imported successfully.
SCID_ERROR_BAD_ARG If database, pgn, or out_imported_count is NULL.
SCID_ERROR If the database is read-only or parsing fails.

function scid_database_game_undelete

scid_error scid_database_game_undelete(
    scid_database * database,
    size_t index
)

Clears the deleted flag for a game (restores a soft-deleted game).

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game to restore (0..game_count - 1).

Returns:

SCID_OK Game undeleted successfully.
SCID_ERROR_BAD_ARG If database is NULL, or index is out of range.
SCID_ERROR If the database is read-only.

See:

function scid_database_game_tag_get

scid_error scid_database_game_tag_get(
    const scid_database * database,
    size_t index,
    const char * name,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Queries a specific header tag value directly from the fast database index without loading the game.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
name Header tag name (e.g. "White", "Black", "Event", "Site", "Date"). Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated tag value. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Tag value retrieved successfully.
SCID_ERROR_BAD_ARG If database, name, or out_text_size is NULL, or index is out of range.
SCID_ERROR_NOT_FOUND If the tag is not present in the game header.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_database_game_result_get

scid_error scid_database_game_result_get(
    const scid_database * database,
    size_t index,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the game outcome result string directly from the database header index.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_text Caller-allocated buffer receiving the null-terminated result string ("1-0", "0-1", "1/2-1/2", or "*"). May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Result string retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_text_size is NULL, or index is out of range.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_database_game_replace

scid_error scid_database_game_replace(
    scid_database * database,
    size_t index,
    const scid_game * game,
    const char * flags
)

Replaces an existing game at a specified zero-based index.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game to replace (0..game_count - 1).
game Pointer to the new game entity. Must not be NULL.
flags Optional user flags string, or NULL/"" for none.

Returns:

SCID_OK Game replaced successfully.
SCID_ERROR_BAD_ARG If database or game is NULL, or index is out of range.
SCID_ERROR If the database is read-only.

See: scid_database_game_add()

function scid_database_game_number_get

scid_error scid_database_game_number_get(
    const scid_database * database,
    size_t index,
    size_t * out_number
)

Retrieves the 1-based sequential game number (index + 1).

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_number Pointer receiving the 1-based game number. Must not be NULL.

Returns:

SCID_OK Number retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_number is NULL, or index is out of range.

function scid_database_game_halfmove_count_get

scid_error scid_database_game_halfmove_count_get(
    const scid_database * database,
    size_t index,
    size_t * out_count
)

Retrieves the halfmove (ply) count of a game directly from the database header index.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_count Pointer receiving the halfmove count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_count is NULL, or index is out of range.

function scid_database_game_get

scid_error scid_database_game_get(
    const scid_database * database,
    size_t index,
    scid_game ** out_game,
    char * out_flags,
    size_t out_flags_capacity,
    size_t * out_flags_size
)

Decodes and retrieves a full scid_game entity from the database by index.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_game Pointer to a handle pointer receiving the newly allocated game entity. Must not be NULL.
out_flags Optional caller-allocated buffer receiving user flags string (may be NULL).
out_flags_capacity Capacity of out_flags in bytes.
out_flags_size Pointer receiving user flags length (may be NULL if out_flags is NULL).

Returns:

SCID_OK Game loaded successfully.
SCID_ERROR_BAD_ARG If database or out_game is NULL, or index is out of range.
SCID_ERROR_BUFFER_FULL If out_flags_capacity is insufficient for user flags.

See: scid_database_game_export_pgn()

Note: The caller acquires ownership of out_game and must release it with scid_game_free().

function scid_database_game_export_pgn

scid_error scid_database_game_export_pgn(
    const scid_database * database,
    size_t index,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Exports a game from the database directly into PGN text format.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_text Caller-allocated buffer receiving the null-terminated PGN text. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK PGN text exported successfully.
SCID_ERROR_BAD_ARG If database or out_text_size is NULL, or index is out of range.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

See: scid_database_game_get()

function scid_database_game_eco_get

scid_error scid_database_game_eco_get(
    const scid_database * database,
    size_t index,
    scid_eco_code * out_code
)

Retrieves the classified ECO code of a game directly from the database header index.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_code Pointer receiving the scid_eco_code. Must not be NULL.

Returns:

SCID_OK ECO code retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_code is NULL, or index is out of range.

function scid_database_game_deleted_get

scid_error scid_database_game_deleted_get(
    const scid_database * database,
    size_t index,
    int * out_deleted
)

Checks if a game at a specified index is marked as deleted.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_deleted Pointer receiving non-zero (1) if deleted; zero (0) if active. Must not be NULL.

Returns:

SCID_OK Query completed successfully.
SCID_ERROR_BAD_ARG If database or out_deleted is NULL, or index is out of range.

See:

function scid_database_game_delete

scid_error scid_database_game_delete(
    scid_database * database,
    size_t index
)

Marks a game as deleted (soft deletion).

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game to mark deleted (0..game_count - 1).

Returns:

SCID_OK Game marked deleted successfully.
SCID_ERROR_BAD_ARG If database is NULL, or index is out of range.
SCID_ERROR If the database is read-only.

See:

The game remains in the database index but is flagged as deleted until compacted.

function scid_database_game_date_get

scid_error scid_database_game_date_get(
    const scid_database * database,
    size_t index,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the played date of a game directly from the database header index.

Parameters:

database Pointer to the database. Must not be NULL.
index Zero-based index of the game (0..game_count - 1).
out_text Caller-allocated buffer receiving the null-terminated date string ("YYYY.MM.DD"). May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving bytes written (excluding null terminator), or required capacity. Must not be NULL.

Returns:

SCID_OK Date string retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_text_size is NULL, or index is out of range.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_database_game_count_get

scid_error scid_database_game_count_get(
    const scid_database * database,
    size_t * out_count
)

Retrieves the total number of games stored in the database.

Parameters:

database Pointer to the database. Must not be NULL.
out_count Pointer receiving the total game count. Must not be NULL.

Returns:

SCID_OK Count retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_count is NULL.

function scid_database_game_add

scid_error scid_database_game_add(
    scid_database * database,
    const scid_game * game,
    const char * flags
)

Appends a new game to the end of the database.

Parameters:

database Pointer to the database. Must not be NULL.
game Pointer to the game entity to encode and append. Must not be NULL.
flags Optional user flags string (e.g. "W", "B", "D"), or NULL/"" for none.

Returns:

SCID_OK Game appended successfully.
SCID_ERROR_BAD_ARG If database or game is NULL.
SCID_ERROR If the database is read-only.

See: scid_database_game_replace()

function scid_database_free

void scid_database_free(
    scid_database * database
)

Releases a database handle, closing underlying files if still open.

Parameters:

database Pointer to the database handle to release. If NULL, this function performs no action.

Note: Passing NULL is guaranteed to be a safe no-op.

function scid_database_filename_get

scid_error scid_database_filename_get(
    const scid_database * database,
    char * out_text,
    size_t out_text_capacity,
    size_t * out_text_size
)

Retrieves the filesystem path or name of the database.

Parameters:

database Pointer to the database. Must not be NULL.
out_text Caller-allocated buffer receiving the null-terminated filename string. May be NULL if out_text_capacity is 0 to query required capacity.
out_text_capacity Capacity of out_text in bytes.
out_text_size Pointer receiving the number of bytes written (excluding null terminator), or required capacity if the buffer is too small. Must not be NULL.

Returns:

SCID_OK Filename retrieved successfully.
SCID_ERROR_BAD_ARG If database or out_text_size is NULL.
SCID_ERROR_BUFFER_FULL If out_text_capacity is insufficient.

function scid_database_create_scid5

scid_error scid_database_create_scid5(
    const char * path,
    scid_database ** out_database
)

Creates a new, empty persistent Scid 5 binary database on disk.

Parameters:

path Base filesystem path without extension (or with .si5). Must not be NULL.
out_database Pointer to a handle pointer receiving the newly created database handle. Must not be NULL.

Returns:

SCID_OK Database created successfully.
SCID_ERROR_BAD_ARG If path or out_database is NULL.
SCID_ERROR If the files cannot be created or already exist.

See: scid_database_open_scid5()

Note: The caller acquires ownership of out_database and must release it with scid_database_free().

Creates the triplet of Scid 5 files: <path>.si5 (index), <path>.sg5 (gamedata), and <path>.sn5 (name dictionary).

function scid_database_create_memory

scid_error scid_database_create_memory(
    const char * name,
    scid_database ** out_database
)

Creates a new empty in-memory chess database.

Parameters:

name Descriptive identifier for the database. Must not be NULL.
out_database Pointer to a handle pointer receiving the newly allocated database. Must not be NULL.

Returns:

SCID_OK Database created successfully.
SCID_ERROR_BAD_ARG If name or out_database is NULL.

See: scid_database_free()

Note: The caller acquires ownership of out_database and must release it with scid_database_free().

In-memory databases provide fast transient game storage and search capabilities without writing files to disk.

function scid_database_close

scid_error scid_database_close(
    scid_database * database
)

Flushes unwritten changes and closes all underlying storage files.

Parameters:

database Pointer to the database handle. Must not be NULL.

Returns:

SCID_OK Database closed successfully.
SCID_ERROR_BAD_ARG If database is NULL.

See:

Updated on 2026-09-02 at 15:26:09 +0000