db.h File Reference


Detailed Description

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

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

Go to the source code of this file.

Typedefs

typedef struct _dba_dbdba_db
 DB-ALLe connection.

Functions

dba_err dba_db_create (const char *dsn, const char *user, const char *password, dba_db *db)
 Start a session with DBALLE.
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_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).


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:
db The dballe session id
query The record with the query data (see Keywords used by dba_record)
Return values:
cur The 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:
count The 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:
db The dballe database
rep_cod The report code to verify
Return values:
valid Set 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 
)

Start a session with DBALLE.

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

References DBA_RUN_OR_GOTO.

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:
db The 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:
db The 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:
db The dballe session id.
rec The record to insert.
can_replace If true, then existing data can be rewritten, else data can only be added.
pseudoana_can_add If 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_id ID of the pseudoana record for the entry just inserted. NULL can be used if the caller is not interested in this value.
context_id ID 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.

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:
db The dballe session id
id_context The database id of the context related to the attributes to insert
id_var The varcode of the variable related to the attributes to add. See vartable.h
attrs The 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:
db The dballe session id
id_context The database id of the context related to the attributes to insert
id_var The varcode of the variable related to the attributes to add. See vartable.h
attrs The 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:
db The dballe session id
id_context The database id of the context related to the attributes to insert
id_var The varcode of the variable related to the attributes to add. See vartable.h
attrs The record with the attributes to be added
can_replace If 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_attr::id_context, 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:
db The dballe session id
id_context The database id of the context related to the attributes to retrieve
id_var The varcode of the variable related to the attributes to retrieve. See vartable.h
qcs The WMO codes of the QC values requested. If it is NULL, then all values are returned.
qcs_size Number of elements in qcs
attrs The dba_record that will hold the resulting attributes
Return values:
count Number 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, 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:
db The dballe session id
id_context The database id of the context related to the attributes to remove
id_var The varcode of the variable related to the attributes to remove. See vartable.h
qcs Array of WMO codes of the QC data to delete. If NULL, all QC data associated to id_data will be deleted.
qcs_size Number 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, and DBA_VAR_Y.

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:
db The dballe session id
rec The record with the query data (see technical specifications, par. 1.6.4 "parameter output/input")
Return values:
cur The 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.
count The 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:
db The dballe session id
rec The 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:
db Database 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:
db The dballe session id
repinfo_file The 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:
db The dballe session id
repinfo_file The 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:
added The number of repinfo entryes that have been added
deleted The number of repinfo entryes that have been deleted
updated The 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.


Generated on Sun May 18 19:18:02 2008 for libdballe by  doxygen 1.5.5