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:
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.
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 struct _dba_varinfo * | dba_varinfo |
typedef struct _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 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') ) \ ))
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".
Referenced by dba_descriptor_code(), dba_record_contains(), dba_record_enq(), and dba_record_set_from_string().
typedef struct _dba_varinfo* dba_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 struct _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.
info | Element of the table that is currently visited. | |
data | Arbitrary user-supplied data given as the data parameter in dba_vartable_iterate() |
dba_varcode dba_descriptor_code | ( | const char * | desc | ) |
Convert a FXXYYY string descriptor code into its short integer representation.
desc | The 6-byte string descriptor as FXXYYY |
References DBA_STRING_TO_VAR.
dba_err dba_varinfo_get_local_table | ( | dba_vartable * | table | ) |
Get a reference to the local B table.
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. |
References DBA_RUN_OR_RETURN.
dba_err dba_varinfo_query_local | ( | dba_varcode | code, | |
dba_varinfo * | info | |||
) |
Query informations about the DBALLE variable definitions.
code | The dba_varcode of the variable to query |
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. |
References DBA_RUN_OR_RETURN.
dba_err dba_varinfo_query_local_altered | ( | dba_varcode | code, | |
dba_alteration | change, | |||
dba_varinfo * | info | |||
) |
Query informations about the DBALLE variable definitions.
code | The dba_varcode of the variable to query | |
change | WMO C table entry specify a change on the variable characteristics |
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. |
References DBA_RUN_OR_RETURN.
dba_err dba_vartable_create | ( | const char * | id, | |
dba_vartable * | table | |||
) |
Create a new vartable structure.
id | ID of the vartable data to access |
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. |
References DBA_RUN_OR_RETURN.
const char* dba_vartable_id | ( | dba_vartable | table | ) |
Return the ID for the given table.
table | The table to query |
dba_err dba_vartable_iterate | ( | dba_vartable | table, | |
dba_vartable_iterator | func, | |||
void * | data | |||
) |
Iterate through all elements in a dba_vartable.
table | Table to iterate. | |
func | Callback to be called for every item of the table. | |
data | Arbitrary value passed as-is to the callback. |
dba_err dba_vartable_query | ( | dba_vartable | table, | |
dba_varcode | var, | |||
dba_varinfo * | info | |||
) |
Query the vartable.
table | vartable to query | |
var | vartable entry number (i.e. the XXYYY number in BXXYYY) |
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. |
References dba_error_notfound, DBA_VAR_F, DBA_VAR_X, and DBA_VAR_Y.
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.
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 |
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. |
References _dba_varinfo::alteration, _dba_varinfo::alterations, _dba_varinfo::bit_len, DBA_ALT, DBA_ALT_SCALE, DBA_ALT_WIDTH, DBA_RUN_OR_RETURN, _dba_varinfo::dmax, _dba_varinfo::dmin, _dba_varinfo::imax, _dba_varinfo::imin, _dba_varinfo::is_string, _dba_varinfo::len, and _dba_varinfo::scale.