Local configuration - ecCodes BUFR FAQ

Local configuration

Step-by-step guide

Users can define their own local BUFR tables to adapt ecCodes to their own needs e.g. to use a local descriptor.

1. The local BUFR tables are stored in the following definitions directories:

      definitions/bufr/tables/[masterTableNumber]/local/[localTablesVersionNumber]/[bufrHeaderCentre]/[bufrHeaderSubCentre]

   e.g. definitions/bufr/tables/0/local/101/98/0/   (98 is for ecmwf)

2. The environment variable ECCODES_DEFINITION_PATH can be set to locate local BUFR tables. This is similar to how the PATH environment variable works in Unix, it is a list of directories separated by colons (":"):

      export ECCODES_DEFINITION_PATH=/path/to/local/defs:/path/to/default/defs

3. The library searches for each required definition file first in /path/to/local/defs and then in /path/to/default/defs.  If the file is found in /path/to/local/defs then it used by the decoding engine.

4. In order to find out where the default definitions are stored, use the tool codes_info. E.g.

   % codes_info
   ecCodes Version 2.2.0
   
   Default definition files path is used: /usr/local/apps/eccodes/2.2.0/share/eccodes/definitions
   Definition files path can be changed by setting ECCODES_DEFINITION_PATH environment variable
   
   Default SAMPLES path is used: /usr/local/apps/eccodes/2.2.0/share/eccodes/samples
   SAMPLES path can be changed by setting ECCODES_SAMPLES_PATH environment variable

   On this platform, ecCodes is installed in /usr/local/apps/eccodes/2.2.0 and the definitions are in /usr/local/apps/eccodes/2.2.0/share/eccodes/definitions.

5. 
   

   To get just the definition path above, you can run codes_info with the "-d" option:

   % def=`codes_info -d`
   % echo $def
   /usr/local/apps/eccodes/2.2.0/share/eccodes/definitions

   This is useful for embedding in Shell scripts.

6. 
   

   If you have a BUFR message and want to know which files/directories are being accessed by ecCodes during the decoding, you can use the Unix "strace" command:

   % strace -o trace.txt bufr_dump my.bufr

   This will create a new file called "trace.txt" which records the system calls made. Search this for strings like "definitions/bufr/tables" and you can see which files ecCodes is trying to access and open.

7. 
   

   Worked Example

   Download an example here.
   This tarball contains a BUFR file which uses local descriptors as well as the definition files needed to decode the tables.

   
   

   1. Try decoding the BUFR file "ikco_217.local.bufr" using bufr_dump. This file uses a local table version (localTablesVersionNumber=66).
      Decoding should fail as ecCodes does not know about these descriptors.
   2. Run the codes_info tool to find the location of the default definitions.
   3. Now set ECCODES_DEFINITION_PATH to include the provided "mydefs" directory.
      E.g.
      export ECCODES_DEFINITION_PATH=`pwd`/mydefs:`codes_info -d`
   4. Now see if ecCodes can decode the BUFR file.
   5. Search the output of bufr_dump for the overridden unit "MyOwnUnits".
      This was added as an example of a centre defining its own parameter attributes

   

Related articles