plucky (3) g2_getfld.c.3.gz

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 <stdio.h>
       #include <stdlib.h>

   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.