cursor.h File Reference

Functions used to manage a general DB-ALLe query. More...

#include <dballe/core/record.h>
#include <dballe/db/querybuf.h>

Go to the source code of this file.

Defines

#define DBA_DB_WANT_COORDS   (1 << 0)
 Constants used to define what values we should retrieve from a query.
#define DBA_DB_WANT_IDENT   (1 << 1)
 Retrieve the mobile station identifier.
#define DBA_DB_WANT_LEVEL   (1 << 2)
 Retrieve the level information.
#define DBA_DB_WANT_TIMERANGE   (1 << 3)
 Retrieve the time range information.
#define DBA_DB_WANT_DATETIME   (1 << 4)
 Retrieve the date and time information.
#define DBA_DB_WANT_VAR_NAME   (1 << 5)
 Retrieve the variable name.
#define DBA_DB_WANT_VAR_VALUE   (1 << 6)
 Retrieve the variable value.
#define DBA_DB_WANT_REPCOD   (1 << 7)
 Retrieve the report code.
#define DBA_DB_WANT_ANA_ID   (1 << 8)
 Retrieve the station ID.
#define DBA_DB_WANT_CONTEXT_ID   (1 << 9)
 Retrieve the context ID.
#define DBA_DB_FROM_PA   (1 << 0)
 Constants used to define what is needed from the FROM part of the query.
#define DBA_DB_FROM_C   (1 << 1)
 Add context to the FROM part of the query.
#define DBA_DB_FROM_D   (1 << 2)
 Add data to the FROM part of the query.
#define DBA_DB_FROM_RI   (1 << 3)
 Add repinfo to the FROM part of the query.
#define DBA_DB_FROM_CBS   (1 << 4)
 Add the pseudoana context as 'cbs' to the FROM part of the query.
#define DBA_DB_FROM_DBLO   (1 << 5)
 Add the the block variables as 'dblo' to the FROM part of the query.
#define DBA_DB_FROM_DSTA   (1 << 6)
 Add the the station variables as 'dsta' to the FROM part of the query.
#define DBA_DB_FROM_DANA   (1 << 7)
 Add the the pseudoana variables as 'dana' to the FROM part of the query.
#define DBA_DB_FROM_DDF   (1 << 8)
 Add an extra data table as 'ddf' to the FROM part of the query, to restrict the query on variable values.
#define DBA_DB_FROM_ADF   (1 << 9)
 Add an extra attr table as 'adf' to the FROM part of the query, to restrict the query on variable attributes.
#define DBA_DB_MODIFIER_BEST   (1 << 0)
 Values for query modifier flags.
#define DBA_DB_MODIFIER_BIGANA   (1 << 1)
 Tell the database optimizer that this is a query on a database with a big pseudoana table (this serves to hint the MySQL optimizer, which would not otherwise apply the correct strategy.
#define DBA_DB_MODIFIER_DISTINCT   (1 << 2)
 Remove duplicates in the results.
#define DBA_DB_MODIFIER_ANAEXTRA   (1 << 3)
 Include the extra anagraphical data in the results.
#define DBA_DB_MODIFIER_NOANAEXTRA   (1 << 4)
 Do not include the extra anagraphical data in the results.
#define DBA_DB_MODIFIER_UNSORTED   (1 << 5)
 Do not bother sorting the results.
#define DBA_DB_MODIFIER_STREAM   (1 << 6)
 Start geting the results as soon as they are available, without waiting for the database to finish building the result set.

Typedefs

typedef struct _dba_dbdba_db
typedef struct _dba_db_cursordba_db_cursor

Functions

dba_err dba_db_cursor_create (dba_db db, dba_db_cursor *cur)
 Create a new dba_cursor.
void dba_db_cursor_delete (dba_db_cursor cur)
 Delete a dba_db_cursor.
dba_err dba_db_cursor_query (dba_db_cursor cur, dba_record query, unsigned int wanted, unsigned int modifiers)
 Create and execute a database query.
int dba_db_cursor_remaining (dba_db_cursor cur)
 Get the number of rows still to be fetched.
dba_err dba_db_cursor_next (dba_db_cursor cur, int *has_data)
 Get a new item from the results of a query.
dba_err dba_db_cursor_to_record (dba_db_cursor cur, dba_record rec)
 Fill in a record with the contents of a dba_db_cursor.


Detailed Description

Functions used to manage a general DB-ALLe query.


Define Documentation

#define DBA_DB_FROM_PA   (1 << 0)

Constants used to define what is needed from the FROM part of the query.

Add pseudoana to the FROM part of the query

#define DBA_DB_MODIFIER_BEST   (1 << 0)

Values for query modifier flags.

When values from different reports exist on the same point, only report the one from the report with the highest priority

Referenced by dba_db_cursor_query().

#define DBA_DB_MODIFIER_STREAM   (1 << 6)

Start geting the results as soon as they are available, without waiting for the database to finish building the result set.

As a side effect, it is impossible to know in advance the number of results. Currently, it does not work with the MySQL ODBC driver

Referenced by dba_db_cursor_query(), and dba_db_remove().

#define DBA_DB_WANT_COORDS   (1 << 0)

Constants used to define what values we should retrieve from a query.

Retrieve latitude and longitude

Referenced by dba_db_ana_query(), dba_db_cursor_to_record(), dba_db_export(), and dba_db_query().


Typedef Documentation

typedef struct _dba_db* dba_db

DB-ALLe session structure.

typedef struct _dba_db_cursor* dba_db_cursor

Structure used to build and execute a query, and to iterate through the results.


Function Documentation

dba_err dba_db_cursor_create ( dba_db  db,
dba_db_cursor cur 
)

Create a new dba_cursor.

Parameters:
db Database that will be queried
Return values:
cur The newly created cursor.
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO.

void dba_db_cursor_delete ( dba_db_cursor  cur  ) 

Delete a dba_db_cursor.

Parameters:
cur The cursor to delete

References _dba_db_cursor::db, _dba_db::od_conn, _dba_db_cursor::query, _dba_db_cursor::stm, and _dba_db_cursor::where.

dba_err dba_db_cursor_next ( dba_db_cursor  cur,
int *  has_data 
)

Get a new item from the results of a query.

Parameters:
cur The cursor to use to iterate the results
Return values:
has_data True if a new record has been read, false if there is no more data to read
Returns:
The error indicator for the function. The error code DBA_ERR_NOTFOUND is used when there are no more results to get.
Note:
Do not forget to call dba_db_cursor_delete after you have finished retrieving the query data.

References _dba_db_cursor::count, and _dba_db_cursor::stm.

dba_err dba_db_cursor_query ( dba_db_cursor  cur,
dba_record  query,
unsigned int  wanted,
unsigned int  modifiers 
)

Create and execute a database query.

The results are retrieved by iterating the cursor.

Parameters:
cur The dballe cursor to use for the query
query The record with the query data (see technical specifications, par. 1.6.4 "parameter output/input"
wanted The values wanted in output
modifiers Optional modifiers to ask for special query behaviours
Returns:
The error indicator for the function (See error.h)

References _dba_db_cursor::accept_from_ana_context, _dba_db_cursor::count, _dba_db_cursor::db, DBA_DB_MODIFIER_BEST, DBA_DB_MODIFIER_BIGANA, DBA_DB_MODIFIER_DISTINCT, DBA_DB_MODIFIER_STREAM, DBA_DB_MODIFIER_UNSORTED, DBA_DB_WANT_ANA_ID, DBA_DB_WANT_DATETIME, DBA_DB_WANT_IDENT, DBA_DB_WANT_LEVEL, DBA_DB_WANT_TIMERANGE, dba_error_unimplemented, DBA_RUN_OR_RETURN, _dba_db_cursor::from_wanted, _dba_db_cursor::input_seq, _dba_db_cursor::modifiers, _dba_db_cursor::output_seq, _dba_db_cursor::query, _dba_db_cursor::select_wanted, _dba_db::server_type, _dba_db_cursor::stm, TRACE, _dba_db_cursor::wanted, and _dba_db_cursor::where.

int dba_db_cursor_remaining ( dba_db_cursor  cur  ) 

Get the number of rows still to be fetched.

Parameters:
cur The dballe cursor to query.
Returns:
The number of rows still to be queried. The value is undefined if no query has been successfully peformed yet using this cursor.

References _dba_db_cursor::count.

dba_err dba_db_cursor_to_record ( dba_db_cursor  cur,
dba_record  rec 
)


Generated on Wed Mar 11 10:00:44 2009 for libdballe by  doxygen 1.5.8