binding.cc File Reference

Simplified interface for Dballe. More...

#include "dbapi.h"
#include <dballe/core/record.h>
#include <dballe/core/error.h>
#include <dballe/db/db.h>
#include <dballe/db/cursor.h>
#include "commonapi.h"
#include <dballe/core/file.h>
#include <dballe/msg/msgs.h>
#include <dballe/core/verbose.h>
#include <dballe/core/aliases.h>
#include <dballe/db/internals.h>
#include <dballe/msg/formatter.h>
#include <dballe/init.h>
#include <f77.h>
#include <float.h>
#include <limits.h>
#include <stdio.h>
#include <string.h>
#include "simple.h"
#include <assert.h>

Defines

#define TRACEMISSING(type)   do {} while(0)
#define MISSING_BYTE   SCHAR_MAX
#define MISSING_INT   INT_MAX
#define MISSING_REAL   FLT_MAX
#define MISSING_DOUBLE   DBL_MAX
#define MAX_SIMPLE   50
#define MAX_SESSION   10
#define STATE   (FDBA_HANDLE(simple, *handle))
#define SESSION   (FDBA_HANDLE(session, FDBA_HANDLE(simple, *handle).session).session)

Functions

integer idba_presentati (integer dbahandle, character dsn, character user, character password)
 Start working with a DBALLE database.
subroutine idba_arrivederci (integer dbahandle)
 Stop working with a DBALLE database.
integer idba_preparati (integer dbahandle, integer handle, character anaflag, character dataflag, character attrflag)
 Starts a session with dballe.
integer idba_messaggi (integer handle, character filename, character mode, character type)
 Access a file with wheter messages.
integer idba_fatto (integer handle)
 Ends a session with DBALLE.
integer idba_scopa (integer handle, character repinfofile)
 Reset the database contents, loading default report informations from a file.
integer idba_unset (integer handle, character parameter)
 Remove one parameter from the input record.
subroutine idba_unsetall (integer handle)
 Remove all parameters from the input record.
integer idba_quantesono (integer handle, integer count)
 Count the number of elements in the anagraphical storage, and start a new anagraphical query.
integer idba_elencamele (integer handle)
 Iterate through the anagraphical data.
integer idba_voglioquesto (integer handle, integer count)
 Submit a query to the database.
integer idba_dammelo (integer handle, character parameter)
 Iterate through the query results data.
integer idba_prendilo (integer handle)
 Insert a new item in the database.
integer idba_dimenticami (integer handle)
 Remove all selected items from the database.
idba_enq*

Functions used to read the output values of the DBALLE action routines

integer idba_enqi (integer handle, character parameter, integer value)
 Read one integer value from the output record.
integer idba_enqb (integer handle, character parameter,)
 Read one byte value from the output record.
integer idba_enqr (integer handle, character parameter, real value)
 Read one real value from the output record.
integer idba_enqd (integer handle, character parameter, double value)
 Read one real*8 value from the output record.
integer idba_enqc (integer handle, character parameter, character value)
 Read one character value from the output record.
idba_set*

Functions used to read the input values for the DBALLE action routines

integer idba_seti (integer handle, character parameter, integer value)
 Set one integer value into the input record.
integer idba_setb (integer handle, character parameter,)
 Set one byte value into the input record.
integer idba_setr (integer handle, character parameter, real value)
 Set one real value into the input record.
integer idba_setd (integer handle, character parameter, double value)
 Set one real*8 value into the input record.
integer idba_setc (integer handle, character parameter, character value)
 Set one character value into the input record.
integer idba_setcontextana (integer handle)
 Shortcut function to set query parameters to the anagraphical context.
integer idba_enqlevel (integer handle, integer ltype1, integer l1, integer ltype2, integer l2)
 Shortcut function to read level data.
integer idba_setlevel (integer handle, integer ltype1, integer l1, integer ltype2, integer l2)
 Shortcut function to set level data.
integer idba_enqtimerange (integer handle, integer ptype, integer p1, integer p2)
 Shortcut function to read time range data.
integer idba_settimerange (integer handle, integer ptype, integer p1, integer p2)
 Shortcut function to set time range data.
integer idba_enqdate (integer handle, integer year, integer month, integer day, integer hour, integer min, integer sec)
 Shortcut function to read date information.
integer idba_setdate (integer handle, integer year, integer month, integer day, integer hour, integer min, integer sec)
 Shortcut function to set date information.
integer idba_setdatemin (integer handle, integer year, integer month, integer day, integer hour, integer min, integer sec)
 Shortcut function to set minimum date for a query.
integer idba_setdatemax (integer handle, integer year, integer month, integer day, integer hour, integer min, integer sec)
 Shortcut function to set maximum date for a query.
QC functions

Functions used to manipulate QC data.

All these functions require some context data about the variable, which is automatically available when the variable just came as the result of an idba_dammelo() or has just been inserted with an idba_prendilo().

integer idba_voglioancora (integer handle, integer count)
 Retrieve QC informations from the last variable returned by idba_dammelo().
integer idba_ancora (integer handle, character parameter)
 Retrieve QC informations from the last variable returned by idba_dammelo().
integer idba_critica (integer handle)
 Insert new QC informations for a variable of the current record.
integer idba_scusa (integer handle)
 Remove QC informations for a variable of the current record.
integer idba_spiegal (integer handle, integer ltype1, integer l1, integer ltype2, integer l2, character result)
 Retrieve QC informations from the last variable returned by idba_dammelo().
integer idba_spiegat (integer handle, integer ptype, integer p1, integer p2, character result)
 Retrieve QC informations from the last variable returned by idba_dammelo().
integer idba_spiegab (integer handle, character varcode, character value, character result)
 Retrieve QC informations from the last variable returned by idba_dammelo().
integer idba_test_input_to_output (integer handle)
 Retrieve QC informations from the last variable returned by idba_dammelo().

Detailed Description

Simplified interface for Dballe.

Every function returns an error indicator, which is 0 if no error happened, or 1 if there has been an error.

When an error happens, the functions in fdba_error.c can be used to get detailed informations about it.

Internals of the simplified interface

Behind the handle returned by idba_preparati() there are a set of variables that are used as implicit parameters:

The simplified interface has two possible states: QUERY and RESULT. Then the interface is in the QUERY state, the idba_enq and idba_set functions operate in the query dba_record, to set and check the parameters of a query. idba_voglioquesto() reads the parameters from the query dba_record and switches the state to RESULT, and further calls to idba_dammelo() will put the query results in the work dba_record, to be read by the idba_enq functions.

In the RESULT state, the idba_enq and idba_set functions operate on the work dba_record, to inspect the results of the queries. A call to idba_ricominciamo() terminates the current query and goes back to the QUERY state, resetting the contents of all the dba_record of the interface.

idba_prendilo() inserts in the database the data coming from the QUERY dba_record if invoked in the query state, or the data coming from the RESULT dba_record if invoked in the result state. This is done because inserting new values in the database should be independent from the state.

qc functions instead always operate on the qc dba_record, which is accessed with the idba_enq and idba_set functions by prefixing the parameter name with an asterisk.

Function Documentation

integer idba_ancora ( integer  handle,
character  parameter 
)

Retrieve QC informations from the last variable returned by idba_dammelo().

Parameters:
handle Handle to a DBALLE session
Return values:
parameter Contains the ID of the parameter retrieved by this fetch
Returns:
The error indicator for the function
subroutine idba_arrivederci ( integer  dbahandle  ) 

Stop working with a DBALLE database.

Parameters:
dbahandle The database handle to close.
integer idba_critica ( integer  handle  ) 

Insert new QC informations for a variable of the current record.

QC informations inserted are all those set by the functions idba_seti(), idba_setc(), idba_setr(), idba_setd(), using an asterisk in front of the variable name.

Contrarily to idba_prendilo(), this function resets all the QC informations (but only the QC informations) previously set in input, so the values to be inserted need to be explicitly set every time.

This function will fail if the database is open in QC readonly mode, and it will refuse to overwrite existing values if the database is open in QC add mode.

The variable referred by the QC informations can be specified in three ways:

  • by variable code, using idba_setc(handle, "*var", "Bxxyyy")
  • by variable id, using idba_seti(handle, "*data_id", id)
  • unspecified, will use the last variable returned by idba_dammelo
Parameters:
handle Handle to a DBALLE session
Returns:
The error indicator for the function
integer idba_dammelo ( integer  handle,
character  parameter 
)

Iterate through the query results data.

Every invocation of this function will return a new result, or fill fail with code DBA_ERR_NOTFOUND when there are no more results available.

Parameters:
handle Handle to a DBALLE session
Return values:
parameter Contains the ID of the parameter retrieved by this fetch
Returns:
The error indicator for the function
integer idba_dimenticami ( integer  handle  ) 

Remove all selected items from the database.

This function will fail unless the database is open in data rewrite mode.

Parameters:
handle Handle to a DBALLE session
Returns:
The error indicator for the function
integer idba_elencamele ( integer  handle  ) 

Iterate through the anagraphical data.

Every invocation of this function will return a new anagraphical data, or fill fail with code DBA_ERR_NOTFOUND when there are no more anagraphical data available.

Parameters:
handle Handle to a DBALLE session
Returns:
The error indicator for the function
integer idba_enqb ( integer  handle,
character  parameter 
)

Read one byte value from the output record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value Where the value will be returned
Returns:
The error indicator for the function
integer idba_enqc ( integer  handle,
character  parameter,
character  value 
)

Read one character value from the output record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value Where the value will be returned
Returns:
The error indicator for the function
integer idba_enqd ( integer  handle,
character  parameter,
double  value 
)

Read one real*8 value from the output record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value Where the value will be returned
Returns:
The error indicator for the function
integer idba_enqdate ( integer  handle,
integer  year,
integer  month,
integer  day,
integer  hour,
integer  min,
integer  sec 
)

Shortcut function to read date information.

Parameters:
handle Handle to a DBALLE session
Return values:
year Year from the output record
month Month the output record
day Day the output record
hour Hour the output record
min Minute the output record
sec Second the output record
Returns:
The error indicator for the function
integer idba_enqi ( integer  handle,
character  parameter,
integer  value 
)

Read one integer value from the output record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value Where the value will be returned
Returns:
The error indicator for the function
integer idba_enqlevel ( integer  handle,
integer  ltype1,
integer  l1,
integer  ltype2,
integer  l2 
)

Shortcut function to read level data.

Parameters:
handle Handle to a DBALLE session
Return values:
ltype Level type from the output record
l1 L1 from the output record
l2 L2 from the output record
Returns:
The error indicator for the function
integer idba_enqr ( integer  handle,
character  parameter,
real  value 
)

Read one real value from the output record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to query. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value Where the value will be returned
Returns:
The error indicator for the function
integer idba_enqtimerange ( integer  handle,
integer  ptype,
integer  p1,
integer  p2 
)

Shortcut function to read time range data.

Parameters:
handle Handle to a DBALLE session
Return values:
ptype P indicator from the output record
p1 P1 from the output record
p2 P2 from the output record
Returns:
The error indicator for the function
integer idba_fatto ( integer  handle  ) 

Ends a session with DBALLE.

Parameters:
handle Handle to the session to be closed.
integer idba_messaggi ( integer  handle,
character  filename,
character  mode,
character  type 
)

Access a file with wheter messages.

Return values:
handle The session handle returned by the function
Parameters:
filename Name of the file to open
mode File open mode. It can be:

  • r for read
  • w for write (the old file is deleted)
  • a for append
type Format of the data in the file. It can be:

  • "BUFR"
  • "CREX"
  • "AOF" (read only)
  • "AUTO" (autodetect, read only)
force_report if 0, nothing happens; otherwise, choose the output message template using this report type instead of the one in the message
Returns:
The error indication for the function.
integer idba_prendilo ( integer  handle  ) 

Insert a new item in the database.

This function will fail if the database is open in data readonly mode, and it will refuse to overwrite existing values if the database is open in data add mode.

If the database is open in pseudoana reuse mode, the pseudoana values provided on input will be used to create a pseudoana record if it is missing, but will be ignored if it is already present. If it is open in pseudoana rewrite mode instead, the pseudoana values on input will be used to replace all the existing pseudoana values.

Parameters:
handle Handle to a DBALLE session
Returns:
The error indicator for the function
integer idba_preparati ( integer  dbahandle,
integer  handle,
character  anaflag,
character  dataflag,
character  attrflag 
)

Starts a session with dballe.

You can call idba_preparati() many times and get more handles. This allows to perform many operations on the database at the same time.

idba_preparati() has three extra parameters that can be used to limit write operations on the database, as a limited protection against programming errors.

Note that some combinations of parameters are illegal, such as anaflag=read and dataflag=add (when adding a new data, it's sometimes necessary to insert new pseudoana records), or dataflag=rewrite and qcflag=read (when deleting data, their attributes are deleted as well).

Parameters:
dbahandle The main DB-ALLe connection handle
Return values:
handle The session handle returned by the function
Parameters:
anaflag Controls access to pseudoana records and can have these values:

  • "read" pseudoana records cannot be inserted.
  • "write" it is possible to insert and delete pseudoana records.
dataflag Controls access to observed data and can have these values:

  • "read" data cannot be modified in any way.
  • "add" data can be added to the database, but existing data cannot be modified. Deletions are disabled. This is used to insert new data in the database while preserving the data that was already present in it.
  • "write" data can freely be added, overwritten and deleted.
qcflag Controls access to data attributes and can have these values:

  • "read" attributes cannot be modified in any way.
  • "add" attributes can can be added to the database, but existing attributes cannot be modified. Deletion of attributes is disabled. This is used to insert new attribute in the database while preserving the attributes that were already present in it.
  • "write" attributes can freely be added, overwritten and deleted.
Returns:
The error indication for the function.
integer idba_presentati ( integer  dbahandle,
character  dsn,
character  user,
character  password 
)

Start working with a DBALLE database.

This function can be called more than once once to connect to different databases at the same time.

Parameters:
dsn The ODBC DSN of the database to use
user The username used to connect to the database
password The username used to connect to the database
Return values:
dbahandle The database handle that can be passed to idba_preparati to work with the database.
Returns:
The error indication for the function.
integer idba_quantesono ( integer  handle,
integer  count 
)

Count the number of elements in the anagraphical storage, and start a new anagraphical query.

Resulting anagraphical data can be retrieved with idba_elencamele()

Parameters:
handle Handle to a DBALLE session
count The count of elements
Returns:
The error indicator for the function
integer idba_scopa ( integer  handle,
character  repinfofile 
)

Reset the database contents, loading default report informations from a file.

It only works in rewrite mode.

Parameters:
handle Handle to a DBALLE session
repinfofile CSV file with the default report informations. See dba_reset() documentation for the format of the file.
Returns:
The error indicator for the function
integer idba_scusa ( integer  handle  ) 

Remove QC informations for a variable of the current record.

The QC informations to be removed are set with: 

   idba_setc(handle, "*varlist", "*B33021,*B33003");

The variable referred by the QC informations can be specified in three ways:

  • by variable code, using idba_setc(handle, "*var", "Bxxyyy")
  • by variable id, using idba_seti(handle, "*data_id", id)
  • unspecified, will use the last variable returned by idba_dammelo
Parameters:
handle Handle to a DBALLE session
Returns:
The error indicator for the function
integer idba_setb ( integer  handle,
character  parameter 
)

Set one byte value into the input record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value The value to assign to the parameter
Returns:
The error indicator for the function
integer idba_setc ( integer  handle,
character  parameter,
character  value 
)

Set one character value into the input record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value The value to assign to the parameter
Returns:
The error indicator for the function
integer idba_setcontextana ( integer  handle  ) 

Shortcut function to set query parameters to the anagraphical context.

Parameters:
handle Handle to a DBALLE session
Returns:
The error indicator for the function
integer idba_setd ( integer  handle,
character  parameter,
double  value 
)

Set one real*8 value into the input record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value The value to assign to the parameter
Returns:
The error indicator for the function
integer idba_setdate ( integer  handle,
integer  year,
integer  month,
integer  day,
integer  hour,
integer  min,
integer  sec 
)

Shortcut function to set date information.

Parameters:
handle Handle to a DBALLE session
year Year to set in the input record
month Month to set in the input
day Day to set in the input
hour Hour to set in the input
min Minute to set in the input
sec Second to set in the input
Returns:
The error indicator for the function
integer idba_setdatemax ( integer  handle,
integer  year,
integer  month,
integer  day,
integer  hour,
integer  min,
integer  sec 
)

Shortcut function to set maximum date for a query.

Parameters:
handle Handle to a DBALLE session
year Maximum year to set in the query
month Maximum month to set in the query
day Maximum day to set in the query
hour Maximum hour to set in the query
min Maximum minute to set in the query
sec Maximum second to set in the query
Returns:
The error indicator for the function
integer idba_setdatemin ( integer  handle,
integer  year,
integer  month,
integer  day,
integer  hour,
integer  min,
integer  sec 
)

Shortcut function to set minimum date for a query.

Parameters:
handle Handle to a DBALLE session
year Minimum year to set in the query
month Minimum month to set in the query
day Minimum day to set in the query
hour Minimum hour to set in the query
min Minimum minute to set in the query
sec Minimum second to set in the query
Returns:
The error indicator for the function
integer idba_seti ( integer  handle,
character  parameter,
integer  value 
)

Set one integer value into the input record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value The value to assign to the parameter
Returns:
The error indicator for the function
integer idba_setlevel ( integer  handle,
integer  ltype1,
integer  l1,
integer  ltype2,
integer  l2 
)

Shortcut function to set level data.

Parameters:
handle Handle to a DBALLE session
ltype Level type to set in the input record
l1 L1 to set in the input record
l2 L2 to set in the input record
Returns:
The error indicator for the function
integer idba_setr ( integer  handle,
character  parameter,
real  value 
)

Set one real value into the input record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to set. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
value The value to assign to the parameter
Returns:
The error indicator for the function
integer idba_settimerange ( integer  handle,
integer  ptype,
integer  p1,
integer  p2 
)

Shortcut function to set time range data.

Parameters:
handle Handle to a DBALLE session
ptype P indicator to set in the input record
p1 P1 to set in the input record
p2 P2 to set in the input record
Returns:
The error indicator for the function
integer idba_spiegab ( integer  handle,
character  varcode,
character  value,
character  result 
)

Retrieve QC informations from the last variable returned by idba_dammelo().

Parameters:
handle Handle to a DBALLE session
Return values:
parameter Contains the ID of the parameter retrieved by this fetch
Returns:
The error indicator for the function
integer idba_spiegal ( integer  handle,
integer  ltype1,
integer  l1,
integer  ltype2,
integer  l2,
character  result 
)

Retrieve QC informations from the last variable returned by idba_dammelo().

Parameters:
handle Handle to a DBALLE session
Return values:
parameter Contains the ID of the parameter retrieved by this fetch
Returns:
The error indicator for the function
integer idba_spiegat ( integer  handle,
integer  ptype,
integer  p1,
integer  p2,
character  result 
)

Retrieve QC informations from the last variable returned by idba_dammelo().

Parameters:
handle Handle to a DBALLE session
Return values:
parameter Contains the ID of the parameter retrieved by this fetch
Returns:
The error indicator for the function
integer idba_test_input_to_output ( integer  handle  ) 

Retrieve QC informations from the last variable returned by idba_dammelo().

Parameters:
handle Handle to a DBALLE session
Return values:
parameter Contains the ID of the parameter retrieved by this fetch
Returns:
The error indicator for the function
integer idba_unset ( integer  handle,
character  parameter 
)

Remove one parameter from the input record.

Parameters:
handle Handle to a DBALLE session
parameter Parameter to remove. It can be the code of a WMO variable prefixed by "B" (such as "B01023"); the code of a QC value prefixed by "*B" (such as "*B01023") or a keyword among the ones defined in dba_record_keywords
Returns:
The error indicator for the function
subroutine idba_unsetall ( integer  handle  ) 

Remove all parameters from the input record.

Parameters:
handle Handle to a DBALLE session
integer idba_voglioancora ( integer  handle,
integer  count 
)

Retrieve QC informations from the last variable returned by idba_dammelo().

Parameters:
handle Handle to a DBALLE session
Return values:
parameter Contains the ID of the parameter retrieved by this fetch
Returns:
The error indicator for the function
integer idba_voglioquesto ( integer  handle,
integer  count 
)

Submit a query to the database.

The query results can be accessed with calls to idba_dammelo.

Parameters:
handle Handle to a DBALLE session
Return values:
count Number of values returned by the function
Returns:
The error indicator for the function
Generated on Sun Jun 13 22:26:41 2010 for libdballeFortranbindings by  doxygen 1.6.3