dm_db – DMPACK

Database abstraction layer over SQLite 3. The SQL statements are stored in module dm_sql.

Load the last 10 observations into allocatable array observs:

integer       :: rc
type(db_type) :: db
type(observ_type), allocatable :: observs(:)

rc = dm_db_open(db, '/var/dmpack/observ.sqlite')
rc = dm_db_select_observs(db, observs, desc=.true., limit=10)
rc = dm_db_close(db)

Using the iterator interface instead:

integer            :: rc      ! Return code.
type(db_type)      :: db      ! Database handle.
type(db_stmt_type) :: db_stmt ! Database statement.
type(observ_type)  :: observ  ! Returned observation.

rc = dm_db_open(db, '/var/dmpack/observ.sqlite')

do while (dm_is_ok(rc))
    rc = dm_db_select_observs(db, db_stmt, observ, desc=.true., limit=10)
    if (dm_is_ok(rc)) print '(a)', trim(observ%name)
end do

rc = dm_db_finalize(db_stmt)
rc = dm_db_close(db)

The database functions return E_NONE if the respective operation was successful.

Uses

- dm_string
- iso_c_binding
- dm_error
- dm_util
- dm_time
- dm_uuid
- sqlite3
- dm_sql
- dm_id
- dm_kind
Help

Graph Key

Nodes of different colours represent the following:

Solid arrows point from a submodule to the (sub)module which it is descended from. Dashed arrows point from a module or program unit to modules which it uses.

Used by

Help

Graph Key

Nodes of different colours represent the following:

Solid arrows point from a submodule to the (sub)module which it is descended from. Dashed arrows point from a module or program unit to modules which it uses.

Variables

Type	Visibility	Attributes		Name		Initial
integer,	public,	parameter	::	DB_JOURNAL_OFF	=	0	No rollback journals.
integer,	public,	parameter	::	DB_JOURNAL_DELETE	=	1	Delete journal (default).
integer,	public,	parameter	::	DB_JOURNAL_TRUNCATE	=	2	Delete journal by truncating (may be faster than `DB_JOURNAL_DELETE`).
integer,	public,	parameter	::	DB_JOURNAL_PERSIST	=	3	Overwrite journal instead of deleting (may be faster than deleting or truncating).
integer,	public,	parameter	::	DB_JOURNAL_MEMORY	=	4	Store journal in memory (fast, volatile).
integer,	public,	parameter	::	DB_JOURNAL_WAL	=	5	Use Write-Ahead Log (WAL) journal.
integer,	public,	parameter	::	DB_AUTO_VACUUM_NONE	=	0	No auto-vacuum (default).
integer,	public,	parameter	::	DB_AUTO_VACUUM_FULL	=	1	Enable auto-vacuum.
integer,	public,	parameter	::	DB_AUTO_VACUUM_INCREMENTAL	=	2	Vacuum requires additional PRAGMA.
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.
integer,	public,	parameter	::	DB_APPLICATION_ID	=	int(z'444D31')	Application id of DMPACK databases (`DM1` in ASCII).
integer,	public,	parameter	::	DB_USER_VERSION	=	1	Database schema version, increased on updates.
integer,	public,	parameter	::	DB_TIMEOUT_DEFAULT	=	1000	Default SQLite 3 busy timeout in mseconds.

Interfaces

public interface dm_db_begin

Starts a transaction. Public alias for db_begin().

Optional argument mode may be one of:

DB_TRANS_DEFERRED
DB_TRANS_IMMEDIATE
DB_TRANS_EXCLUSIVE

The default mode is DB_TRANS_DEFERRED.

private function 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.

The function returns the following error codes:

E_DB_TRANSACTION if the transaction failed.
E_INVALID if the transaction mode is invalid.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
integer,	intent(in),	optional		::	mode	Transaction mode.

Return Value integer

public interface dm_db_insert

Generic database insert function.

public function dm_db_insert_beat(db, beat, db_stmt, validate) result(rc)

Adds the given heartbeat to database. The beat data is validated by default.

The function returns the following error codes:

E_DB if statement reset failed.
E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if argument beat is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(beat_type),	intent(inout)		::	beat	Beat to insert.
type(db_stmt_type),	intent(inout),	optional	::	db_stmt	Database statement type.
logical,	intent(in),	optional	::	validate	Validate beat.

Return Value integer

public function dm_db_insert_beats(db, beats, transaction, validate) result(rc)

Adds array of beats to database. A transaction is used unless transaction is .false.. The beat data is validated by default.

The function returns the following error codes:

E_DB if statement reset failed.
E_DB_BIND if value binding failed.
E_DB_EXEC if execution of transaction statement failed.
E_DB_PREPARE if statement preparation failed.
E_DB_ROLLBACK if transaction rollback failed.
E_DB_STEP if step execution failed or no write permission.
E_DB_TRANSACTION if transaction failed.
E_EMPTY if array beats is empty.
E_INVALID if an element in beats is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(beat_type),	intent(inout)		::	beats(:)	Beat type array.
logical,	intent(in),	optional	::	transaction	Use SQL transaction.
logical,	intent(in),	optional	::	validate	Validate beats.

Return Value integer

public function dm_db_insert_log(db, log, validate) result(rc)

Adds the given log to database. The log data is validated by default.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if argument log is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(log_type),	intent(inout)		::	log	Log message to insert.
logical,	intent(in),	optional	::	validate	Validate log.

Return Value integer

public function dm_db_insert_node(db, node, validate) result(rc)

Adds the given node to database. The node data is validated by default.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if argument node is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(node_type),	intent(inout)		::	node	Node to insert.
logical,	intent(in),	optional	::	validate	Validate node.

Return Value integer

public function dm_db_insert_observ(db, observ, db_stmt, validate) result(rc)

Adds single observation to database, including receivers, requests, and responses. If the insert query fails, the transaction will be rolled back, i.e., no part of the observation is written to the database on error. The observation data is validated by default.

The function returns the following error codes:

E_DB if statement reset failed.
E_DB_BIND if value binding failed.
E_DB_EXEC if execution of transaction statement failed.
E_DB_PREPARE if statement preparation failed.
E_DB_ROLLBACK if transaction rollback failed.
E_DB_STEP if step execution failed or no write permission.
E_DB_TRANSACTION if transaction failed.
E_INVALID if argument observ is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(observ_type),	intent(inout)		::	observ	Observation type.
type(db_stmt_type),	intent(inout),	optional	::	db_stmt	Database statement type.
logical,	intent(in),	optional	::	validate	Validate observation.

Return Value integer

public function dm_db_insert_observs(db, observs, transaction, validate) result(rc)

Adds array of observations to database. A transaction is used unless transaction is .false.. The observation data is validated by default.

The function returns the following error codes:

E_DB if statement reset failed.
E_DB_BIND if value binding failed.
E_DB_EXEC if execution of transaction statement failed.
E_DB_PREPARE if statement preparation failed.
E_DB_ROLLBACK if transaction rollback failed.
E_DB_STEP if step execution failed or no write permission.
E_DB_TRANSACTION if transaction failed.
E_EMPTY if array observs is empty.
E_INVALID if an element in observs is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(observ_type),	intent(inout)		::	observs(:)	Observation type array.
logical,	intent(in),	optional	::	transaction	Use SQL transaction.
logical,	intent(in),	optional	::	validate	Validate observations.

Return Value integer

public function dm_db_insert_sensor(db, sensor, validate) result(rc)

Adds given sensor to database. The sensor data is validated by default.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if argument sensor is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(sensor_type),	intent(inout)		::	sensor	Sensor to insert.
logical,	intent(in),	optional	::	validate	Validate sensor.

Return Value integer

public function dm_db_insert_target(db, target, validate) result(rc)

Adds given target to database. The target data is validated by default.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if argument target is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(target_type),	intent(inout)		::	target	Target to insert.
logical,	intent(in),	optional	::	validate	Validate target.

Return Value integer

public interface dm_db_select

Generic database select function.

public function dm_db_select_beat(db, beat, node_id) result(rc)

Returns heartbeat associated with given node id in beat.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(beat_type),	intent(out)	::	beat	Returned beat type.
character(len=*),	intent(in)	::	node_id	Node id.

Return Value integer

public function dm_db_select_log(db, log, log_id) result(rc)

Returns log associated with given id in log.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(log_type),	intent(out)	::	log	Returned log data.
character(len=*),	intent(in)	::	log_id	Log id.

Return Value integer

public function dm_db_select_node(db, node, node_id) result(rc)

Returns node data associated with given id in node.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(node_type),	intent(out)	::	node	Returned node data.
character(len=*),	intent(in)	::	node_id	Node id.

Return Value integer

public function dm_db_select_observ(db, observ, observ_id) result(rc)

Returns observation referenced by the given id from database.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_FINALIZE if statement finalisation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(observ_type),	intent(out)	::	observ	Selected observation.
character(len=*),	intent(in)	::	observ_id	Observation id (UUID).

Return Value integer

public function dm_db_select_sensor(db, sensor, sensor_id) result(rc)

Returns sensor data associated with given sensor id from database.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(sensor_type),	intent(out)	::	sensor	Returned sensor data.
character(len=*),	intent(in)	::	sensor_id	Sensor id.

Return Value integer

public function dm_db_select_target(db, target, target_id) result(rc)

Returns target data associated with given target id from database.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(target_type),	intent(out)	::	target	Returned target data.
character(len=*),	intent(in)	::	target_id	Target id.

Return Value integer

public interface dm_db_select_beats

Generic beats select function.

private function db_select_beats_array(db, beats, limit, nbeats) result(rc)

Returns heatbeats from database in array beats. An optional limit may be passed in limit.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(beat_type),	intent(out),		allocatable	::	beats(:)	Returned beat types.
integer(kind=i8),	intent(in),	optional		::	limit	Max. number of beats.
integer(kind=i8),	intent(out),	optional		::	nbeats	Total number of beats in database.

Return Value integer

private function db_select_beats_iter(db, db_stmt, beat, limit) result(rc)

Iterator function that returns heatbeats from database in beat. An optional limit may be passed in limit. The statement db_stmt must be finalised once finished.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no more rows are available.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(db_stmt_type),	intent(inout)		::	db_stmt	Database statement type.
type(beat_type),	intent(out)		::	beat	Returned beat type.
integer(kind=i8),	intent(in),	optional	::	limit	Max. number of beats.

Return Value integer

public interface dm_db_select_data_points

Generic data points select function.

private function db_select_data_points_array(db, dps, node_id, sensor_id, target_id, response_name, from, to, error, limit, npoints) result(rc)

Returns data points from observations database in dps. This function selects only responses of error E_NONE, unless argument error is passed, then only of the given error code.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_BIND if value binding failed.
E_DB_FINALIZE if statement finalisation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(dp_type),	intent(out),		allocatable	::	dps(:)	Returned data points.
character(len=*),	intent(in)			::	node_id	Node id.
character(len=*),	intent(in)			::	sensor_id	Sensor id.
character(len=*),	intent(in)			::	target_id	Target id.
character(len=*),	intent(in)			::	response_name	Response name.
character(len=*),	intent(in)			::	from	Beginning of time span.
character(len=*),	intent(in)			::	to	End of time span.
integer,	intent(in),	optional		::	error	Response error code.
integer(kind=i8),	intent(in),	optional		::	limit	Max. number of data points.
integer(kind=i8),	intent(out),	optional		::	npoints	Number of data points.

Return Value integer

private function db_select_data_points_iter(db, db_stmt, dp, node_id, sensor_id, target_id, response_name, from, to, error, limit) result(rc)

Iterator function that returns data points from observations database in dp. This function selects only responses of error E_NONE, unless argument error is passed, then only of the given error code. The statement db_stmt must be finalised once finished.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no more rows are available.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(db_stmt_type),	intent(inout)		::	db_stmt	Database statement type.
type(dp_type),	intent(out)		::	dp	Returned data point.
character(len=*),	intent(in)		::	node_id	Node id.
character(len=*),	intent(in)		::	sensor_id	Sensor id.
character(len=*),	intent(in)		::	target_id	Target id.
character(len=*),	intent(in)		::	response_name	Response name.
character(len=*),	intent(in)		::	from	Beginning of time span.
character(len=*),	intent(in)		::	to	End of time span.
integer,	intent(in),	optional	::	error	Response error code.
integer(kind=i8),	intent(in),	optional	::	limit	Max. number of data points.

Return Value integer

public interface dm_db_select_json_beats

Generic JSON logs select function.

private function db_select_json_beats_array(db, strings, limit, nbeats) result(rc)

Returns beats in JSON format in allocatable string type array strings.

If no beats have been found, the array will be empty, and the function returns E_DB_NO_ROWS.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(string_type),	intent(out),		allocatable	::	strings(:)	Returned JSON array.
integer(kind=i8),	intent(in),	optional		::	limit	Max. number of beats.
integer(kind=i8),	intent(out),	optional		::	nbeats	Number of beats.

Return Value integer

private function db_select_json_beats_iter(db, db_stmt, json, limit) result(rc)

Iterator function that returns beats in JSON format in allocatable string json. The statement db_stmt must be finalised once finished.

If no beats have been found, the string will be empty, and the function returns E_DB_NO_ROWS.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(db_stmt_type),	intent(inout)			::	db_stmt	Database statement type.
character(len=:),	intent(out),		allocatable	::	json	Returned JSON.
integer(kind=i8),	intent(in),	optional		::	limit	Max. number of beats.

Return Value integer

public interface dm_db_select_json_logs

Generic JSON logs select function.

private function db_select_json_logs_array(db, strings, node_id, sensor_id, target_id, source, from, to, min_level, max_level, error, desc, limit, nlogs) result(rc)

Returns logs in JSON format in allocatable string type array strings.

If no logs have been found, the array will be empty, and the function returns E_DB_NO_ROWS.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_BIND if value binding failed.
E_DB_FINALIZE if statement finalisation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(string_type),	intent(out),		allocatable	::	strings(:)	Returned JSON array.
character(len=*),	intent(in),	optional		::	node_id	Node id.
character(len=*),	intent(in),	optional		::	sensor_id	Sensor id.
character(len=*),	intent(in),	optional		::	target_id	Target id.
character(len=*),	intent(in),	optional		::	source	Source name.
character(len=*),	intent(in),	optional		::	from	Begin of time range.
character(len=*),	intent(in),	optional		::	to	End of time range.
integer,	intent(in),	optional		::	min_level	Minimum log level.
integer,	intent(in),	optional		::	max_level	Maximum log level.
integer,	intent(in),	optional		::	error	Error code.
logical,	intent(in),	optional		::	desc	Descending order.
integer(kind=i8),	intent(in),	optional		::	limit	Max. numbers of logs.
integer(kind=i8),	intent(out),	optional		::	nlogs	Number of logs.

Return Value integer

private function db_select_json_logs_iter(db, db_stmt, json, node_id, sensor_id, target_id, source, from, to, min_level, max_level, error, desc, limit) result(rc)

Iterator function that returns logs in JSON format in allocatable character json. The statement db_stmt must be finalised once finished.

If no logs have been found, the string will be empty, and the function returns E_DB_NO_ROWS.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(db_stmt_type),	intent(inout)			::	db_stmt	Database statement type.
character(len=:),	intent(out),		allocatable	::	json	Returned JSON.
character(len=*),	intent(in),	optional		::	node_id	Node id.
character(len=*),	intent(in),	optional		::	sensor_id	Sensor id.
character(len=*),	intent(in),	optional		::	target_id	Target id.
character(len=*),	intent(in),	optional		::	source	Source name.
character(len=*),	intent(in),	optional		::	from	Begin of time range.
character(len=*),	intent(in),	optional		::	to	End of time range.
integer,	intent(in),	optional		::	min_level	Minimum log level.
integer,	intent(in),	optional		::	max_level	Maximum log level.
integer,	intent(in),	optional		::	error	Error code.
logical,	intent(in),	optional		::	desc	Descending order.
integer(kind=i8),	intent(in),	optional		::	limit	Max. numbers of logs.

Return Value integer

public interface dm_db_select_json_nodes

Generic JSON nodes select function.

private function db_select_json_nodes_array(db, strings, limit, nnodes) result(rc)

Returns nodes in JSON format in allocatable string type array strings.

If no nodes have been found, the array will be empty, and the function returns E_DB_NO_ROWS.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(string_type),	intent(out),		allocatable	::	strings(:)	Returned JSON array.
integer(kind=i8),	intent(in),	optional		::	limit	Max. number of nodes.
integer(kind=i8),	intent(out),	optional		::	nnodes	Number of nodes.

Return Value integer

private function db_select_json_nodes_iter(db, db_stmt, json, limit) result(rc)

Iterator function that returns nodes in JSON format in allocatable string json. The statement db_stmt must be finalised once finished.

If no nodes have been found, the string will be empty, and the function returns E_DB_NO_ROWS.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(db_stmt_type),	intent(inout)			::	db_stmt	Database statement type.
character(len=:),	intent(out),		allocatable	::	json	Returned JSON.
integer(kind=i8),	intent(in),	optional		::	limit	Max. number of nodes.

Return Value integer

public interface dm_db_select_logs

Generic logs select function.

private function db_select_logs_array(db, logs, node_id, sensor_id, target_id, source, from, to, min_level, max_level, error, desc, limit, nlogs) result(rc)

Returns logs in allocatable array logs.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_BIND if value binding failed.
E_DB_FINALIZE if statement finalisation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(log_type),	intent(out),		allocatable	::	logs(:)	Returned log data array.
character(len=*),	intent(in),	optional		::	node_id	Node id.
character(len=*),	intent(in),	optional		::	sensor_id	Sensor id.
character(len=*),	intent(in),	optional		::	target_id	Target id.
character(len=*),	intent(in),	optional		::	source	Source name.
character(len=*),	intent(in),	optional		::	from	Begin of time range.
character(len=*),	intent(in),	optional		::	to	End of time range.
integer,	intent(in),	optional		::	min_level	Minimum log level.
integer,	intent(in),	optional		::	max_level	Maximum log level.
integer,	intent(in),	optional		::	error	Error code.
logical,	intent(in),	optional		::	desc	Descending order.
integer(kind=i8),	intent(in),	optional		::	limit	Max. numbers of logs.
integer(kind=i8),	intent(out),	optional		::	nlogs	Total number of logs.

Return Value integer

private function db_select_logs_iter(db, db_stmt, log, node_id, sensor_id, target_id, source, from, to, min_level, max_level, error, desc, limit) result(rc)

Iterator function that returns logs in logs. The statement db_stmt must be finalised once finished.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(db_stmt_type),	intent(inout)		::	db_stmt	Database statement type.
type(log_type),	intent(out)		::	log	Returned log type.
character(len=*),	intent(in),	optional	::	node_id	Node id.
character(len=*),	intent(in),	optional	::	sensor_id	Sensor id.
character(len=*),	intent(in),	optional	::	target_id	Target id.
character(len=*),	intent(in),	optional	::	source	Source name.
character(len=*),	intent(in),	optional	::	from	Begin of time range.
character(len=*),	intent(in),	optional	::	to	End of time range.
integer,	intent(in),	optional	::	min_level	Minimum log level.
integer,	intent(in),	optional	::	max_level	Maximum log level.
integer,	intent(in),	optional	::	error	Error code.
logical,	intent(in),	optional	::	desc	Descending order.
integer(kind=i8),	intent(in),	optional	::	limit	Max. numbers of logs.

Return Value integer

public interface dm_db_select_nodes

Generic nodes select function.

private function db_select_nodes_array(db, nodes, nnodes) result(rc)

Returns all sensor nodes in allocatable array nodes.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(node_type),	intent(out),		allocatable	::	nodes(:)	Returned node data array.
integer(kind=i8),	intent(out),	optional		::	nnodes	Number of nodes.

Return Value integer

private function db_select_nodes_iter(db, db_stmt, node) result(rc)

Iterator function that returns all sensor nodes in node. The statement db_stmt must be finalised once finished.

The function returns the following error codes:

E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(db_stmt_type),	intent(inout)	::	db_stmt	Database statement type.
type(node_type),	intent(out)	::	node	Returned node data.

Return Value integer

public interface dm_db_select_observs

Generic observations select function.

private function db_select_observs_array(db, observs, node_id, sensor_id, target_id, from, to, desc, limit, stub, nobservs) result(rc)

Returns observations in observs, with optional node id, sensor id, target id, from, to. By default, observations are returned in ascending order, unless desc is passed and .true.. The maximum number of observations may be passed in limit.

The stub is .true., neither receivers nor requests are read from database.

The total number of observations is returned in optional argument nobservs.

Calling this function is usually slower than db_select_observs_by_id() or db_select_observs_by_time().

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_BIND if value binding failed.
E_DB_FINALIZE if statement finalisation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(observ_type),	intent(out),		allocatable	::	observs(:)	Returned observation data.
character(len=*),	intent(in),	optional		::	node_id	Node id.
character(len=*),	intent(in),	optional		::	sensor_id	Sensor id.
character(len=*),	intent(in),	optional		::	target_id	Target id.
character(len=*),	intent(in),	optional		::	from	Beginning of time span.
character(len=*),	intent(in),	optional		::	to	End of time span.
logical,	intent(in),	optional		::	desc	Descending order.
integer(kind=i8),	intent(in),	optional		::	limit	Max. number of observations.
logical,	intent(in),	optional		::	stub	Without receivers, requests, responses.
integer(kind=i8),	intent(out),	optional		::	nobservs	Total number of observations (may be greater than limit).

Return Value integer

private function db_select_observs_iter(db, db_stmt, observ, node_id, sensor_id, target_id, from, to, desc, limit, stub) result(rc)

Iterator function that returns observations in observ, with optional node id, sensor id, target id, from, to. By default, observations are returned in ascending order, unless desc is passed and .true.. The maximum number of observations may be passed in limit. The statement db_stmt must be finalised once finished.

The stub is .true., neither receivers nor requests are read from database.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(db_stmt_type),	intent(inout)		::	db_stmt	Database statement type.
type(observ_type),	intent(out)		::	observ	Returned observation type.
character(len=*),	intent(in),	optional	::	node_id	Node id.
character(len=*),	intent(in),	optional	::	sensor_id	Sensor id.
character(len=*),	intent(in),	optional	::	target_id	Target id.
character(len=*),	intent(in),	optional	::	from	Beginning of time span.
character(len=*),	intent(in),	optional	::	to	End of time span.
logical,	intent(in),	optional	::	desc	Descending order.
integer(kind=i8),	intent(in),	optional	::	limit	Max. number of observations.
logical,	intent(in),	optional	::	stub	Without receivers, requests, responses.

Return Value integer

public interface dm_db_select_sensors

Generic sensors select function.

private function db_select_sensors_array(db, sensors, nsensors) result(rc)

Returns all sensors in allocatable array sensors.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(sensor_type),	intent(out),		allocatable	::	sensors(:)	Returned sensor data array.
integer(kind=i8),	intent(out),	optional		::	nsensors	Number of returned sensors.

Return Value integer

private function db_select_sensors_iter(db, db_stmt, sensor) result(rc)

Iterator function that returns all sensors in sensor. The statement db_stmt must be finalised once finished.

The function returns the following error codes:

E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(db_stmt_type),	intent(inout)	::	db_stmt	Database statement type.
type(sensor_type),	intent(out)	::	sensor	Returned sensor data.

Return Value integer

private function db_select_sensors_by_node_array(db, node_id, sensors, nsensors) result(rc)

Returns all sensors of node node_id in allocatable array sensors.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_INVALID if node id is empty.
E_DB_BIND if value binding failed.
E_DB_FINALIZE if statement finalisation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
character(len=*),	intent(in)			::	node_id	Node id.
type(sensor_type),	intent(out),		allocatable	::	sensors(:)	Returned sensor data array.
integer(kind=i8),	intent(out),	optional		::	nsensors	Number of returned sensors.

Return Value integer

private function db_select_sensors_by_node_iter(db, db_stmt, node_id, sensor) result(rc)

Iterator function that returns all sensors of node node_id in sensor. The statement db_stmt must be finalised once finished.

The function returns the following error codes:

E_INVALID if node id is empty.
E_DB_BIND if value binding failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(db_stmt_type),	intent(inout)	::	db_stmt	Database statement type.
character(len=*),	intent(in)	::	node_id	Node id.
type(sensor_type),	intent(out)	::	sensor	Returned sensor data.

Return Value integer

public interface dm_db_select_targets

Generic targets select function.

private function db_select_targets_array(db, targets, ntargets) result(rc)

Returns number of targets and array of target data in allocatable array targets, if query was successful.

The function returns the following error codes:

E_ALLOC if memory allocation failed.
E_DB_NO_ROWS if no rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent	Optional	Attributes		Name
type(db_type),	intent(inout)			::	db	Database type.
type(target_type),	intent(out),		allocatable	::	targets(:)	Target data array.
integer(kind=i8),	intent(out),	optional		::	ntargets	Number of selected targets.

Return Value integer

private function db_select_targets_iter(db, db_stmt, target) result(rc)

Iterator function that returns all targets in target. The statement db_stmt must be finalised once finished.

The function returns the following error codes:

E_DB_NO_ROWS if no more rows are returned.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(db_stmt_type),	intent(inout)	::	db_stmt	Database statement type.
type(target_type),	intent(out)	::	target	Target data.

Return Value integer

public interface dm_db_update

Generic database update function.

public function dm_db_update_node(db, node, validate) result(rc)

Updates the given node in database. The node data is validated by default.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if node is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(node_type),	intent(inout)		::	node	Node to update.
logical,	intent(in),	optional	::	validate	Validate node.

Return Value integer

public function dm_db_update_sensor(db, sensor, validate) result(rc)

Updates given sensor in database. The sensor data is validated by default.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if sensor is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(sensor_type),	intent(inout)		::	sensor	Sensor to update.
logical,	intent(in),	optional	::	validate	Validate sensor.

Return Value integer

public function dm_db_update_target(db, target, validate) result(rc)

Updates the given target in database. The target data is validated by default.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_PREPARE if statement preparation failed.
E_DB_STEP if step execution failed or no write permission.
E_INVALID if target is invalid.
E_READ_ONLY if database is opened read-only.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(target_type),	intent(inout)		::	target	Target to update.
logical,	intent(in),	optional	::	validate	Validate target.

Return Value integer

Abstract Interfaces

abstract interface

public function dm_db_busy_handler(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	Intent	Optional	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 handler has been invoked previously.

Return Value integer(kind=c_int)

Returns value.

abstract interface

public subroutine dm_db_backup_handler(remaining, page_count)

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

Arguments

Type	Intent	Optional	Attributes		Name
integer,	intent(in)			::	remaining	Remaining pages.
integer,	intent(in)			::	page_count	Total number of pages.

abstract interface

public subroutine dm_db_log_handler(client_data, err_code, err_msg_ptr) bind(c)

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

Arguments

Type	Intent	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_handler(client_data, type, db_name, table_name, row_id) bind(c)

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

Arguments

Type	Intent	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

Opaque SQLite database connectivity type.

type, public :: db_stmt_type

Opaque SQLite database statement type.

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.

Type	Intent	Optional	Attributes		Name
procedure(dm_db_log_handler)				::	callback	Callback routine.
type(c_ptr),	intent(in),	optional		::	client_data	C pointer to client data.

dm_db Module

Contents

Variables

Interfaces

Abstract Interfaces

Derived Types

Functions

Subroutines

Uses

Used by

Variables

Interfaces

public interface dm_db_begin

private function db_begin(db, mode) result(rc)

Arguments

Return Value integer

public interface dm_db_insert

public function dm_db_insert_beat(db, beat, db_stmt, validate) result(rc)

Arguments

Return Value integer

public function dm_db_insert_beats(db, beats, transaction, validate) result(rc)

Arguments

Return Value integer

public function dm_db_insert_log(db, log, validate) result(rc)

Arguments

Return Value integer

public function dm_db_insert_node(db, node, validate) result(rc)

Arguments

Return Value integer

public function dm_db_insert_observ(db, observ, db_stmt, validate) result(rc)

Arguments

Return Value integer

public function dm_db_insert_observs(db, observs, transaction, validate) result(rc)

Arguments

Return Value integer

public function dm_db_insert_sensor(db, sensor, validate) result(rc)

Arguments

Return Value integer

public function dm_db_insert_target(db, target, validate) result(rc)

Arguments

Return Value integer

public interface dm_db_select

public function dm_db_select_beat(db, beat, node_id) result(rc)

Arguments

Return Value integer

public function dm_db_select_log(db, log, log_id) result(rc)

Arguments

Return Value integer

public function dm_db_select_node(db, node, node_id) result(rc)

Arguments

Return Value integer

public function dm_db_select_observ(db, observ, observ_id) result(rc)

Arguments

Return Value integer

public function dm_db_select_sensor(db, sensor, sensor_id) result(rc)

Arguments

Return Value integer

public function dm_db_select_target(db, target, target_id) result(rc)

Arguments

Return Value integer

public interface dm_db_select_beats

private function db_select_beats_array(db, beats, limit, nbeats) result(rc)

Arguments

Return Value integer

private function db_select_beats_iter(db, db_stmt, beat, limit) result(rc)

Arguments

Return Value integer

public interface dm_db_select_data_points

private function db_select_data_points_array(db, dps, node_id, sensor_id, target_id, response_name, from, to, error, limit, npoints) result(rc)

Arguments

Return Value integer

private function db_select_data_points_iter(db, db_stmt, dp, node_id, sensor_id, target_id, response_name, from, to, error, limit) result(rc)

Arguments

Return Value integer

public interface dm_db_select_json_beats

private function db_select_json_beats_array(db, strings, limit, nbeats) result(rc)

Arguments

Return Value integer

private function db_select_json_beats_iter(db, db_stmt, json, limit) result(rc)

Arguments