--- name: "g2_getfld.c" section: "3" platform: "linux" package: "libg2c-dev" version: "2.1.0-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/g2_getfld.c" --- # g2\_getfld.c(3) Return all the metadata, template values, Bit-map (if applicable), and the unpacked data for a given data field. ## 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 'grib2_int.h'`\ `#include `\ `#include `\ ### Functions **g2int** **g2\_getfld** (unsigned char \*cgrib, **g2int** ifldnum, **g2int** unpack, **g2int** expand, **gribfield** \*\*gfld)\ Return all the metadata, template values, bit-map (if applicable), and the unpacked data for a data field. ## 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) Return all the metadata, template values, bit-map (if applicable), and the unpacked data for a 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** - • **G2\_NO\_ERROR** no error - • **G2\_GETFLD\_NO\_GRIB** Beginning characters 'GRIB' not found. - • **G2\_GETFLD\_GRIB\_VERSION** GRIB message is not Edition 2. - • **G2\_GETFLD\_INVAL** The data field request number was not positive. - • **G2\_GETFLD\_WRONG\_END** End string '7777' found, but not where expected. - • **G2\_GETFLD\_WRONG\_NFLDS** GRIB message did not contain the requested number of data fields. - • **G2\_GETFLD\_BAD\_END** End string '7777' not found at end of message. - • **G2\_GETFLD\_INVAL\_SEC** Unrecognized Section encountered. - • **G2\_GETFLD\_NO\_DRT** Data Representation Template 5.NN not yet implemented. - • **G2\_GETFLD\_BAD\_SEC1** Error unpacking Section 1. - • **G2\_GETFLD\_BAD\_SEC2** Error unpacking Section 2. - • **G2\_GETFLD\_BAD\_SEC3** Error unpacking Section 3. - • **G2\_GETFLD\_BAD\_SEC4** Error unpacking Section 4. - • **G2\_GETFLD\_BAD\_SEC5** Error unpacking Section 5. - • **G2\_GETFLD\_BAD\_SEC6** Error unpacking Section 6. - • **G2\_GETFLD\_BAD\_SEC7** Error unpacking Section 7. - • **G2\_GETFLD\_NO\_BITMAP** 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 **93** of file **g2\_getfld.c**. References **gribfield::bmap**, **gribfield::coord\_list**, **gribfield::discipline**, **gribfield::expanded**, **gribfield::fld**, **g2\_free()**, **G2\_GETFLD\_BAD\_END**, **G2\_GETFLD\_BAD\_SEC1**, **G2\_GETFLD\_BAD\_SEC2**, **G2\_GETFLD\_BAD\_SEC3**, **G2\_GETFLD\_BAD\_SEC4**, **G2\_GETFLD\_BAD\_SEC5**, **G2\_GETFLD\_BAD\_SEC6**, **G2\_GETFLD\_BAD\_SEC7**, **G2\_GETFLD\_GRIB\_VERSION**, **G2\_GETFLD\_INVAL**, **G2\_GETFLD\_INVAL\_SEC**, **G2\_GETFLD\_NO\_BITMAP**, **G2\_GETFLD\_NO\_GRIB**, **G2\_GETFLD\_WRONG\_END**, **G2\_GETFLD\_WRONG\_NFLDS**, **G2\_NO\_ERROR**, **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**. ## Author Generated automatically by Doxygen for NCEPLIBS-g2c from the source code.