Provided by: libg2c-dev_1.6.4-3_amd64 
NAME
g2_getfld.c - Return all the metadata, template values, Bit-map (if applicable), and the
unpacked data for a given data field.
SYNOPSIS
#include <stdio.h>
#include <stdlib.h>
#include 'grib2.h'
Functions
g2int g2_getfld (unsigned char *cgrib, g2int ifldnum, g2int unpack, g2int expand,
gribfield **gfld)
This subroutine returns all the metadata, template values, Bit-map (if applicable),
and the unpacked data for a given data field.
g2int g2_unpack1 (unsigned char *, g2int *, g2int **, g2int *)
This subroutine unpacks Section 1 (Identification Section) as defined in GRIB Edition
2.
g2int g2_unpack2 (unsigned char *, g2int *, g2int *, unsigned char **)
This subroutine unpacks Section 2 (Local Use Section) as defined in GRIB Edition 2.
g2int g2_unpack3 (unsigned char *, g2int *, g2int **, g2int **, g2int *, g2int **, g2int
*)
This routine unpacks Section 3 (Grid Definition Section) as defined in GRIB Edition 2.
g2int g2_unpack4 (unsigned char *, g2int *, g2int *, g2int **, g2int *, g2float **, g2int
*)
This subroutine unpacks Section 4 (Product Definition Section) as defined in GRIB
Edition 2.
g2int g2_unpack5 (unsigned char *, g2int *, g2int *, g2int *, g2int **, g2int *)
This subroutine unpacks Section 5 (Data Representation Section) as defined in GRIB
Edition 2.
g2int g2_unpack6 (unsigned char *, g2int *, g2int, g2int *, g2int **)
This subroutine unpacks Section 6 (Bit-Map Section) as defined in GRIB Edition 2.
g2int g2_unpack7 (unsigned char *, g2int *, g2int, g2int *, g2int, g2int *, g2int, g2float
**)
This subroutine unpacks Section 7 (Data Section) as defined in GRIB Edition 2.
Detailed Description
Return all the metadata, template values, Bit-map (if applicable), and the unpacked data
for a given data field.
Author
Stephen Gilbert
Date
2002-10-28
Definition in file g2_getfld.c.
Function Documentation
g2int g2_getfld (unsigned char * cgrib, g2int ifldnum, g2int unpack, g2int expand, gribfield
** gfld)
This subroutine returns all the metadata, template values, Bit-map (if applicable), and
the unpacked data for a given data field. All of the information returned is stored in a
gribfield structure, which is defined in file grib2.h. Users of this routine will need to
include grib2.h in their source code that calls this routine.
Since there can be multiple data fields packed into a GRIB2 message, the calling routine
indicates which field is being requested with the ifldnum argument.
PROGRAM HISTORY LOG:
• 2002-10-28 Gilbert
• 2013-08-08 Vuong Free up memory in array igds - free(igds)
Parameters
cgrib Character pointer to the GRIB2 message.
ifldnum Specifies which field in the GRIB2 message to return.
unpack Boolean value indicating whether to unpack bitmap/data field.
• 1 unpack bitmap (if present) and data values.
• 0 do not unpack bitmap and data values.
expand Boolean value indicating whether the data points should be expanded to the
correspond grid, if a bit-map is present. This argument is ignored if unpack == 0 OR
if the returned field does not contain a bit-map.
• 1 if possible, expand data field to grid, inserting zero values at gridpoints that
are bitmapped out. (SEE REMARKS2)
• 0 do not expand data field, leaving it an array of consecutive data points for each
'1' in the bitmap.
gfld pointer to structure gribfield containing all decoded data for the data field.
gfld->version = GRIB edition number ( currently 2 )
gfld->discipline = Message Discipline ( see Code Table 0.0 )
gfld->idsect = Contains the entries in the Identification
Section ( Section 1 )
This element is a pointer to an array
that holds the data.
gfld->idsect[0] = Identification of originating Centre
( see Common Code Table C-1 )
7 - US National Weather Service
gfld->idsect[1] = Identification of originating Sub-centre
gfld->idsect[2] = GRIB Master Tables Version Number
( see Code Table 1.0 )
0 - Experimental
1 - Initial operational version number
gfld->idsect[3] = GRIB Local Tables Version Number
( see Code Table 1.1 )
0 - Local tables not used
1-254 - Number of local tables version used
gfld->idsect[4] = Significance of Reference Time (Code Table 1.2)
0 - Analysis
1 - Start of forecast
2 - Verifying time of forecast
3 - Observation time
gfld->idsect[5] = Year ( 4 digits )
gfld->idsect[6] = Month
gfld->idsect[7) = Day
gfld->idsect[8] = Hour
gfld->idsect[9] = Minute
gfld->idsect[10] = Second
gfld->idsect[11] = Production status of processed data
( see Code Table 1.3 )
0 - Operational products
1 - Operational test products
2 - Research products
3 - Re-analysis products
gfld->idsect[12] = Type of processed data ( see Code Table 1.4 )
0 - Analysis products
1 - Forecast products
2 - Analysis and forecast products
3 - Control forecast products
4 - Perturbed forecast products
5 - Control and perturbed forecast products
6 - Processed satellite observations
7 - Processed radar observations
gfld->idsectlen = Number of elements in gfld->idsect[].
gfld->local = Pointer to character array containing contents
of Local Section 2, if included
gfld->locallen = length of array gfld->local[]
gfld->ifldnum = field number within GRIB message
gfld->griddef = Source of grid definition (see Code Table 3.0)
0 - Specified in Code table 3.1
1 - Predetermined grid Defined by originating centre
gfld->ngrdpts = Number of grid points in the defined grid.
gfld->numoct_opt = Number of octets needed for each
additional grid points definition.
Used to define number of
points in each row ( or column ) for
non-regular grids.
= 0, if using regular grid.
gfld->interp_opt = Interpretation of list for optional points
definition. (Code Table 3.11)
gfld->igdtnum = Grid Definition Template Number (Code Table 3.1)
gfld->igdtmpl = Contains the data values for the specified Grid
Definition Template ( NN=gfld->igdtnum ). Each
element of this integer array contains an entry (in
the order specified) of Grid Defintion Template 3.NN
This element is a pointer to an array
that holds the data.
gfld->igdtlen = Number of elements in gfld->igdtmpl[]. i.e. number of
entries in Grid Defintion Template 3.NN
( NN=gfld->igdtnum ).
gfld->list_opt = (Used if gfld->numoct_opt .ne. 0) This array
contains the number of grid points contained in
each row ( or column ). (part of Section 3)
This element is a pointer to an array
that holds the data. This pointer is nullified
if gfld->numoct_opt=0.
gfld->num_opt = (Used if gfld->numoct_opt .ne. 0)
The number of entries
in array ideflist. i.e. number of rows ( or columns )
for which optional grid points are defined. This value
is set to zero, if gfld->numoct_opt=0.
gfdl->ipdtnum = Product Definition Template Number(see Code Table 4.0)
gfld->ipdtmpl = Contains the data values for the specified Product
Definition Template ( N=gfdl->ipdtnum ). Each element
of this integer array contains an entry (in the
order specified) of Product Defintion Template 4.N.
This element is a pointer to an array
that holds the data.
gfld->ipdtlen = Number of elements in gfld->ipdtmpl[]. i.e. number of
entries in Product Defintion Template 4.N
( N=gfdl->ipdtnum ).
gfld->coord_list = Real array containing floating point values
intended to document the vertical discretisation
associated to model data on hybrid coordinate
vertical levels. (part of Section 4)
This element is a pointer to an array
that holds the data.
gfld->num_coord = number of values in array gfld->coord_list[].
gfld->ndpts = Number of data points unpacked and returned.
gfld->idrtnum = Data Representation Template Number
( see Code Table 5.0)
gfld->idrtmpl = Contains the data values for the specified Data
Representation Template ( N=gfld->idrtnum ). Each
element of this integer array contains an entry
(in the order specified) of Product Defintion
Template 5.N.
This element is a pointer to an array
that holds the data.
gfld->idrtlen = Number of elements in gfld->idrtmpl[]. i.e. number
of entries in Data Representation Template 5.N
( N=gfld->idrtnum ).
gfld->unpacked = logical value indicating whether the bitmap and
data values were unpacked. If false,
gfld->bmap and gfld->fld pointers are nullified.
gfld->expanded = Logical value indicating whether the data field
was expanded to the grid in the case where a
bit-map is present. If true, the data points in
gfld->fld match the grid points and zeros were
inserted at grid points where data was bit-mapped
out. If false, the data values in gfld->fld were
not expanded to the grid and are just a consecutive
array of data points corresponding to each value of
'1' in gfld->bmap.
gfld->ibmap = Bitmap indicator ( see Code Table 6.0 )
0 = bitmap applies and is included in Section 6.
1-253 = Predefined bitmap applies
254 = Previously defined bitmap applies to this field
255 = Bit map does not apply to this product.
gfld->bmap = integer array containing decoded bitmap,
if gfld->ibmap=0 or gfld->ibap=254. Otherwise nullified
This element is a pointer to an array
that holds the data.
gfld->fld = Array of gfld->ndpts unpacked data points.
This element is a pointer to an array
that holds the data.
Returns
• 0 no error
• 1 Beginning characters 'GRIB' not found.
• 2 GRIB message is not Edition 2.
• 3 The data field request number was not positive.
• 4 End string '7777' found, but not where expected.
• 6 GRIB message did not contain the requested number of data fields.
• 7 End string '7777' not found at end of message.
• 8 Unrecognized Section encountered.
• 9 Data Representation Template 5.NN not yet implemented.
• 15 Error unpacking Section 1.
• 16 Error unpacking Section 2.
• 10 Error unpacking Section 3.
• 11 Error unpacking Section 4.
• 12 Error unpacking Section 5.
• 13 Error unpacking Section 6.
• 14 Error unpacking Section 7.
• 17 Previous bitmap specified, yet none exists.
Note
Struct gribfield is allocated by this routine and it also contains pointers to many
arrays of data that were allocated during decoding. Users are encouraged to free up
this memory, when it is no longer needed, by an explicit call to routine g2_free.
EXAMPLE:
#include "grib2.h"
gribfield *gfld;
ret=g2_getfld(cgrib,1,1,1,&gfld);
...
g2_free(gfld);
Routine g2_info can be used to first determine how many data fields exist in a given GRIB
message.
Note
It may not always be possible to expand a bit-mapped data field. If a pre-defined bit-
map is used and not included in the GRIB2 message itself, this routine would not have
the necessary information to expand the data. In this case, gfld->expanded would would
be set to 0 (false), regardless of the value of input argument expand.
Author
Stephen Gilbert
Date
2002-10-28
Definition at line 237 of file g2_getfld.c.
References g2_unpack1(), g2_unpack2(), g2_unpack3(), g2_unpack4(), g2_unpack5(),
g2_unpack6(), g2_unpack7(), and gbit().
g2int g2_unpack1 (unsigned char * cgrib, g2int * iofst, g2int ** ids, g2int * idslen)
This subroutine unpacks Section 1 (Identification Section) as defined in GRIB Edition 2.
Parameters
cgrib char array containing Section 1 of the GRIB2 message.
iofst Bit offset for the beginning of Section 1 in cgrib.
ids address of pointer to integer array containing information read from Section 1,
the Identification section.
• ids[0] Identification of originating Centre (see Common Code Table C-1).
• ids[1] Identification of originating Sub-centre.
• ids[2] GRIB Master Tables Version Number (see Code Table 1.0).
• ids[3] GRIB Local Tables Version Number (see Code Table 1.1).
• ids[4] Significance of Reference Time (Code Table 1.2)
• ids[5] Year ( 4 digits )
• ids[6] Month
• ids[7] Day
• ids[8] Hour
• ids[9] Minute
• ids[10] Second
• ids[11] Production status of processed data (see Code Table 1.3).
• ids[12] Type of processed data (see Code Table 1.4).
idslen Number of elements in ids.
Returns
• 0 no error
• 2 Array passed is not section 1
• 6 memory allocation error
Author
Stephen Gilbert
Date
2002-10-29
Definition at line 44 of file g2_unpack1.c.
References gbit().
Referenced by g2_getfld().
g2int g2_unpack2 (unsigned char * cgrib, g2int * iofst, g2int * lencsec2, unsigned char **
csec2)
This subroutine unpacks Section 2 (Local Use Section) as defined in GRIB Edition 2.
PROGRAM HISTORY LOG:
• 2002-10-31 Gilbert
• 2008-12-23 Wesley - Initialize lencsec2 Length of Local Use data
• 2010-08-05 Vuong - If section 2 has zero length, ierr=0
Parameters
cgrib char array containing Section 2 of the GRIB2 message.
iofst Bit offset for the beginning of Section 2 in cgrib. The modified version will be
returned.
lencsec2 Length (in octets) of Local Use data.
csec2 Pointer to a char array containing local use data.
Returns
• 0 no error
• 2 Array passed is not section 2
• 6 memory allocation error
Author
Stephen Gilbert
Date
2002-10-31
Definition at line 34 of file g2_unpack2.c.
References gbit().
Referenced by g2_getfld().
g2int g2_unpack3 (unsigned char * cgrib, g2int * iofst, g2int ** igds, g2int ** igdstmpl,
g2int * mapgridlen, g2int ** ideflist, g2int * idefnum)
This routine unpacks Section 3 (Grid Definition Section) as defined in GRIB Edition 2.
PROGRAM HISTORY LOG:
• 2002-10-31 Gilbert
• 2009-01-14 Vuong Changed structure name template to gtemplate
Parameters
cgrib Char array ontaining Section 3 of the GRIB2 message.
iofst Bit offset for the beginning of Section 3 in cgrib.
igds Contains information read from the appropriate GRIB Grid Definition Section 3 for
the field being returned.
• igds[0] Source of grid definition (see Code Table 3.0)
• igds[1] Number of grid points in the defined grid.
• igds[2] Number of octets needed for each additional grid points definition. Used to
define number of points in each row (or column) for non-regular grids. = 0, if using
regular grid.
• igds[3] Interpretation of list for optional points definition. (Code Table 3.11)
• igds[4] Grid Definition Template Number (Code Table 3.1).
igdstmpl - Pointer to integer array containing the data values for the specified Grid
Definition Template (NN=igds[4]). Each element of this integer array contains an entry
(in the order specified) of Grid Defintion Template 3.NN
mapgridlen- Number of elements in igdstmpl[]. i.e. number of entries in Grid Defintion
Template 3.NN (NN=igds[4]).
ideflist (Used if igds[2] .ne. 0) Pointer to integer array containing the number of
grid points contained in each row ( or column ). (part of Section 3).
idefnum (Used if igds[2] .ne. 0) The number of entries in array ideflist. i.e. number
of rows (or columns) for which optional grid points are defined.
Returns
• 0 no error
• 2 Not Section 3
• 5 'GRIB' message contains an undefined Grid Definition Template.
• 6 memory allocation error
Author
Stephen Gilbert
Date
2002-10-31
Definition at line 53 of file g2_unpack3.c.
References gtemplate::ext, extgridtemplate(), gtemplate::extlen, gbit(), gbits(),
getgridtemplate(), gtemplate::map, gtemplate::maplen, and gtemplate::needext.
Referenced by g2_getfld().
g2int g2_unpack4 (unsigned char * cgrib, g2int * iofst, g2int * ipdsnum, g2int ** ipdstmpl,
g2int * mappdslen, g2float ** coordlist, g2int * numcoord)
This subroutine unpacks Section 4 (Product Definition Section) as defined in GRIB Edition
2. PROGRAM HISTORY LOG:
• 2002-10-31 Gilbert
• 2009-01-14 Vuong Changed structure name template to gtemplate
Parameters
cgrib Char array containing Section 4 of the GRIB2 message.
iofst Bit offset of the beginning of Section 4 in cgrib. Returned with updated bit
offset.
ipdsnum Product Definition Template Number (see Code Table 4.0).
ipdstmpl Pointer to integer array containing the data values for the specified Product
Definition Template (N=ipdsnum). Each element of this integer array contains an entry
(in the order specified) of Product Defintion Template 4.N.
mappdslen Number of elements in ipdstmpl. i.e. number of entries in Product Defintion
Template 4.N (N=ipdsnum).
coordlist Pointer to real array containing floating point values intended to document
the vertical discretisation associated to model data on hybrid coordinate vertical
levels. (part of Section 4).
numcoord number of values in array coordlist.
Returns
• 0 no error
• 2 Not section 4
• 5 'GRIB' message contains an undefined Product Definition Template.
• 6 memory allocation error
Author
Stephen Gilbert
Date
2002-10-31
Definition at line 42 of file g2_unpack4.c.
References gtemplate::ext, gtemplate::extlen, extpdstemplate(), gbit(), gbits(),
getpdstemplate(), gtemplate::map, gtemplate::maplen, gtemplate::needext, and rdieee().
Referenced by g2_getfld().
g2int g2_unpack5 (unsigned char * cgrib, g2int * iofst, g2int * ndpts, g2int * idrsnum, g2int
** idrstmpl, g2int * mapdrslen)
This subroutine unpacks Section 5 (Data Representation Section) as defined in GRIB Edition
2. PROGRAM HISTORY LOG:
• 2002-10-31 Gilbert
• 2009-01-14 Vuong Changed structure name template to gtemplate
Parameters
cgrib char array containing Section 5 of the GRIB2 message.
iofst Bit offset for the beginning of Section 5 in cgrib. Returned with bit offset at
the end of Section 5.
ndpts Number of data points unpacked and returned.
idrsnum Data Representation Template Number (see Code Table 5.0).
idrstmpl Pointer to an integer array containing the data values for the specified Data
Representation Template (N=idrsnum). Each element of this integer array contains an
entry (in the order specified) of Data Representation Template 5.N.
mapdrslen- Number of elements in idrstmpl. i.e. number of entries in Data
Representation Template 5.N (N=idrsnum).
Returns
• 0 no error
• 2 Not Section 5
• 6 memory allocation error
• 7 'GRIB' message contains an undefined Data Representation Template.
Author
Stephen Gilbert
Date
2002-10-31
Definition at line 40 of file g2_unpack5.c.
References gtemplate::ext, extdrstemplate(), gtemplate::extlen, gbit(), getdrstemplate(),
gtemplate::map, gtemplate::maplen, and gtemplate::needext.
Referenced by g2_getfld().
g2int g2_unpack6 (unsigned char * cgrib, g2int * iofst, g2int ngpts, g2int * ibmap, g2int **
bmap)
This subroutine unpacks Section 6 (Bit-Map Section) as defined in GRIB Edition 2.
Parameters
cgrib char array containing Section 6 of the GRIB2 message.
iofst Bit offset of the beginning of Section 6 in cgrib.
ngpts Number of grid points specified in the bit-map
ibmap Bitmap indicator (see Code Table 6.0)
• 0 bitmap applies and is included in Section 6.
• 1-253 Predefined bitmap applies
• 254 Previously defined bitmap applies to this field
• 255 Bit map does not apply to this product.
bmap Pointer to an integer array containing decoded bitmap. (if ibmap=0)
Returns
• 0 no error
• 2 Not Section 6
• 4 Unrecognized pre-defined bit-map.
• 6 memory allocation error
Author
Stephen Gilbert
Date
2002-10-31
Definition at line 33 of file g2_unpack6.c.
References gbit(), and gbits().
Referenced by g2_getfld().
g2int g2_unpack7 (unsigned char * cgrib, g2int * iofst, g2int igdsnum, g2int * igdstmpl, g2int
idrsnum, g2int * idrstmpl, g2int ndpts, g2float ** fld)
This subroutine unpacks Section 7 (Data Section) as defined in GRIB Edition 2. PROGRAM
HISTORY LOG:
• 2002-10-31 Gilbert
• 2002-12-20 Gilbert - Added GDT info to arguments and added 5.51 processing.
• 2003-08-29 Gilbert - Added support for new templates using PNG and JPEG2000
algorithms/templates.
• 2004-11-29 Gilbert - JPEG2000 now allowed to use WMO Template no. 5.40 PNG now allowed
to use WMO Template no. 5.41
• 2004-12-16 Taylor - Added check on comunpack return code.
• 2008-12-23 Wesley - Initialize Number of data points unpacked
Parameters
cgrib char array containing Section 7 of the GRIB2 message
iofst Bit offset of the beginning of Section 7 in cgrib.
igdsnum Grid Definition Template Number (see Code Table 3.0) (Only used for DRS
Template 5.51)
igdstmpl Pointer to an integer array containing the data values for the specified Grid
Definition Template (N=igdsnum). Each element of this integer array contains an entry
(in the order specified) of Grid Definition Template 3.N. (Only used for DRS Template
5.51).
idrsnum Data Representation Template Number (see Code Table 5.0)
idrstmpl Pointer to an integer array containing the data values for the specified Data
Representation Template (N=idrsnum). Each element of this integer array contains an
entry (in the order specified) of Data Representation Template 5.N
ndpts Number of data points unpacked and returned.
fld Pointer to a float array containing the unpacked data field.
Returns
• 0 no error
• 2 Not section 7
• 4 Unrecognized Data Representation Template
• 5 need one of GDT 3.50 through 3.53 to decode DRT 5.51
• 6 memory allocation error
• 7 corrupt section 7.
Author
Stephen Gilbert
Date
2002-10-31
Definition at line 66 of file g2_unpack7.c.
References comunpack(), gbit(), jpcunpack(), pngunpack(), rdieee(), simunpack(), and
specunpack().
Referenced by g2_getfld().
Author
Generated automatically by Doxygen for NCEPLIBS-g2c from the source code.