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 '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.