Functions

db.h File Reference

Functions used to connect to Dballe and insert, query and delete data. More...

#include <dballe/core/record.h>
#include <dballe/core/var.h>
#include <dballe/db/cursor.h>

Go to the source code of this file.

Functions

dba_err dba_db_create (const char *dsn, const char *user, const char *password, dba_db *db)
 DB-ALLe connection.
dba_err dba_db_create_generic (const char *config, dba_db *db)
 Start a session with DB-All.e.
dba_err dba_db_create_from_file (const char *pathname, dba_db *db)
 Create from a SQLite file pathname.
dba_err dba_db_create_from_url (const char *url, dba_db *db)
 Create from an url-like specification, that can be:
int dba_db_is_url (const char *str)
 Return TRUE if the string looks like a DB URL.
dba_err dba_db_create_test (dba_db *db)
 Start a session with DB-All.e.
void dba_db_delete (dba_db db)
 End a session with DBALLE.
dba_err dba_db_reset (dba_db db, const char *repinfo_file)
 Reset the database, removing all existing DBALLE tables and re-creating them empty.
dba_err dba_db_delete_tables (dba_db db)
 Delete all the DB-ALLe tables from the database.
dba_err dba_db_update_repinfo (dba_db db, const char *repinfo_file, int *added, int *deleted, int *updated)
 Update the repinfo table in the database, with the data found in the given file.
dba_err dba_db_rep_cod_from_memo (dba_db db, const char *memo, int *rep_cod)
 Get the report code from a report mnemonic.
dba_err dba_db_rep_memo_from_cod (dba_db db, int rep_cod, const char **memo)
 Get the report mnemonic from a report code.
dba_err dba_db_check_rep_cod (dba_db db, int rep_cod, int *valid)
 Verify that a rep_cod is supported by the database.
dba_err dba_db_ana_query (dba_db db, dba_record query, dba_db_cursor *cur, int *count)
 Start a query on the anagraphic archive.
dba_err dba_db_insert (dba_db db, dba_record rec, int can_replace, int pseudoana_can_add, int *ana_id, int *context_id)
 Insert a record into the database.
dba_err dba_db_query (dba_db db, dba_record rec, dba_db_cursor *cur, int *count)
 Query the database.
dba_err dba_db_remove (dba_db db, dba_record rec)
 Remove data from the database.
dba_err dba_db_remove_orphans (dba_db db)
 Remove orphan values from the database.
dba_err dba_db_qc_query (dba_db db, int id_context, dba_varcode id_var, const dba_varcode *qcs, size_t qcs_size, dba_record attrs, int *count)
 Query QC data.
dba_err dba_db_qc_insert_or_replace (dba_db db, int id_context, dba_varcode id_var, dba_record attrs, int can_replace)
 Insert a new QC value into the database.
dba_err dba_db_qc_insert (dba_db db, int id_context, dba_varcode id_var, dba_record attrs)
 Insert a new QC value into the database.
dba_err dba_db_qc_insert_new (dba_db db, int id_context, dba_varcode id_var, dba_record attrs)
 Insert a new QC value into the database.
dba_err dba_db_qc_remove (dba_db db, int id_context, dba_varcode id_var, dba_varcode *qcs, int qcs_size)
 Delete QC data for the variable `var' in record `rec' (coming from a previous dba_query)

Detailed Description

Functions used to connect to Dballe and insert, query and delete data.


Function Documentation

dba_err dba_db_ana_query ( dba_db  db,
dba_record  query,
dba_db_cursor cur,
int *  count 
)

Start a query on the anagraphic archive.

Parameters:
dbThe dballe session id
queryThe record with the query data (see Keywords used by dba_record)
Return values:
curThe dba_db_cursor variable that will hold the resulting dba_db_cursor that can be used to get the result values (See dba_db_cursor_next). dba_db_ana_query() will create the cursor, and it is up to the caller to delete it using dba_db_cursor_delete().
Parameters:
countThe count of items in the anagraphic archive, returned by the function
Returns:
The error indicator for the function (See error.h)

References DBA_DB_MODIFIER_ANAEXTRA, DBA_DB_MODIFIER_DISTINCT, DBA_DB_WANT_ANA_ID, DBA_DB_WANT_COORDS, DBA_DB_WANT_IDENT, DBA_RUN_OR_GOTO, and DBA_RUN_OR_RETURN.

dba_err dba_db_check_rep_cod ( dba_db  db,
int  rep_cod,
int *  valid 
)

Verify that a rep_cod is supported by the database.

Parameters:
dbThe dballe database
rep_codThe report code to verify
Return values:
validSet to 1 if the report code is supported, 0 if not
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_RETURN, and _dba_db::repinfo.

dba_err dba_db_create ( const char *  dsn,
const char *  user,
const char *  password,
dba_db db 
)

DB-ALLe connection.

Start a session with DB-All.e

Parameters:
dsnThe ODBC DSN of the database to use
userThe user name to use to connect to the DSN
passwordThe password to use to connect to the DSN. To specify an empty password, pass "" or NULL
Return values:
dbThe dba_db handle returned by the function
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO.

dba_err dba_db_create_from_file ( const char *  pathname,
dba_db db 
)

Create from a SQLite file pathname.

Parameters:
pathnameThe pathname to a SQLite file
Return values:
dbThe dba_db handle returned by the function
Returns:
The error indicator for the function (See error.h)
dba_err dba_db_create_from_url ( const char *  url,
dba_db db 
)

Create from an url-like specification, that can be:

sqlite:[//]foo.sqlite odbc://[user[:pass]@]dsn test:[//]

Parameters:
urlThe url-like connection descriptor
Return values:
dbThe dba_db handle returned by the function
Returns:
The error indicator for the function (See error.h)

References dba_error_consistency.

dba_err dba_db_create_generic ( const char *  config,
dba_db db 
)

Start a session with DB-All.e.

Parameters:
configThe string with the configuration to use to start the connection. This is passed as is to SQLDriverConnect, so see ODBC documentation for its format.
Return values:
dbThe dba_db handle returned by the function
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO.

dba_err dba_db_create_test ( dba_db db )

Start a session with DB-All.e.

Take information from the environment (

See also:
dba_db_create_from_env) and default to ./test.sqlite if nothing is specified.
Return values:
dbThe dba_db handle returned by the function
Returns:
The error indicator for the function (See error.h)
void dba_db_delete ( dba_db  db )

End a session with DBALLE.

All the resources associated with db will be freed. db should not be used anymore, unless it is recreated with dba_open

Parameters:
dbThe dballe session id

References _dba_db::attr, _dba_db::connected, _dba_db::context, _dba_db::data, _dba_db::od_conn, _dba_db::pseudoana, _dba_db::repinfo, _dba_db::seq_context, _dba_db::seq_pseudoana, and _dba_db::stm_last_insert_id.

dba_err dba_db_delete_tables ( dba_db  db )

Delete all the DB-ALLe tables from the database.

Parameters:
dbThe dballe session id
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, and _dba_db::server_type.

dba_err dba_db_insert ( dba_db  db,
dba_record  rec,
int  can_replace,
int  pseudoana_can_add,
int *  ana_id,
int *  context_id 
)

Insert a record into the database.

In a record with the same phisical situation already exists, the function fails.

Parameters:
dbThe dballe session id.
recThe record to insert.
can_replaceIf true, then existing data can be rewritten, else data can only be added.
pseudoana_can_addIf true, then it is allowed to add new pseudoana records to the database. Otherwise, data can be added only by reusing existing ones.
Return values:
ana_idID of the pseudoana record for the entry just inserted. NULL can be used if the caller is not interested in this value.
context_idID of the context record for the entry just inserted. NULL can be used if the caller is not interested in this value.
Returns:
The error indicator for the function (See error.h).

References _dba_db::data, dba_error_consistency, DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, and _dba_db_data::id_context.

int dba_db_is_url ( const char *  str )

Return TRUE if the string looks like a DB URL.

Parameters:
strThe string to test
Returns:
1 if it looks like a URL, else 0
dba_err dba_db_qc_insert ( dba_db  db,
int  id_context,
dba_varcode  id_var,
dba_record  attrs 
)

Insert a new QC value into the database.

If the same QC value exists for the same data, it is overwritten

Parameters:
dbThe dballe session id
id_contextThe database id of the context related to the attributes to insert
id_varThe varcode of the variable related to the attributes to add. See vartable.h
attrsThe record with the attributes to be added
Returns:
The error indicator for the function (See error.h)
dba_err dba_db_qc_insert_new ( dba_db  db,
int  id_context,
dba_varcode  id_var,
dba_record  attrs 
)

Insert a new QC value into the database.

If the same QC value exists for the same data, the function fails.

Parameters:
dbThe dballe session id
id_contextThe database id of the context related to the attributes to insert
id_varThe varcode of the variable related to the attributes to add. See vartable.h
attrsThe record with the attributes to be added
Returns:
The error indicator for the function (See error.h)
dba_err dba_db_qc_insert_or_replace ( dba_db  db,
int  id_context,
dba_varcode  id_var,
dba_record  attrs,
int  can_replace 
)

Insert a new QC value into the database.

Parameters:
dbThe dballe session id
id_contextThe database id of the context related to the attributes to insert
id_varThe varcode of the variable related to the attributes to add. See vartable.h
attrsThe record with the attributes to be added
can_replaceIf true, then existing data can be rewritten, else data can only be added.
Returns:
The error indicator for the function (See error.h)

References _dba_db::attr, DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, _dba_db_data::id_context, _dba_db_attr::id_context, _dba_db_data::id_var, and _dba_db_attr::id_var.

dba_err dba_db_qc_query ( dba_db  db,
int  id_context,
dba_varcode  id_var,
const dba_varcode qcs,
size_t  qcs_size,
dba_record  attrs,
int *  count 
)

Query QC data.

Parameters:
dbThe dballe session id
id_contextThe database id of the context related to the attributes to retrieve
id_varThe varcode of the variable related to the attributes to retrieve. See vartable.h
qcsThe WMO codes of the QC values requested. If it is NULL, then all values are returned.
qcs_sizeNumber of elements in qcs
attrsThe dba_record that will hold the resulting attributes
Return values:
countNumber of QC items returned in qc
Returns:
The error indicator for the function (See error.h)

References dba_error_consistency, DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, _dba_db_data::id_context, and TRACE.

dba_err dba_db_qc_remove ( dba_db  db,
int  id_context,
dba_varcode  id_var,
dba_varcode qcs,
int  qcs_size 
)

Delete QC data for the variable `var' in record `rec' (coming from a previous dba_query)

Parameters:
dbThe dballe session id
id_contextThe database id of the context related to the attributes to remove
id_varThe varcode of the variable related to the attributes to remove. See vartable.h
qcsArray of WMO codes of the QC data to delete. If NULL, all QC data associated to id_data will be deleted.
qcs_sizeNumber of items in the qcs array.
Returns:
The error indicator for the function (See error.h)

References dba_error_consistency, DBA_RUN_OR_RETURN, DBA_VAR_X, DBA_VAR_Y, and _dba_db_data::id_context.

dba_err dba_db_query ( dba_db  db,
dba_record  rec,
dba_db_cursor cur,
int *  count 
)

Query the database.

When multiple values per variable are present, the results will be presented in increasing order of priority.

Parameters:
dbThe dballe session id
recThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input")
Return values:
curThe dba_db_cursor variable that will hold the resulting dba_db_cursor that can be used to get the result values (See dba_db_cursor_next) dba_db_query will create the cursor, and it is up to the caller to delete it using dba_db_cursor_delete.
countThe number of values returned by the query
Returns:
The error indicator for the function (See error.h)

References DBA_DB_WANT_ANA_ID, DBA_DB_WANT_CONTEXT_ID, DBA_DB_WANT_COORDS, DBA_DB_WANT_DATETIME, DBA_DB_WANT_IDENT, DBA_DB_WANT_LEVEL, DBA_DB_WANT_REPCOD, DBA_DB_WANT_TIMERANGE, DBA_DB_WANT_VAR_NAME, DBA_DB_WANT_VAR_VALUE, DBA_RUN_OR_GOTO, and DBA_RUN_OR_RETURN.

dba_err dba_db_remove ( dba_db  db,
dba_record  rec 
)

Remove data from the database.

Parameters:
dbThe dballe session id
recThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input") to select the items to be deleted
Returns:
The error indicator for the function (See error.h)

References DBA_DB_MODIFIER_STREAM, DBA_DB_MODIFIER_UNSORTED, DBA_DB_WANT_CONTEXT_ID, DBA_DB_WANT_VAR_NAME, DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, DBA_VAR_X, DBA_VAR_Y, _dba_db_cursor::out_context_id, and _dba_db_cursor::out_idvar.

dba_err dba_db_remove_orphans ( dba_db  db )

Remove orphan values from the database.

Orphan values are currently:

  • context values for which no data exists
  • pseudoana values for which no context exists

Depending on database size, this routine can take a few minutes to execute.

Parameters:
dbDatabase to operate on
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, and _dba_db::server_type.

dba_err dba_db_reset ( dba_db  db,
const char *  repinfo_file 
)

Reset the database, removing all existing DBALLE tables and re-creating them empty.

Parameters:
dbThe dballe session id
repinfo_fileThe name of the CSV file with the report type information data to load. The file is in CSV format with 6 columns: report code, mnemonic id, description, priority, descriptor, table A category. If repinfo_file is NULL, then the default of /etc/dballe/repinfo.csv is used.
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, _dba_db::repinfo, and _dba_db::server_type.

dba_err dba_db_update_repinfo ( dba_db  db,
const char *  repinfo_file,
int *  added,
int *  deleted,
int *  updated 
)

Update the repinfo table in the database, with the data found in the given file.

Parameters:
dbThe dballe session id
repinfo_fileThe name of the CSV file with the report type information data to load. The file is in CSV format with 6 columns: report code, mnemonic id, description, priority, descriptor, table A category. If repinfo_file is NULL, then the default of /etc/dballe/repinfo.csv is used.
Return values:
addedThe number of repinfo entryes that have been added
deletedThe number of repinfo entryes that have been deleted
updatedThe number of repinfo entryes that have been updated
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_RETURN, and _dba_db::repinfo.