dm_db_api – DMPACK

Database API module for CRUD operations, based on the core module dm_db. 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)
call 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')
call dm_error_out(rc, fatal=.true.)

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

call dm_db_finalize(db_stmt)
call dm_db_close(db)

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

Uses

- dm_db_table
- dm_db
- dm_db_row
- dm_sql
- dm_id
- dm_uuid
- dm_time
- dm_db_query
- dm_error
- sqlite3
- iso_c_binding
- dm_kind
- dm_util
- dm_db_pragma
- dm_db_count
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_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_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_JOURNAL_WAL2	=	6	Use Write-Ahead Log 2 (WAL2) journal.
integer,	public,	parameter	::	DB_JOURNAL_LAST	=	6	Never use this.
integer,	public,	parameter	::	DB_LOCKING_MODE_NORMAL	=	0	Normal locking mode.
integer,	public,	parameter	::	DB_LOCKING_MODE_EXCLUSIVE	=	1	Exclusive locking mode.
integer,	public,	parameter	::	DB_SYNCHRONOUS_OFF	=	0	SQLite continues without syncing as soon as it has handed data off to the operating system.
integer,	public,	parameter	::	DB_SYNCHRONOUS_NORMAL	=	1	SQLite will still sync at the most critical moments, but less often than in FULL mode.
integer,	public,	parameter	::	DB_SYNCHRONOUS_FULL	=	2	Default mode, SQLite will use the xSync method of the VFS to ensure that all content is safely written to the disk surface prior to continuing.
integer,	public,	parameter	::	DB_SYNCHRONOUS_EXTRA	=	3	Like FULL with the addition that the directory containing a rollback journal is synced after that journal is unlinked to commit a transaction in DELETE mode.
integer,	public,	parameter	::	DB_TEMP_STORE_DEFAULT	=	0	Default temp store.
integer,	public,	parameter	::	DB_TEMP_STORE_FILE	=	1	File temp store.
integer,	public,	parameter	::	DB_TEMP_STORE_MEMORY	=	2	Memory temp store.
integer,	public,	parameter	::	DB_APPLICATION_ID	=	int(z'444D31')	Application id of DMPACK databases (`DM1` in ASCII).
integer,	public,	parameter	::	DB_SCHEMA_VERSION	=	3	Database schema version, increased on updates.
integer,	public,	parameter	::	DB_TIMEOUT_DEFAULT	=	1000	Default SQLite 3 busy timeout [msec].

Interfaces

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_image(db, image, validate) result(rc)

Adds given image to database. The image 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 image 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(image_type),	intent(inout)		::	image	Image to insert.
logical,	intent(in),	optional	::	validate	Validate image.

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 function dm_db_insert_transfer(db, transfer, validate) result(rc)

Adds given transfer to database. The transfer 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 transfer 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(transfer_type),	intent(inout)		::	transfer	Transfer to insert.
logical,	intent(in),	optional	::	validate	Validate transfer.

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_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if id is invalid.

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_image(db, image, image_id) result(rc)

Returns image data associated with given image id from images table.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if image id or type id is not passed or invalid.

Arguments

Type	Intent		Name
type(db_type),	intent(inout)	::	db	Database type.
type(image_type),	intent(out)	::	image	Returned image data.
character(len=*),	intent(in)	::	image_id	Image 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_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if id is invalid.

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_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if id is invalid.

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_DONE if statement finished.
E_DB_FINALIZE if statement finalisation failed.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if id is invalid.

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_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if id is invalid.

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_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if id is invalid.

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 function dm_db_select_transfer(db, transfer, transfer_id, type_id) result(rc)

Returns transfer data associated with given transfer id and/or type_id from transfer database.

The function returns the following error codes:

E_DB_BIND if value binding failed.
E_DB_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if transfer id or type id is not passed or invalid.

Arguments

Type	Intent	Optional		Name
type(db_type),	intent(inout)		::	db	Database type.
type(transfer_type),	intent(out)		::	transfer	Returned transfer data.
character(len=*),	intent(in),	optional	::	transfer_id	Transfer id.
character(len=*),	intent(in),	optional	::	type_id	Transfer type 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, validate) 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_DONE if statement finished.
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.
logical,	intent(in),	optional	::	validate	Validate column types.

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, ndps) 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_STEP if step execution 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		::	ndps	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, validate) 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_DONE if statement finished.
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.
logical,	intent(in),	optional	::	validate	Validate column types.

Return Value integer

public interface dm_db_select_images

Generic images select function.

private function db_select_images_array(db, images, node_id, sensor_id, target_id, from, to, desc, limit, nimages) result(rc)

Returns images in allocatable array images.

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(image_type),	intent(out),		allocatable	::	images(:)	Returned image 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		::	from	Begin of time range.
character(len=*),	intent(in),	optional		::	to	End of time range.
logical,	intent(in),	optional		::	desc	Descending order.
integer(kind=i8),	intent(in),	optional		::	limit	Max. numbers of images.
integer(kind=i8),	intent(out),	optional		::	nimages	Total number of images.

Return Value integer

private function db_select_images_iter(db, db_stmt, image, node_id, sensor_id, target_id, from, to, desc, limit, validate) result(rc)

Iterator function that returns images in images. 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_DONE if statement finished.
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(image_type),	intent(out)		::	image	Returned image 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	Begin of time range.
character(len=*),	intent(in),	optional	::	to	End of time range.
logical,	intent(in),	optional	::	desc	Descending order.
integer(kind=i8),	intent(in),	optional	::	limit	Max. numbers of images.
logical,	intent(in),	optional	::	validate	Validate column types.

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, observ_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		::	observ_id	Observation 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, observ_id, source, from, to, min_level, max_level, error, desc, limit, validate) 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_DONE if statement finished.
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	::	observ_id	Observation 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.
logical,	intent(in),	optional	::	validate	Validate column types.

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, validate) 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_DONE if statement finished.
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(node_type),	intent(out)		::	node	Returned node data.
logical,	intent(in),	optional	::	validate	Validate column types.

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.

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, validate) 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_DONE if statement finished.
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.
logical,	intent(in),	optional	::	validate	Validate column types.

Return Value integer

public interface dm_db_select_sensors

Generic sensors select function.

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

Returns all sensors in allocatable array sensors. If argument node_id is passed, returns only sensors of this node.

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.
E_INVALID if node id is empty.

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.
character(len=*),	intent(in),	optional		::	node_id	Node id.
integer(kind=i8),	intent(out),	optional		::	nsensors	Number of returned sensors.

Return Value integer

private function db_select_sensors_iter(db, db_stmt, sensor, node_id, validate) 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_DONE if statement finished.
E_DB_PREPARE if statement preparation failed.
E_DB_TYPE if returned columns are unexpected.
E_INVALID if node id is empty.

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(sensor_type),	intent(out)		::	sensor	Returned sensor data.
character(len=*),	intent(in),	optional	::	node_id	Node id.
logical,	intent(in),	optional	::	validate	Validate column types.

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, validate) 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_DONE if statement finished.
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(target_type),	intent(out)		::	target	Target data.
logical,	intent(in),	optional	::	validate	Validate column types.

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

Functions

public function dm_db_backup(db, path, wal, callback, nsteps, sleep_time) result(rc)

Creates online backup of given database. The functions assumes 500 steps and a sleep time of 250 msec by default, if the arguments are not passed.

dm_db_api Module

Contents

Variables

Interfaces

Functions

Subroutines

Uses

Used by

Variables

Interfaces

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_image(db, image, 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 function dm_db_insert_transfer(db, transfer, 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_image(db, image, image_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 function dm_db_select_transfer(db, transfer, transfer_id, type_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, validate) 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, ndps) 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, validate) result(rc)

Arguments

Return Value integer