g2_getfld.c File Reference

Return all the metadata, template values, Bit-map (if applicable), and the unpacked data for a given data field. More...

#include <stdio.h>
#include <stdlib.h>
#include "grib2.h"

Go to the source code of this file.

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. More...
g2int	g2_unpack1 (unsigned char *, g2int *, g2int **, g2int *)
	This subroutine unpacks Section 1 - Identification Section as defined in GRIB Edition 2. More...
g2int	g2_unpack2 (unsigned char *, g2int *, g2int *, unsigned char **)
	This subroutine unpacks Section 2 (Local Use Section) as defined in GRIB Edition 2. More...
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. More...
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. More...
g2int	g2_unpack5 (unsigned char *, g2int *, g2int *, g2int *, g2int **, g2int *)
	This subroutine unpacks Section 5 (Data Representation Section) as defined in GRIB Edition 2. More...
g2int	g2_unpack6 (unsigned char *, g2int *, g2int, g2int *, g2int **)
	This subroutine unpacks Section 6 (Bit-Map Section) as defined in GRIB Edition 2. More...
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. More...

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

g2_getfld()

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

Date	Programmer	Comments
2002-10-28	Gilbert	Initial
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. The first field is number 1, Fortran style.
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.

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 102 of file g2_getfld.c.

References gribfield::bmap, gribfield::coord_list, gribfield::discipline, gribfield::expanded, gribfield::fld, g2_unpack1(), g2_unpack2(), g2_unpack3(), g2_unpack4(), g2_unpack5(), g2_unpack6(), g2_unpack7(), gbit(), gribfield::griddef, gribfield::ibmap, gribfield::idrtlen, gribfield::idrtmpl, gribfield::idrtnum, gribfield::idsect, gribfield::idsectlen, gribfield::ifldnum, gribfield::igdtlen, gribfield::igdtmpl, gribfield::igdtnum, gribfield::interp_opt, gribfield::ipdtlen, gribfield::ipdtmpl, gribfield::ipdtnum, gribfield::list_opt, gribfield::local, gribfield::locallen, gribfield::ndpts, gribfield::ngrdpts, gribfield::num_coord, gribfield::num_opt, gribfield::numoct_opt, gribfield::unpacked, and gribfield::version.

g2_unpack1()

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	Pointer that gets an array which contians the information read from Section 1, the Identification section. This array is allocated by this function, and must be freed by caller (using g2_free()). ids[0] Identification of originating Centre (see Table 0). ids[1] Identification of originating Sub-centre (see Table C). ids[2] GRIB Master Tables Version Number (see Table 1.0). ids[3] GRIB Local Tables Version Number (see Table 1.1). ids[4] Significance of Reference Time (see 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 Table 1.3). ids[12] Type of processed data (see 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 55 of file g2_unpack1.c.

References gbit().

Referenced by g2_getfld().

g2_unpack2()

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

Date	Programmer	Comments
2002-10-31	Gilbert	Initial
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 37 of file g2_unpack2.c.

References gbit().

Referenced by g2_getfld().

g2_unpack3()

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

Date	Programmer	Comments
2002-10-31	Gilbert	Initial
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 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. (See Table 3.11) igds[4] Grid Definition Template Number (see Table 3.1).
igdstmpl	Pointer to integer array containing the data values for the Grid Definition Template specified by igds[4].
mapgridlen	Number of elements in igdstmpl. i.e. number of entries in Grid Defintion Template specified by 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).
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 message contains an undefined Grid Definition Template.
• 6 memory allocation error

Author

Stephen Gilbert

Date

2002-10-31

Definition at line 57 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(), getdim(), and getpoly().

g2_unpack4()

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

Date	Programmer	Comments
2002-10-31	Gilbert	Initial
2009-01-14	Vuong	Changed structure name template to gtemplate

Parameters

cgrib	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 Table 4.0).
ipdstmpl	Pointer that gets an integer array containing the data values for the Product Definition Template specified by ipdsnum.
mappdslen	Number of elements in ipdstmpl - i.e. number of entries in Product Defintion Template specified by ipdsnum.
coordlist	Pointer that gets an array containing floating point values intended to document the vertical discretisation associated to model data on hybrid coordinate vertical levels.
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 45 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().

g2_unpack5()

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

Date	Programmer	Comments
2002-10-31	Gilbert	Initial
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 42 of file g2_unpack5.c.

References gtemplate::ext, extdrstemplate(), gtemplate::extlen, gbit(), getdrstemplate(), gtemplate::map, gtemplate::maplen, and gtemplate::needext.

Referenced by g2_getfld().

g2_unpack6()

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().

g2_unpack7()

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

Date	Programmer	Comments
2002-10-31	Gilbert	Initial
2002-12-20	Gilbert	Added GDT info to arguments and added 5.51 processing.
2003-08-29	Gilbert	New templates using PNG and JPEG2000 algorithms/templates.
2004-11-29	Gilbert	JPEG2000 now allowed to use WMO Template 5.40 PNG allowed to use 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 65 of file g2_unpack7.c.

References comunpack(), gbit(), jpcunpack(), pngunpack(), rdieee(), simunpack(), and specunpack().

Referenced by g2_getfld().