libdballeFortranbindings  5.18
Defines | Functions | Variables
binding.cc File Reference

Simplified interface for Dballe. More...

#include "config.h"
#include "msgapi.h"
#include <cstring>
#include <limits.h>
#include <float.h>
#include "handles.h"
#include "error.h"
#include <f77.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

Functions

subroutine idba_arrivederci (integer dbahandle)
 Stop working with a DBALLE database.
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().

Variables

struct fortran::Handler
< HSimple, MAX_SIMPLE > 
hsimp

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:
handleHandle to a DBALLE session
Return values:
parameterContains 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:
dbahandleThe 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:
handleHandle 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:
handleHandle to a DBALLE session
Return values:
parameterContains 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:
handleHandle 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:
handleHandle 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:
handleHandle to a DBALLE session
parameterParameter 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
valueWhere 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:
handleHandle to a DBALLE session
parameterParameter 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
valueWhere 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:
handleHandle to a DBALLE session
parameterParameter 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
valueWhere 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:
handleHandle to a DBALLE session
Return values:
yearYear from the output record
monthMonth the output record
dayDay the output record
hourHour the output record
minMinute the output record
secSecond 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:
handleHandle to a DBALLE session
parameterParameter 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
valueWhere 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:
handleHandle to a DBALLE session
Return values:
ltypeLevel type from the output record
l1L1 from the output record
l2L2 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:
handleHandle to a DBALLE session
parameterParameter 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
valueWhere 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:
handleHandle to a DBALLE session
Return values:
ptypeP indicator from the output record
p1P1 from the output record
p2P2 from the output record
Returns:
The error indicator for the function
integer idba_fatto ( integer  handle)

Ends a session with DBALLE.

Parameters:
handleHandle 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:
handleThe session handle returned by the function
Parameters:
filenameName of the file to open
modeFile open mode. It can be:
  • r for read
  • w for write (the old file is deleted)
  • a for append
typeFormat of the data in the file. It can be:
  • "BUFR"
  • "CREX"
  • "AOF" (read only)
  • "AUTO" (autodetect, read only)
force_reportif 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:
handleHandle to a DBALLE session
Returns:
The error indicator 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:
handleHandle to a DBALLE session
countThe 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:
handleHandle to a DBALLE session
repinfofileCSV 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:
handleHandle 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:
handleHandle to a DBALLE session
parameterParameter 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
valueThe 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:
handleHandle to a DBALLE session
parameterParameter 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
valueThe 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:
handleHandle 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:
handleHandle to a DBALLE session
parameterParameter 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
valueThe 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:
handleHandle to a DBALLE session
yearYear to set in the input record
monthMonth to set in the input
dayDay to set in the input
hourHour to set in the input
minMinute to set in the input
secSecond 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:
handleHandle to a DBALLE session
yearMaximum year to set in the query
monthMaximum month to set in the query
dayMaximum day to set in the query
hourMaximum hour to set in the query
minMaximum minute to set in the query
secMaximum 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:
handleHandle to a DBALLE session
yearMinimum year to set in the query
monthMinimum month to set in the query
dayMinimum day to set in the query
hourMinimum hour to set in the query
minMinimum minute to set in the query
secMinimum 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:
handleHandle to a DBALLE session
parameterParameter 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
valueThe 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:
handleHandle to a DBALLE session
ltypeLevel type to set in the input record
l1L1 to set in the input record
l2L2 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:
handleHandle to a DBALLE session
parameterParameter 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
valueThe 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:
handleHandle to a DBALLE session
ptypeP indicator to set in the input record
p1P1 to set in the input record
p2P2 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:
handleHandle to a DBALLE session
Return values:
parameterContains 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:
handleHandle to a DBALLE session
Return values:
parameterContains 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:
handleHandle to a DBALLE session
Return values:
parameterContains 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:
handleHandle to a DBALLE session
Return values:
parameterContains 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:
handleHandle to a DBALLE session
parameterParameter 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:
handleHandle to a DBALLE session
integer idba_voglioancora ( integer  handle,
integer  count 
)

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

Parameters:
handleHandle to a DBALLE session
Return values:
parameterContains 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:
handleHandle to a DBALLE session
Return values:
countNumber of values returned by the function
Returns:
The error indicator for the function