dm_db Module

SQLite core API access.


Uses

  • module~~dm_db~~UsesGraph module~dm_db dm_db iso_c_binding iso_c_binding module~dm_db->iso_c_binding module~dm_db_query dm_db_query module~dm_db->module~dm_db_query module~dm_error dm_error module~dm_db->module~dm_error module~dm_kind dm_kind module~dm_db->module~dm_kind module~dm_util dm_util module~dm_db->module~dm_util sqlite3 sqlite3 module~dm_db->sqlite3 module~dm_db_query->module~dm_error module~dm_db_query->module~dm_kind module~dm_error->module~dm_kind module~dm_ascii dm_ascii module~dm_error->module~dm_ascii iso_fortran_env iso_fortran_env module~dm_kind->iso_fortran_env module~dm_util->module~dm_error module~dm_util->module~dm_kind

Used by

  • module~~dm_db~~UsedByGraph module~dm_db dm_db module~dm_db_api dm_db_api module~dm_db_api->module~dm_db module~dm_db_count dm_db_count module~dm_db_api->module~dm_db_count module~dm_db_pragma dm_db_pragma module~dm_db_api->module~dm_db_pragma module~dm_db_row dm_db_row module~dm_db_api->module~dm_db_row module~dm_db_table dm_db_table module~dm_db_api->module~dm_db_table module~dm_db_count->module~dm_db module~dm_db_json dm_db_json module~dm_db_json->module~dm_db module~dm_db_json->module~dm_db_count module~dm_db_json->module~dm_db_row module~dm_db_pragma->module~dm_db module~dm_db_row->module~dm_db module~dm_db_table->module~dm_db module~dmpack dmpack module~dmpack->module~dm_db module~dmpack->module~dm_db_api module~dmpack->module~dm_db_count module~dmpack->module~dm_db_json module~dmpack->module~dm_db_pragma module~dmpack->module~dm_db_row module~dmpack->module~dm_db_table

Variables

Type Visibility Attributes Name Initial
integer, public, parameter :: DB_TRANS_DEFERRED = 0

Deferred transaction (default).
integer, public, parameter :: DB_TRANS_IMMEDIATE = 1

Start a new write immediately (may fail with E_DB_BUSY).
integer, public, parameter :: DB_TRANS_EXCLUSIVE = 2

No reading while transactions are underway.

Interfaces

public interface dm_db_bind

Generic bind function.

  • private function db_bind_double(db_stmt, index, value) result(rc)

    Binds 64-bit real value to statement. Returns E_DB_BIND on error.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Value index.
    real(kind=r8), intent(in) :: value

    Value.

    Return Value integer

  • private function db_bind_int(db_stmt, index, value) result(rc)

    Binds 32-bit integer value to statement. Returns E_DB_BIND on error.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Value index.
    integer(kind=i4), intent(in) :: value

    Value.

    Return Value integer

  • private function db_bind_int64(db_stmt, index, value) result(rc)

    Binds 64-bit integer value to statement. Returns E_DB_BIND on error.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Value index.
    integer(kind=i8), intent(in) :: value

    Value.

    Return Value integer

  • private function db_bind_query(db_stmt, db_query) result(rc)

    Binds query parameters to SQLite statement. Returns E_DB_BIND on binding error.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    type(db_query_type), intent(inout) :: db_query

    Database query type.

    Return Value integer

  • private function db_bind_text(db_stmt, index, value) result(rc)

    Binds string value to statement. The value will be trimmed before binding. Returns E_DB_BIND on error.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Value index.
    character(len=*), intent(in) :: value

    Value.

    Return Value integer

public interface dm_db_changes

Generic routine to return number of rows changed.

  • private subroutine db_changes_int32(db, n)

    The function returns the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection. Auxiliary changes caused by triggers, foreign key actions or REPLACE constraint resolution are not counted.

    Arguments

    Type IntentOptional Attributes Name
    type(db_type), intent(inout) :: db

    Database type.
    integer(kind=i4), intent(out) :: n

    Number of changes.

  • private subroutine db_changes_int64(db, n)

    The function returns the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection. Auxiliary changes caused by triggers, foreign key actions or REPLACE constraint resolution are not counted.

    Arguments

    Type IntentOptional Attributes Name
    type(db_type), intent(inout) :: db

    Database type.
    integer(kind=i8), intent(out) :: n

    Number of changes.

public interface dm_db_column

Generic column function.

  • private subroutine db_column_allocatable(db_stmt, index, value)

    Returns string value from column of given index.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Column index.
    character(len=:), intent(out), allocatable :: value

    Value.

  • private subroutine db_column_double(db_stmt, index, value)

    Returns double value from column of given index.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Column index.
    real(kind=r8), intent(out) :: value

    Value.

  • private subroutine db_column_int(db_stmt, index, value)

    Returns 32-bit integer value from column of given index.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Column index.
    integer(kind=i4), intent(out) :: value

    Value.

  • private subroutine db_column_int64(db_stmt, index, value)

    Returns 64-bit integer value from column of given index.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Column index.
    integer(kind=i8), intent(out) :: value

    Value.

  • private subroutine db_column_text(db_stmt, index, value, n)

    Returns string value from column of given index.

    Arguments

    Type IntentOptional Attributes Name
    type(db_stmt_type), intent(inout) :: db_stmt

    Database statement type.
    integer, intent(in) :: index

    Column index.
    character(len=*), intent(inout) :: value

    Value.
    integer, intent(out) :: n

    Actual string length.

Abstract Interfaces

abstract interface

  • public function dm_db_busy_callback(client_data, n) bind(c)

    C-interoperable callback function that is invoked on error SQL_BUSY. May return 0 to signal that no more invocations are desired.

    Arguments

    Type IntentOptional Attributes Name
    type(c_ptr), intent(in), value :: client_data

    Client data.
    integer(kind=c_int), intent(in), value :: n

    Number of times the busy callback has been invoked previously.

    Return Value integer(kind=c_int)

    Returns value.

abstract interface

  • public subroutine dm_db_backup_callback(remaining, page_count)

    Callback routine that is invoked if passed to dm_db_backup().

    Arguments

    Type IntentOptional Attributes Name
    integer, intent(in) :: remaining

    Remaining pages.
    integer, intent(in) :: page_count

    Total number of pages.

abstract interface

  • public subroutine dm_db_log_callback(client_data, err_code, err_msg_ptr) bind(c)

    C-interoperable callback routine that is invoked for each created SQLite log.

    Arguments

    Type IntentOptional Attributes Name
    type(c_ptr), intent(in), value :: client_data

    Client data.
    integer(kind=c_int), intent(in), value :: err_code

    SQLite error code.
    type(c_ptr), intent(in), value :: err_msg_ptr

    SQLite error message.

abstract interface

  • public subroutine dm_db_update_callback(client_data, type, db_name, table_name, row_id) bind(c)

    C-interoperable callback routine that is invoked on database updates.

    Arguments

    Type IntentOptional Attributes Name
    type(c_ptr), intent(in), value :: client_data

    Client data.
    integer(kind=c_int), intent(in), value :: type

    Database operation.
    type(c_ptr), intent(in), value :: db_name

    Database name.
    type(c_ptr), intent(in), value :: table_name

    Table name.
    integer(kind=c_int64_t), intent(in), value :: row_id

    Row id.

Derived Types

type, public ::  db_type

SQLite database connectivity type.

Components

Type Visibility Attributes Name Initial
type(c_ptr), public :: ctx = c_null_ptr

C pointer to SQLite 3 database.
logical, public :: read_only = .false.

Read-only flag.

type, public ::  db_stmt_type

SQLite database statement type.

Components

Type Visibility Attributes Name Initial
type(c_ptr), public :: ctx = c_null_ptr

C pointer to SQLite 3 statement.

Functions

public function dm_db_attach(db, path, name) result(rc)

Attaches the database at path to the current connection. If no name is passed for the attached database, the name will be set to attached. The function trims the given path and name strings.

Read more…

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
character(len=*), intent(in) :: path

Path of database to attach.
character(len=*), intent(in), optional :: name

Name of attached database.

Return Value integer

public function dm_db_begin(db, mode) result(rc)

Starts a transactions in IMMEDIATE mode. Mode shall be either DB_TRANS_DEFERRED, DB_TRANS_IMMEDIATE, or DB_TRANS_EXLCUSIVE. Default is DB_TRANS_IMMEDIATE.

Read more…

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
integer, intent(in), optional :: mode

Transaction mode.

Return Value integer

public function dm_db_column_is_float(db_stmt, index) result(is)

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt
integer, intent(in) :: index

Return Value logical

public function dm_db_column_is_integer(db_stmt, index) result(is)

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt
integer, intent(in) :: index

Return Value logical

public function dm_db_column_is_text(db_stmt, index) result(is)

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt
integer, intent(in) :: index

Return Value logical

public function dm_db_commit(db) result(rc)

Commits a transaction. Returns E_DB_EXEC on error.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.

Return Value integer

public function dm_db_detach(db, name) result(rc)

Detaches database from the current connection. If no name is passed for the attached database, the name is assumed to be attached. The function trims the given name string. Returns E_DB_DETACH on error.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
character(len=*), intent(in), optional :: name

Name of attached database.

Return Value integer

public function dm_db_error(db, sqlite_error) result(rc)

Returns last database error as DMPACK error code, optionally the SQLite error code in argument sqlite_error. This function matches an SQLite error code to the corresponding DMPACK error code. For example, if the last SQLite error is SQLITE_OK, the function returns E_NONE.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
integer, intent(out), optional :: sqlite_error

SQLite error code.

Return Value integer

public function dm_db_error_message(db) result(message)

Returns last SQLite error message.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.

Return Value character(len=:), allocatable

Error message.

public function dm_db_exec(db, query, error_message) result(rc)

Executes given query, and returns optional error message if rc is not E_NONE. Otherwise, err_msg is not allocated. Returns E_DB_EXEC on error

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
character(len=*), intent(in) :: query

SQL query.
character(len=:), intent(out), optional, allocatable :: error_message

Optional error message.

Return Value integer

public function dm_db_init() result(rc)

Initialises SQLite backend. Returns E_DB on error.

Arguments

None

Return Value integer

public function dm_db_is_connected(db) result(is)

Returns .true. if database type has associated pointer.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.

Return Value logical

public function dm_db_is_prepared(db_stmt) result(prepared)

Returns .true. if given statement has been prepared.

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt

Database statement type.

Return Value logical

public function dm_db_is_read_only(db) result(is)

Returns .true. if database is in read-only mode. This function checks only the opaque database type for the read-only flag. It is still possible to enable ready-only access by calling dm_db_set_query_only(). The function dm_db_get_query_only() returns the status of the query_only pragma.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.

Return Value logical

public function dm_db_is_threadsafe() result(is)

Returns true if SQLite 3 was compiled threadsafe.

Arguments

None

Return Value logical

public function dm_db_prepare(db, db_stmt, sql) result(rc)

Prepares database statement. Returns E_DB_PREPARE on error.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
type(db_stmt_type), intent(inout) :: db_stmt

Database statement type.
character(len=*), intent(in) :: sql

SQL query.

Return Value integer

public function dm_db_release(db, name) result(rc)

Jumps back to a save point. Returns E_DB_EXEC on error.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
character(len=*), intent(in) :: name

Save point name.

Return Value integer

public function dm_db_reset(db_stmt) result(rc)

Resets database statement. The function returns E_DB on error.

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt

Database statement type.

Return Value integer

public function dm_db_rollback(db, name) result(rc)

Rolls a transaction back, optionally to save point name. The function returns E_DB_ROLLBACK is the rollback failed.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
character(len=*), intent(in), optional :: name

Save point name.

Return Value integer

public function dm_db_save_point(db, name) result(rc)

Creates a save point name. Returns E_DB_EXEC on error.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
character(len=*), intent(in) :: name

Save point name.

Return Value integer

public function dm_db_set_busy_callback(db, callback, client_data) result(rc)

Sets SQLite busy callback that is invoked whenever the database is busy.

Read more…

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
procedure(dm_db_busy_callback) :: callback

Callback function.
type(c_ptr), intent(in) :: client_data

C pointer to client data.

Return Value integer

public function dm_db_set_busy_timeout(db, msec) result(rc)

Sets SQLite busy timeout in msec. Returns E_DB on error.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
integer, intent(in) :: msec

Timeout in mseconds.

Return Value integer

public function dm_db_set_log_callback(callback, client_data) result(rc)

Sets SQLite error log callback. The dummy argument client_data is passed to the callback routine. The function returns E_DB on error.

Arguments

Type IntentOptional Attributes Name
procedure(dm_db_log_callback) :: callback

Callback routine.
type(c_ptr), intent(in), optional :: client_data

C pointer to client data.

Return Value integer

public function dm_db_set_update_callback(db, callback, client_data) result(rc)

Sets SQLite error log callback. The dummy argument client_data is passed to the callback routine. The function returns E_DB on error.

Arguments

Type IntentOptional Attributes Name
type(db_type), intent(inout) :: db

Database type.
procedure(dm_db_update_callback) :: callback

Callback routine.
type(c_ptr), intent(in), optional :: client_data

C pointer to client data.

Return Value integer

public function dm_db_shutdown() result(rc)

Finalises SQLite handle. Returns E_DB on error.

Arguments

None

Return Value integer

public function dm_db_step(db_stmt) result(rc)

Steps rows. Returns E_DB_STEP on error.

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt

Database statement type.

Return Value integer

public function dm_db_version(name) result(version)

Returns SQLite 3 library version as allocatable string.

Arguments

Type IntentOptional Attributes Name
logical, intent(in), optional :: name

Add prefix `libsqlite/'.

Return Value character(len=:), allocatable

Version string.


Subroutines

public subroutine dm_db_column_size(db_stmt, index, value)

Returns byte size of column value of given index.

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt

Database statement type.
integer, intent(in) :: index

Column index.
integer, intent(out) :: value

Value.

public subroutine dm_db_finalize(db_stmt, error)

Finalises given database statement. Sets error to E_NULL if statement is not associated and to E_DB_FINALIZE if finalisation failed.

Arguments

Type IntentOptional Attributes Name
type(db_stmt_type), intent(inout) :: db_stmt

Database statement type.
integer, intent(out), optional :: error

Error code.

public subroutine dm_db_log(err_code, err_msg)

Sends log message to SQLite error log handler. The callback has to be set through dm_db_set_log_callback() initially.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: err_code

Error code.
character(len=*), intent(in) :: err_msg

Error message.

public subroutine dm_db_sleep(msec)

Delays execution for given duration in msec.

Arguments

Type IntentOptional Attributes Name
integer, intent(in) :: msec

Time in [msec].