Skip to end of metadata
Go to start of metadata

ecCodes is an evolution of GRIB-API and will replace it in the future.

GRIB-API is entirely included in ecCodes without any major change to its Fortran 90, Python and C interfaces.  However there are some minor changes and rationalisations described below.

API Changes

The following functions have been removed:
grib_handle_new_from_template: This was already deprecated in GRIB-API and has been replaced by grib_handle_new_from_samples.
grib_context_new: This was experimental. One should use the default context

In the Fortran interface, for GRIB keys whose value is MISSING, GRIB-API returns -1 whereas ecCodes returns the constant CODES_MISSING_LONG.
It is best to check whether a GRIB key is missing by using the function "grib_is_missing" rather than comparing the result of grib_get with -1. See example here.

An example of such a key is "Ni" (the number of points per latitude) for Reduced Gaussian Grids. Please check your code and make sure you are not comparing with -1.

In the Fortran interface of GRIB-API, the function grib_keys_iterator_next returns 1 if the next iterator exists and 0 if there are no more elements. But in ecCodes this function returns CODES_SUCCESS (=GRIB_SUCCESS) if the next iterator exists and an integer value if there are no more elements.

See example here.

We have also removed the Fortran 77 library (libgrib_api_f77.a) and the API examples.

Tool Changes

Some of the GRIB-API command line tools are not included in ecCodes because they have been superseded by other tools or they were experimental and are not needed anymore. In the following table the deprecated tools are listed:

Tool nameComments
grib_cmpSuperseded by grib_compare
grib_debugSuperseded by "grib_dump -D"
grib_convertSuperseded by grib_filter
grib_distanceThis tool was experimental
grib_errorThis tool was experimental
grib_keysThis tool was experimental
grib_add

This tool was experimental

grib_corruption_checkThis tool was experimental
pointsThis tool was experimental
grib_packingThis tool was experimental
grib_momentsThis tool was experimental
big2gribexThis tool was experimental
grib_list_keysThis tool was experimental
grib_repairThis tool was experimental
grib_to_jsonThis tool was experimental
gg_sub_area_checkThis tool was experimental

Also note that the tool grib_info is now renamed to codes_info.

Definition Language Changes

Please also note that some changes have been made to the definitions language so users who have their own versions of the the definitions need to be aware of the following change:
In ecCodes the keyword "length" has been changed to "section_length" so for example in the file definitions/grib1/section.1.def:

   length[3] section1Length ;

has been changed to

   section_length[3] section1Length ;

 

The names of the files in the definitions/mars directory have also changed. Previously they had the prefix "grib1" but this was misleading as they pertain to all editions. So the new files have the prefix "grib" e.g.

   definitions/mars/grib.oper.fc.def

 

The "include" statements now require the relative path from the top-level of the definitions directory so instead of

   include "template.4.statistical.def"

We now have

   include "grib2/template.4.statistical.def"

 

The migration from GRIB-API to ecCodes should not affect user software and will be managed in installation and linking phases. Nevertheless, very significant changes in the library have been performed to implement the encoding of different types of messages and in particular for BUFR.

To be confident that ecCodes behaves as GRIB-API (as far as GRIB decoding and encoding is concerned) a set of regression tests are being performed. At the moment all the standard tests are passing without problems. One important aspect of the library is performance and we are continuously checking that ecCodes performs at least as well as GRIB-API. In the latest version the difference in performance is not significant. ecCodes is performing as well as GRIB-API and in some tests it is slightly better.

Some more tests are needed to be fully confident that ecCodes can replace GRIB-API in an operational environment, but we don't have experience at the moment of problems with the GRIB decoding/encoding part of ecCodes. We strongly advise the users to do their own migration tests and send feedback to software.support@ecmwf.int.

 

  • No labels