g2_getfld.c(3)

NCEPLIBS-g2c

g2_getfld.c(3)

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.

Tue May 3 2022

Version 1.6.4

Source file:	g2_unpack4.3.en.gz (from libg2c-dev )
Source last updated:	2022-05-03T11:15:51Z
Converted to HTML:	2024-10-21T18:02:12Z

NAME¶

SYNOPSIS¶

Functions¶

Detailed Description¶

Function Documentation¶

g2int g2_getfld (unsigned char * cgrib, g2int ifldnum, g2int unpack, g2int expand, gribfield ** gfld)¶

g2int g2_unpack1 (unsigned char * cgrib, g2int * iofst, g2int ** ids, g2int * idslen)¶

g2int g2_unpack2 (unsigned char * cgrib, g2int * iofst, g2int * lencsec2, unsigned char ** csec2)¶

g2int g2_unpack3 (unsigned char * cgrib, g2int * iofst, g2int ** igds, g2int ** igdstmpl, g2int * mapgridlen, g2int ** ideflist, g2int * idefnum)¶

g2int g2_unpack4 (unsigned char * cgrib, g2int * iofst, g2int * ipdsnum, g2int ** ipdstmpl, g2int * mappdslen, g2float ** coordlist, g2int * numcoord)¶

g2int g2_unpack5 (unsigned char * cgrib, g2int * iofst, g2int * ndpts, g2int * idrsnum, g2int ** idrstmpl, g2int * mapdrslen)¶

g2int g2_unpack6 (unsigned char * cgrib, g2int * iofst, g2int ngpts, g2int * ibmap, g2int ** bmap)¶

g2int g2_unpack7 (unsigned char * cgrib, g2int * iofst, g2int igdsnum, g2int * igdstmpl, g2int idrsnum, g2int * idrstmpl, g2int ndpts, g2float ** fld)¶

Author¶

g2int g2_unpack3 (unsigned char * cgrib, g2int * iofst, g2int igds, g2int igdstmpl, g2int * mapgridlen, g2int ** ideflist, g2int * idefnum)¶