libdballe 4.0.18
Data Structures | Typedefs | Enumerations | Functions
msg.h File Reference

Abstraction for a weather report message which is independent from the encoding, used to make sense of decoded information and to carry data between the various import and export modules of DB-ALLe. More...

#include <dballe/core/error.h>
#include <dballe/core/var.h>
#include <stdio.h>
#include <dballe/msg/vars.h>

Go to the source code of this file.

Data Structures

struct  _dba_msg
 Storage for related physical data. More...

Typedefs

typedef enum _dba_msg_type dba_msg_type
typedef struct _dba_msg_contextdba_msg_context
typedef struct _dba_msgdba_msg

Enumerations

enum  _dba_msg_type {
  MSG_GENERIC, MSG_SYNOP, MSG_PILOT, MSG_TEMP,
  MSG_TEMP_SHIP, MSG_AIREP, MSG_AMDAR, MSG_ACARS,
  MSG_SHIP, MSG_BUOY, MSG_METAR, MSG_SAT,
  MSG_POLLUTION
}
 Source of the data. More...

Functions

const char * dba_msg_type_name (dba_msg_type type)
 Return a string with the name of a dba_msg_type.
dba_err dba_msg_create (dba_msg *msg)
 Create a new dba_msg.
void dba_msg_print (dba_msg msg, FILE *out)
 Dump all the contents of the message to the given stream.
void dba_msg_diff (dba_msg msg1, dba_msg msg2, int *diffs, FILE *out)
 Print the differences between two dba_msg to a stream.
void dba_msg_delete (dba_msg msg)
 Delete a dba_msg.
dba_err dba_msg_set (dba_msg msg, dba_var var, dba_varcode code, int ltype1, int l1, int ltype2, int l2, int pind, int p1, int p2)
 Add or replace a value in the dba_msg.
dba_err dba_msg_set_nocopy (dba_msg msg, dba_var var, int ltype1, int l1, int ltype2, int l2, int pind, int p1, int p2)
 Add or replace a value in the dba_msg, taking ownership of the source variable witout copying it.
dba_err dba_msg_set_by_id (dba_msg msg, dba_var var, int id)
 Add or replace a value in the dba_msg.
dba_err dba_msg_set_nocopy_by_id (dba_msg msg, dba_var var, int id)
 Add or replace a value in the dba_msg, taking ownership of the source variable witout copying it.
dba_err dba_msg_seti (dba_msg msg, dba_varcode code, int val, int conf, int ltype1, int l1, int ltype2, int l2, int pind, int p1, int p2)
 Add or replace an integer value in the dba_msg.
dba_err dba_msg_setd (dba_msg msg, dba_varcode code, double val, int conf, int ltype1, int l1, int ltype2, int l2, int pind, int p1, int p2)
 Add or replace a double value in the dba_msg.
dba_err dba_msg_setc (dba_msg msg, dba_varcode code, const char *val, int conf, int ltype1, int l1, int ltype2, int l2, int pind, int p1, int p2)
 Add or replace a string value in the dba_msg.
dba_msg_context dba_msg_find_context (dba_msg msg, int ltype1, int l1, int ltype2, int l2, int pind, int p1, int p2)
 Find a level given its description.
dba_var dba_msg_find (dba_msg msg, dba_varcode code, int ltype1, int l1, int ltype2, int l2, int pind, int p1, int p2)
 Find a variable given its description.
dba_var dba_msg_find_by_id (dba_msg msg, int id)
 Find a datum given its shortcut ID.
dba_msg_type dba_msg_get_type (dba_msg msg)
 Get the source of the data.
dba_msg_type dba_msg_type_from_repmemo (const char *repmemo)
 Get the message source type corresponding to the given report code.
const char * dba_msg_repmemo_from_type (dba_msg_type type)
 Get the report code corresponding to the given message source type.
dba_err dba_msg_sounding_pack_levels (dba_msg msg, dba_msg *dst)
 Copy a dba_msg, removing the sounding significance from the level descriptions and packing together the data at the same pressure level.
dba_err dba_msg_sounding_unpack_levels (dba_msg msg, dba_msg *dst)
 Copy a dba_msg, adding the sounding significance from the level descriptions and moving the data at the same pressure level to the resulting pseudolevels.
dba_err dba_msg_lua_push (dba_msg var, struct lua_State *L)
 Push the variable as an object in the lua stack.
dba_msg dba_msg_lua_check (struct lua_State *L, int idx)
 Check that the element at idx is a dba_msg.

Detailed Description

Abstraction for a weather report message which is independent from the encoding, used to make sense of decoded information and to carry data between the various import and export modules of DB-ALLe.

The internal representation is as connected as possible to physics rather than to observations. dba_msg is a container for related weather information, stored in a nonambiguous way.

To understand what is the difference betwee dba_msg and other ways of representing weather data, it is important to keep in mind how a value is usually defined in the various encodings:

dba_msg contains values as tuples (variable, level layer, time range).

The variable is represented by a dba_var. The dba_varcode of the dba_var refers to a local B table which lists physical measurements unambiguously.

Level layer is a triple (level type, l1, l2) and time range is a triple (pindicator, p1, p2). The values of these two triples follow what is used in the GRIB encoding plus some local extensions, and an explanation of their possible value is found in the document "DB-ALLe Guide of the Fortran API".

Importers and exporters have to implement a mapping between their representation and the unambiguous physical representation. Luckily this is necessarily possible, because the ultimate purpose of the various message encodings is to correctly transmit those physical data.

Since to work with the full physical coordinates one needs to specify a lot of different parameters in order to identify a value (BLocal value, level layer, time range), there is a var.h module available with shortcut functions to the values that are used more commonly.


Typedef Documentation

typedef struct _dba_msg* dba_msg

Storage for related physical data.

Store an array of physical data all on the same level.

Source of the data.


Enumeration Type Documentation

Source of the data.

Enumerator:
MSG_GENERIC 

Data from unspecified source.

MSG_SYNOP 

Synop measured data.

MSG_PILOT 

Pilot sounding data.

MSG_TEMP 

Temp sounding data.

MSG_TEMP_SHIP 

Temp ship sounding data.

MSG_AIREP 

Airep airplane data.

MSG_AMDAR 

Amdar airplane data.

MSG_ACARS 

Acars airplane data.

MSG_SHIP 

Ship measured data.

MSG_BUOY 

Buoy measured data.

MSG_METAR 

Metar data.

MSG_SAT 

Satellite data.

MSG_POLLUTION 

Pollution data.


Function Documentation

dba_err dba_msg_create ( dba_msg msg)

Create a new dba_msg.

Return values:
msgThe newly created dba_msg.
Returns:
The error indicator for the function (See error.h)

References _dba_msg::data, _dba_msg::data_alloc, _dba_msg::data_count, MSG_GENERIC, and _dba_msg::type.

void dba_msg_delete ( dba_msg  msg)

Delete a dba_msg.

Parameters:
msgThe dba_msg to delete.

References _dba_msg::data, _dba_msg::data_alloc, and _dba_msg::data_count.

void dba_msg_diff ( dba_msg  msg1,
dba_msg  msg2,
int *  diffs,
FILE *  out 
)

Print the differences between two dba_msg to a stream.

Parameters:
msg1First dba_msg to compare
msg2Second dba_msg to compare
Return values:
diffsInteger variable that will be incremented by the number of differences found.
Parameters:
outThe stream to dump a description of the differences to.

References _dba_msg::data, _dba_msg_context::data_count, _dba_msg::data_count, and _dba_msg::type.

dba_var dba_msg_find ( dba_msg  msg,
dba_varcode  code,
int  ltype1,
int  l1,
int  ltype2,
int  l2,
int  pind,
int  p1,
int  p2 
)

Find a variable given its description.

Parameters:
msgThe dba_msg to query
codeThe dba_varcode of the variable to query. See vartable.h
ltypeType of the level. See Level type values.
l1L1 value of the level. See Level type values.
l2L2 value of the level. See Level type values.
Returns:
The variable found, or NULL if it was not found.
dba_var dba_msg_find_by_id ( dba_msg  msg,
int  id 
)

Find a datum given its shortcut ID.

Parameters:
msgThe message to query
idShortcut ID of the value to set (see vars.h)
Returns:
The value found, or NULL if it was not found.

References _dba_msg_var::code, _dba_msg_var::l1, _dba_msg_var::l2, _dba_msg_var::ltype1, _dba_msg_var::ltype2, _dba_msg_var::p1, _dba_msg_var::p2, and _dba_msg_var::pind.

dba_msg_context dba_msg_find_context ( dba_msg  msg,
int  ltype1,
int  l1,
int  ltype2,
int  l2,
int  pind,
int  p1,
int  p2 
)

Find a level given its description.

Parameters:
msgThe dba_msg to query
ltypeType of the level. See Level type values.
l1L1 value of the level. See Level type values.
l2L2 value of the level. See Level type values.
pindTime range type indicator. See Time range values.
p1Time range P1 indicator. See Time range values.
p2Time range P2 indicator. See Time range values.
Returns:
The context found, or NULL if it was not found.

References _dba_msg::data, and _dba_msg::data_count.

dba_msg_type dba_msg_get_type ( dba_msg  msg)

Get the source of the data.

Parameters:
msgThe dba_msg to query
Returns:
The query source type

References _dba_msg::type.

dba_msg dba_msg_lua_check ( struct lua_State *  L,
int  idx 
)

Check that the element at idx is a dba_msg.

Returns:
the dba_msg element, or NULL if the check failed

References dba_error_unimplemented.

void dba_msg_print ( dba_msg  msg,
FILE *  out 
)

Dump all the contents of the message to the given stream.

Parameters:
msgThe dba_msg to dump
outThe stream to dump the contents of the dba_msg to.

References _dba_msg::data, _dba_msg::data_count, MSG_PILOT, MSG_TEMP, MSG_TEMP_SHIP, and _dba_msg::type.

dba_err dba_msg_set ( dba_msg  msg,
dba_var  var,
dba_varcode  code,
int  ltype1,
int  l1,
int  ltype2,
int  l2,
int  pind,
int  p1,
int  p2 
)

Add or replace a value in the dba_msg.

Parameters:
msgThe message to operate on
varThe dba_var with the value to set, that will be copied into the dba_msg.
codeThe dba_varcode of the destination value. If it is different than the varcode of var, a conversion will be attempted.
ltype1Type of the first level. See Level type values.
l1L1 value of the level. See Level type values.
ltype2Type of the second level. See Level type values.
l2L2 value of the level. See Level type values.
pindTime range type indicator. See Time range values.
p1Time range P1 indicator. See Time range values.
p2Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, and DBA_RUN_OR_RETURN.

dba_err dba_msg_set_by_id ( dba_msg  msg,
dba_var  var,
int  id 
)

Add or replace a value in the dba_msg.

Parameters:
msgThe message to operate on
varThe dba_var with the value to set, that will be copied into the dba_msg.
idShortcut ID of the value to set (see vars.h)
Returns:
The error indicator for the function (See error.h)

References _dba_msg_var::code, DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, _dba_msg_var::l1, _dba_msg_var::l2, _dba_msg_var::ltype1, _dba_msg_var::ltype2, _dba_msg_var::p1, _dba_msg_var::p2, and _dba_msg_var::pind.

dba_err dba_msg_set_nocopy ( dba_msg  msg,
dba_var  var,
int  ltype1,
int  l1,
int  ltype2,
int  l2,
int  pind,
int  p1,
int  p2 
)

Add or replace a value in the dba_msg, taking ownership of the source variable witout copying it.

Parameters:
msgThe message to operate on
varThe dba_var with the value to set. This dba_msg will take ownership of memory management.
ltypeType of the level. See Level type values.
l1L1 value of the level. See Level type values.
l2L2 value of the level. See Level type values.
pindTime range type indicator. See Time range values.
p1Time range P1 indicator. See Time range values.
p2Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, and DBA_RUN_OR_RETURN.

dba_err dba_msg_set_nocopy_by_id ( dba_msg  msg,
dba_var  var,
int  id 
)

Add or replace a value in the dba_msg, taking ownership of the source variable witout copying it.

Parameters:
msgThe message to operate on
varThe dba_var with the value to set. This dba_msg will take ownership of memory management.
idShortcut ID of the value to set (see vars.h)
Returns:
The error indicator for the function (See error.h)

References _dba_msg_var::l1, _dba_msg_var::l2, _dba_msg_var::ltype1, _dba_msg_var::ltype2, _dba_msg_var::p1, _dba_msg_var::p2, and _dba_msg_var::pind.

dba_err dba_msg_setc ( dba_msg  msg,
dba_varcode  code,
const char *  val,
int  conf,
int  ltype1,
int  l1,
int  ltype2,
int  l2,
int  pind,
int  p1,
int  p2 
)

Add or replace a string value in the dba_msg.

Parameters:
msgThe message to operate on
codeThe dba_varcode of the destination value. See vartable.h
valThe string value of the data
confThe confidence interval of the data, as the value of a B33007 WMO B (per cent confidence) table entry, that is, a number between 0 and 100 inclusive. -1 means no confidence interval attribute.
ltypeType of the level. See Level type values.
l1L1 value of the level. See Level type values.
l2L2 value of the level. See Level type values.
pindTime range type indicator. See Time range values.
p1Time range P1 indicator. See Time range values.
p2Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, and DBA_VAR.

dba_err dba_msg_setd ( dba_msg  msg,
dba_varcode  code,
double  val,
int  conf,
int  ltype1,
int  l1,
int  ltype2,
int  l2,
int  pind,
int  p1,
int  p2 
)

Add or replace a double value in the dba_msg.

Parameters:
msgThe message to operate on
codeThe dba_varcode of the destination value. See vartable.h
valThe double value of the data
confThe confidence interval of the data, as the value of a B33007 WMO B (per cent confidence) table entry, that is, a number between 0 and 100 inclusive. -1 means no confidence interval attribute.
ltypeType of the level. See Level type values.
l1L1 value of the level. See Level type values.
l2L2 value of the level. See Level type values.
pindTime range type indicator. See Time range values.
p1Time range P1 indicator. See Time range values.
p2Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, and DBA_VAR.

dba_err dba_msg_seti ( dba_msg  msg,
dba_varcode  code,
int  val,
int  conf,
int  ltype1,
int  l1,
int  ltype2,
int  l2,
int  pind,
int  p1,
int  p2 
)

Add or replace an integer value in the dba_msg.

Parameters:
msgThe message to operate on
codeThe dba_varcode of the destination value.. See vartable.h
valThe integer value of the data
confThe confidence interval of the data, as the value of a B33007 WMO B (per cent confidence) table entry, that is, a number between 0 and 100 inclusive. -1 means no confidence interval attribute.
ltypeType of the level. See Level type values.
l1L1 value of the level. See Level type values.
l2L2 value of the level. See Level type values.
pindTime range type indicator. See Time range values.
p1Time range P1 indicator. See Time range values.
p2Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

References DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, and DBA_VAR.

dba_err dba_msg_sounding_pack_levels ( dba_msg  msg,
dba_msg dst 
)

Copy a dba_msg, removing the sounding significance from the level descriptions and packing together the data at the same pressure level.

This is used to postprocess data after decoding, where the l2 field of the level description is temporarily used to store the vertical sounding significance, to simplify decoding.

References _dba_msg_context::data, _dba_msg::data, _dba_msg_context::data_count, _dba_msg::data_count, DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, _dba_msg_context::l1, _dba_msg_context::ltype1, _dba_msg_context::p1, _dba_msg_context::p2, _dba_msg_context::pind, and _dba_msg::type.

dba_err dba_msg_sounding_unpack_levels ( dba_msg  msg,
dba_msg dst 
)

Copy a dba_msg, adding the sounding significance from the level descriptions and moving the data at the same pressure level to the resulting pseudolevels.

This is used to preprocess data before encoding, where the l2 field of the level description is temporarily used to store the vertical sounding significance, to simplify encoding.

References _dba_msg::data, _dba_msg::data_count, DBA_RUN_OR_GOTO, DBA_RUN_OR_RETURN, _dba_msg_context::l2, and _dba_msg::type.

const char* dba_msg_type_name ( dba_msg_type  type)

Return a string with the name of a dba_msg_type.

Parameters:
typeThe dba_msg_type value to name
Returns:
The name, as a const string. This function is thread safe.

References MSG_ACARS, MSG_AIREP, MSG_AMDAR, MSG_BUOY, MSG_GENERIC, MSG_METAR, MSG_PILOT, MSG_POLLUTION, MSG_SAT, MSG_SHIP, MSG_SYNOP, MSG_TEMP, and MSG_TEMP_SHIP.