vartable.h File Reference


Detailed Description

Implement fast access to information about WMO variables.

The measured value of a physical quantity has little meaning without specifying what quantity it represents, what units are used to measure it, and how many digits are significant for the value.

This module provides access to all this metadata:

There are many B tables with slight differences used by different meteorological centre or equipment. This module allows to access different vartables using dba_vartable_create().

DB-All.e provides a default B table called the "local B table" which is used for the encoding-independent values. The local B table has the desirable property of having unambiguous entries for the various physical values: normal B tables can have more than one, for example low accuracy and high accuracy latitudes. The local B table can be queried using dba_varinfo_query_local().

dba_vartable and dba_varinfo have special memory management: they are never deallocated. This is a precise design choice to speed up passing and copying dba_varinfo values, that are used very intensely as they accompany all the physical values processed by DB-All.e and its components. This behaviour should not be a cause of memory leaks, since a software would only need to access a limited amount of B tables during its lifetime.

To construct a dba_varcode value one needs to provide three numbers: F, X and Y.

The normal text representation of a dba_varcode for a WMO B table uses the format Bxxyyy.

See Local B table for the contents of the local B table and their relative dba_varcode values.

#include <dballe/core/error.h>

Go to the source code of this file.

Data Structures

struct  _dba_varinfo
 Holds the information about a DBALLE variable. More...

Defines

#define DBA_VAR(f, x, y)   ((dba_varcode)( ((unsigned)(f)<<14) | ((unsigned)(x)<<8) | (unsigned)(y) ))
 Create a WMO variable code from its F, X and Y components.
#define DBA_STRING_TO_VAR(str)
 Convert a XXYYY string to a WMO variable code.
#define DBA_VAR_F(code)   ((code) >> 14)
 Get the F part of a WMO variable code.
#define DBA_VAR_X(code)   ((code) >> 8 & 0x3f)
 Get the X part of a WMO variable code.
#define DBA_VAR_Y(code)   ((code) & 0xff)
 Get the Y part of a WMO variable code.
#define DBA_ALT(width, scale)   (((width)+128) << 8 | ((scale)+128))
 Create a variable alteration value.
#define DBA_ALT_WIDTH(code)   (((code) >> 8) - 128)
 Read the width part of a variable alteration value.
#define DBA_ALT_SCALE(code)   (((code) & 0xff) - 128)
 Read the scale part of a variable alteration value.

Typedefs

typedef short unsigned int dba_varcode
 Holds the WMO variable code of a variable.
typedef short unsigned int dba_alteration
 Describes how a dba_varinfo has been altered: it is used for supporting variables coming from BUFR and CREX messages that use C codes to alter variable information.
typedef _dba_varinfodba_varinfo
 Holds the information about a DBALLE variable.

It never needs to be deallocated, as all the dba_varinfo returned by DB-ALLe are pointers to memory-cached versions that are guaranteed to exist for all the lifetime of the program.

typedef _dba_vartable * dba_vartable
 
typedef void(*) dba_vartable_iterator (dba_varinfo info, void *data)
 Type of callback called by dba_vartable_iterate() on every member of a dba_vartable.

Functions

dba_err dba_varinfo_query_local (dba_varcode code, dba_varinfo *info)
 Query informations about the DBALLE variable definitions.
dba_err dba_varinfo_query_local_altered (dba_varcode code, dba_alteration change, dba_varinfo *info)
 Query informations about the DBALLE variable definitions.
dba_err dba_varinfo_get_local_table (dba_vartable *table)
 Get a reference to the local B table.
dba_varcode dba_descriptor_code (const char *desc)
 Convert a FXXYYY string descriptor code into its short integer representation.
dba_err dba_vartable_create (const char *id, dba_vartable *table)
 Create a new vartable structure.
const char * dba_vartable_id (dba_vartable table)
 Return the ID for the given table.
dba_err dba_vartable_query (dba_vartable table, dba_varcode var, dba_varinfo *info)
 Query the vartable.
dba_err dba_vartable_query_altered (dba_vartable table, dba_varcode var, dba_alteration change, dba_varinfo *info)
 Query an altered version of the vartable.
dba_err dba_vartable_iterate (dba_vartable table, dba_vartable_iterator func, void *data)
 Iterate through all elements in a dba_vartable.


Define Documentation

#define DBA_STRING_TO_VAR ( str   ) 

Value:

((dba_varcode)( \
        (( ((str)[0] - '0')*10 + ((str)[1] - '0') ) << 8) | \
        ( ((str)[2] - '0')*100 + ((str)[3] - '0')*10 + ((str)[4] - '0') ) \
))
Convert a XXYYY string to a WMO variable code.

This is useful only in rare cases, such as when parsing tables; use dba_descriptor_code to parse proper entry names such as "B01003" or "D21301".


Typedef Documentation

typedef void(*) dba_vartable_iterator(dba_varinfo info, void *data)

Type of callback called by dba_vartable_iterate() on every member of a dba_vartable.

Parameters:
info Element of the table that is currently visited.
data Arbitrary user-supplied data given as the data parameter in dba_vartable_iterate()


Function Documentation

dba_varcode dba_descriptor_code ( const char *  desc  ) 

Convert a FXXYYY string descriptor code into its short integer representation.

Parameters:
desc The 6-byte string descriptor as FXXYYY
Returns:
The short integer code that can be queried with the DBA_GET_* macros

dba_err dba_varinfo_get_local_table ( dba_vartable table  ) 

Get a reference to the local B table.

Return values:
table The local B table. dba_vartable structures are never deallocated: the pointer will be valid through the entire lifetime of the program, and can be freely copied.
Returns:
The error indicator for this function (See error.h)

dba_err dba_varinfo_query_local ( dba_varcode  code,
dba_varinfo info 
)

Query informations about the DBALLE variable definitions.

Parameters:
code The dba_varcode of the variable to query
Return values:
info the dba_varinfo structure with the results of the query. The returned dba_varinfo is stored inside the dba_vartable, can be freely copied around and does not need to be deallocated.
Returns:
The error indicator for this function (See error.h)

dba_err dba_varinfo_query_local_altered ( dba_varcode  code,
dba_alteration  change,
dba_varinfo info 
)

Query informations about the DBALLE variable definitions.

Parameters:
code The dba_varcode of the variable to query
change WMO C table entry specify a change on the variable characteristics
Return values:
info the dba_varinfo structure with the results of the query. The returned dba_varinfo is stored inside the dba_vartable, can be freely copied around and does not need to be deallocated.
Returns:
The error indicator for this function (See error.h)

dba_err dba_vartable_create ( const char *  id,
dba_vartable table 
)

Create a new vartable structure.

Parameters:
id ID of the vartable data to access
Return values:
table The vartable to access the data. dba_vartable structures are never deallocated: the pointer will be valid through the entire lifetime of the program, and can be freely copied.
Returns:
The error status (See error.h)

const char* dba_vartable_id ( dba_vartable  table  ) 

Return the ID for the given table.

Parameters:
table The table to query
Returns:
The table id. It is a pointer to the internal value, and does not need to be deallocated.

dba_err dba_vartable_iterate ( dba_vartable  table,
dba_vartable_iterator  func,
void *  data 
)

Iterate through all elements in a dba_vartable.

Parameters:
table Table to iterate.
func Callback to be called for every item of the table.
data Arbitrary value passed as-is to the callback.
Returns:
The error status (See error.h)

dba_err dba_vartable_query ( dba_vartable  table,
dba_varcode  var,
dba_varinfo info 
)

Query the vartable.

Parameters:
table vartable to query
var vartable entry number (i.e. the XXYYY number in BXXYYY)
Return values:
info the dba_varinfo structure with the results of the query. The returned dba_varinfo is stored inside the dba_vartable, can be freely copied around and does not need to be deallocated.
Returns:
The error status (See error.h)

dba_err dba_vartable_query_altered ( dba_vartable  table,
dba_varcode  var,
dba_alteration  change,
dba_varinfo info 
)

Query an altered version of the vartable.

Parameters:
table vartable to query
var vartable entry number (i.e. the XXYYY number in BXXYYY)
change WMO C table entry specify a change on the variable characteristics
Return values:
info the dba_varinfo structure with the results of the query. The returned dba_varinfo is stored inside the dba_vartable, can be freely copied around and does not need to be deallocated.
Returns:
The error status (See error.h)


Generated on Fri Jun 22 15:34:04 2007 for libdballe-db by  doxygen 1.5.2