GRIB Data Format

GRIB Data Format used for the COSMO-Model System

Last updated: February 2013

GRIB Software

To code / decode the meteorological data to GRIB, special software is needed. While a DWD-written software, the GRIB1-library is used to work with GRIB 1 data, the new application programmers interface grib_api from ECMWF is used for dealing with GRIB 2. But grib_api can also deal with GRIB 1 data. The approach, how data is coded to / decoded from GRIB messages is rather different in these software packages. While the GRIB1-library provides interfaces to code / decode the full GRIB message in one step, the grib_api uses the so-called key/value approach, where the single meta data could be set. Both approaches will be discussed shortly:

ECMWF grib_api

In contrast to the DWD GRIB1 library, the grib_api from ECMWF does not provide routines to code or decode full GRIB messages in one step. Instead, there are interface routines to access the single meta data of GRIB edition 1 and eddition 2 messages. In addition to these interface routines (available for Fortran and for C), there are some command line tools to provide an easy way to check and manipulate GRIB data from the shell.

To access and modify the coded information, a set of GRIB keys are defined. Using the keys, all information contained in GRIB messages can be retrieved through alphanumeric names. All the key names are built from the official WMO documentation on the GRIB edition 1 and 2 coding standard, removing the spaces in the key description and capitalizing the initials.

Example for a key name

In GRIB messages the originating centre can be specified as a meta date. In edition 1 it is contained in Section 1, the product definition section, in edition 2 it is also contained in Section 1, but here this is the identification section. The WMO Manual on Codes specifies:


 
   
     Edition  
     Octet No.
     Contents
   
   
     1
     6
     Identification of originating / generating centre (allocated by originating centre)
   
   
     2
     6-7
     Identification of originating / generating centre (see Common Code table C-11)

Edition	Octet No.	Contents
1	6	Identification of originating / generating centre (allocated by originating centre)
2	6-7	Identification of originating / generating centre (see Common Code table C-11)

grib_api transforms this definition to

identificationOfOriginatingGeneratingCentre

Because some of the key names are getting really long, also short names (or aliases) are provided. The above key can also be accessed by the short name centre This key also is an example of an edition independent key, because it is available in edition 1 and in edition 2.

More information on keys and on grib_api in general can be found on an ECMWF wiki page

The grib_api interface

The following table lists the basic grib_api routines from the Fortran interface, with which the basic manipulation of GRIB data can be done:

Group	Interface Routine	Purpose
Basic routines to modify contents of GRIB messages	`grib_get`	Get the value for a key from a grib message
Basic routines to modify contents of GRIB messages	`grib_set`	Set the value for a key in a grib message
Routines for file handling	`grib_open_file`	Open a file
Routines for file handling	`grib_close_file`	Close a file
Routines for reading and manipulating GRIB messages	`grib_read_from_file`	Reads a message in a buffer array from the file opened with `grib_open_file`. After this routine, the message is in the buffer, but cannot be accessed for reading or manipulating data.
	`grib_new_from_message`	Creates a new message in memory from an `INTEGER` or `CHARACTER` array containing the coded message (after e.g. grib_read_from_file). This routine creates a grib_handle and data of this message can now be accessed through this handle. It will be available until `grib_release` is called.
	`grib_new_from_file`	Loads a new message into memory and builds the corresponding grib_handle in one step. This handle will be available until `grib_release` is called.
	`grib_new_from_sample`	Creates a new valid grib_handle from a sample contained in the samples directory pointed by the environment variable `GRIB_SAMPLES_PATH`
	`grib_clone`	Creates a copy of a message and returns a new grib_handle
	`grib_copy_message`	Copies a coded message into an integer array
	`grib_release`	Frees the memory for the message referred as the grib_handle
Routines for writing GRIB messages	`grib_write_bytes`	Writes `nbytes` bytes from the buffer in a file opened with `grib_open_file`.

Using grib_api in a program for reading GRIB messages

For reading and decoding GRIB messages, the following steps have to be performed.

Open a file with grib_open_file.
Read a GRIB message and build a grib_handle for that message.
- In a sequential program this can be done with grib_new_from_file
- In a parallel program this task can be split in grib_read_from_file (which will be performed on Task A) and in grib_new_from_message (which might be performed on another Task B, which gets the message by parallel program communication).
Access the necessary data through a sequence of grib_get calls.
Release the grib_handle again by calling grib_release
Close the file with grib_close_file.

When starting to work with grib_api, one could think that coding and writing GRIB messages might be hard, if all the meta data / keys of a message must be set with grib_set calls. But grib_api provides methods to avoid this. The idea is to provide special sample messages, where most of the meta data are already set. Only few meta data have to be set then for special messages / products.

Using grib_api in a program for writing GRIB messages

In the following we briefly sketch, how GRIB messages are written using grib_api:

Get a sample GRIB message with grib_new_from_sample.
In this sample message, most of the meta data can already be preset for special products, e.g. the originating centre or most of the grid description section.
Clone the grib message to get a new grib_handle by calling grib_clone.
Set all meta data that will be the same for all messages that are now written.
Open a file with grib_open_file.
Loop over all products to be written:
- Set all other meta data that are special for that product
- Set the values for this product
- Copy the message to a message buffer by calling grib_copy_message
- Write the message buffer to the file by calling grib_write_bytes
Close the file with grib_close_file.

Back