First Steps¶

Initialisation¶

The odc library makes heavy internal use of the provisions of the eckit library. As such, eckit must be properly initialised.

If odc is being used in a context where eckit is not already being used, it is necessary to call an initialisation function before odc is used.

#include "odc/api/odc.h"

int main() {
    odc_initialise_api();
    return 0;
}

Note

Make sure to reference the linked library when compiling:

gcc -lodccore odc_test.c

#include "eckit/runtime/Main.h"
#include "odc/api/Odb.h"

// We use the namespace to simplify the examples later in this documentation
using namespace odc::api;

int main(int argc, char* argv[]) {
    eckit::Main::initialise(argc, argv);
    return 0;
}

Note

Make sure to reference the linked library when compiling:

g++ -std=c++11 -lodccore odc_test.cc

program odc_test
    use odc
    implicit none

    integer :: rc

    rc = odc_initialise_api()
end program

Note

Make sure to reference the linked library when compiling:

gfortran -lfodc odc_test.f90

Note

All further code snippets in this guide depend on above headers being included and initialisation functions called.

Integer Handling¶

In the odc API interface integers can be treated in two different ways.

By default, an integer is represented as a 64-bit floating point number (a double).

Alternatively, an integer can be represented as a 64-bit signed integer (a long).

The integer-handling behaviour can be specified by calling a special function immediately after initialisation.

odc_integer_behaviour(ODC_INTEGERS_AS_LONGS);

Settings::treatIntegersAsDoubles(false);

rc = odc_integer_behaviour(ODC_INTEGERS_AS_LONGS)

Note

The only reason why integers are not being represented as 64-bit integers by default is to maintain backward compatibility with existing tools.

Note

The default integer-handling behaviour will change in a future release. It is highly recommended to be explicit about the integer-handling behaviour desired in any application.

Compatible and Incompatible Data¶

A stream of ODB-2 data comprises a sequence of Frames. These frames may be related to each other, or not, and they may or may not have the same columnar structure.

When two frames have the same columnar structure, we call them compatible. Otherwise the frames are incompatible.

In compatible data the columnar structure of the frames in the underlying ODB-2 data is logically the same – it contains the same number of columns, with the same names and types, albeit not necessarily in the same order. Within the odc library we can treat a contiguous group of these compatible frames as a larger aggregated frame. This can have performance benefits during decoding, as the real frames can be decoded in parallel within one logical frame.

Incompatible data requires the calling code to treat each frame separately.