msg.h File Reference


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.

#include <dballe/msg/level.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
 Source of the data.
typedef _dba_msgdba_msg
 Storage for related physical data.

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
}
 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 ltype, int l1, 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 ltype, int l1, 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 ltype, int l1, 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 ltype, int l1, 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 ltype, int l1, int l2, int pind, int p1, int p2)
 Add or replace a string value in the dba_msg.
dba_msg_level dba_msg_find_level (dba_msg msg, int ltype, int l1, int l2)
 Find a level given its description.
dba_msg_datum dba_msg_find (dba_msg msg, dba_varcode code, int ltype, int l1, int l2, int pind, int p1, int p2)
 Find a datum given its description.
dba_msg_datum 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_repcod (int repcod)
 Get the message source type corresponding to the given report code.
int dba_msg_repcod_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.


Enumeration Type Documentation

enum _dba_msg_type

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.


Function Documentation

dba_err dba_msg_create ( dba_msg msg  ) 

Create a new dba_msg.

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

void dba_msg_delete ( dba_msg  msg  ) 

Delete a dba_msg.

Parameters:
msg The dba_msg to delete.

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:
msg1 First dba_msg to compare
msg2 Second dba_msg to compare
Return values:
diffs Integer variable that will be incremented by the number of differences found.
Parameters:
out The stream to dump a description of the differences to.

dba_msg_datum dba_msg_find ( dba_msg  msg,
dba_varcode  code,
int  ltype,
int  l1,
int  l2,
int  pind,
int  p1,
int  p2 
)

Find a datum given its description.

Parameters:
msg The dba_msg to query
code The dba_varcode of the variable to query. See vartable.h
ltype Type of the level. See Level type values.
l1 L1 value of the level. See Level type values.
l2 L2 value of the level. See Level type values.
pind Time range type indicator. See Time range values.
p1 Time range P1 indicator. See Time range values.
p2 Time range P2 indicator. See Time range values.
Returns:
The level found, or NULL if it was not found.

dba_msg_datum dba_msg_find_by_id ( dba_msg  msg,
int  id 
)

Find a datum given its shortcut ID.

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

dba_msg_level dba_msg_find_level ( dba_msg  msg,
int  ltype,
int  l1,
int  l2 
)

Find a level given its description.

Parameters:
msg The dba_msg to query
ltype Type of the level. See Level type values.
l1 L1 value of the level. See Level type values.
l2 L2 value of the level. See Level type values.
Returns:
The level found, or NULL if it was not found.

dba_msg_type dba_msg_get_type ( dba_msg  msg  ) 

Get the source of the data.

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

void dba_msg_print ( dba_msg  msg,
FILE *  out 
)

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

Parameters:
msg The dba_msg to dump
out The stream to dump the contents of the dba_msg to.

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

Add or replace a value in the dba_msg.

Parameters:
msg The message to operate on
var The dba_var with the value to set, that will be copied into the dba_msg.
code The dba_varcode of the destination value. If it is different than the varcode of var, a conversion will be attempted.
ltype Type of the level. See Level type values.
l1 L1 value of the level. See Level type values.
l2 L2 value of the level. See Level type values.
pind Time range type indicator. See Time range values.
p1 Time range P1 indicator. See Time range values.
p2 Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

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:
msg The message to operate on
var The dba_var with the value to set, that will be copied into the dba_msg.
id Shortcut ID of the value to set (see vars.h)
Returns:
The error indicator for the function (See error.h)

dba_err dba_msg_set_nocopy ( dba_msg  msg,
dba_var  var,
int  ltype,
int  l1,
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:
msg The message to operate on
var The dba_var with the value to set. This dba_msg will take ownership of memory management.
ltype Type of the level. See Level type values.
l1 L1 value of the level. See Level type values.
l2 L2 value of the level. See Level type values.
pind Time range type indicator. See Time range values.
p1 Time range P1 indicator. See Time range values.
p2 Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

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:
msg The message to operate on
var The dba_var with the value to set. This dba_msg will take ownership of memory management.
id Shortcut ID of the value to set (see vars.h)
Returns:
The error indicator for the function (See error.h)

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

Add or replace a string value in the dba_msg.

Parameters:
msg The message to operate on
code The dba_varcode of the destination value. See vartable.h
val The string value of the data
conf The 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.
ltype Type of the level. See Level type values.
l1 L1 value of the level. See Level type values.
l2 L2 value of the level. See Level type values.
pind Time range type indicator. See Time range values.
p1 Time range P1 indicator. See Time range values.
p2 Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

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

Add or replace a double value in the dba_msg.

Parameters:
msg The message to operate on
code The dba_varcode of the destination value. See vartable.h
val The double value of the data
conf The 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.
ltype Type of the level. See Level type values.
l1 L1 value of the level. See Level type values.
l2 L2 value of the level. See Level type values.
pind Time range type indicator. See Time range values.
p1 Time range P1 indicator. See Time range values.
p2 Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

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

Add or replace an integer value in the dba_msg.

Parameters:
msg The message to operate on
code The dba_varcode of the destination value.. See vartable.h
val The integer value of the data
conf The 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.
ltype Type of the level. See Level type values.
l1 L1 value of the level. See Level type values.
l2 L2 value of the level. See Level type values.
pind Time range type indicator. See Time range values.
p1 Time range P1 indicator. See Time range values.
p2 Time range P2 indicator. See Time range values.
Returns:
The error indicator for the function (See error.h)

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.

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.

const char* dba_msg_type_name ( dba_msg_type  type  ) 

Return a string with the name of a dba_msg_type.

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


Generated on Fri Jun 22 15:18:07 2007 for libdballe-msg by  doxygen 1.5.2