cursor.h File Reference

Detailed Description

Functions used to manage a general DB-ALLe query.

#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_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.

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.

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().

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
	)

Fill in a record with the contents of a dba_db_cursor.

Parameters:

	cur	The cursor to use to iterate the results
	rec	The record where to store the values

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.


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_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.
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.