ecCodes is an evolution of GRIB-API and has replaced it at ECMWF. Users are strongly advised to start the migration process.
GRIB-API is entirely included in ecCodes without any major change to its Fortran 90, Python and C interfaces. The functions with the "grib_" prefix are included in the ecCodes library.
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.
The following C function signatures have changed:
grib_get_data: no longer takes the final "size" argument. This was redundant and never used by the function.
grib_fieldset_new_from_files: The "where_string" and "order_by_string" arguments are now "const char*".
grib_handle_new_from_message: The "data" argument is now "const void*".
grib_handle_new_from_partial_message: The "data" argument is now "const void*".
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 name | Comments |
|---|---|
| grib_cmp | Superseded by grib_compare |
| grib_debug | Superseded by "grib_dump -D" |
| grib_convert | Superseded by grib_filter |
| grib_distance | This tool was experimental |
| grib_error | This tool was experimental |
| grib_keys | This tool was experimental |
| grib_add | This tool was experimental |
| grib_corruption_check | This tool was experimental |
| points | This tool was experimental |
| grib_packing | This tool was experimental |
| grib_moments | This tool was experimental |
| big2gribex | This tool was experimental |
| grib_list_keys | This tool was experimental |
| grib_repair | This tool was experimental |
| grib_to_json | This tool was experimental |
| gg_sub_area_check | This 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.