NCEPLIBS-g2  3.4.5
Functions/Subroutines
getgb2.f File Reference

This subroutine find and unpack a grib file. More...

Go to the source code of this file.

Functions/Subroutines

subroutine getgb2 (LUGB, LUGI, J, JDISC, JIDS, JPDTN, JPDT, JGDTN, JGDT, UNPACK, K, GFLD, IRET)
 This subroutine find and unpack a grib message. More...
 

Detailed Description

This subroutine find and unpack a grib file.

Author
Mark Iredell
Date
1994-04-01

Definition in file getgb2.f.

Function/Subroutine Documentation

◆ getgb2()

subroutine getgb2 ( integer, intent(in)  LUGB,
integer, intent(in)  LUGI,
integer, intent(in)  J,
integer, intent(in)  JDISC,
integer, dimension(*)  JIDS,
integer, intent(in)  JPDTN,
integer, dimension(*)  JPDT,
integer, intent(in)  JGDTN,
integer, dimension(*)  JGDT,
logical, intent(in)  UNPACK,
integer, intent(out)  K,
type(gribfield), intent(out)  GFLD,
integer, intent(out)  IRET 
)

This subroutine find and unpack a grib message.

It reads a grib index file (or optionally the grib file itself) to get the index buffer (i.e. table of contents) for the grib file. find in the index buffer a reference to the grib field requested. the grib field request specifies the number of fields to skip and the unpacked identification section, grid definition template and product defintion section parameters. (a requested parameter of -9999 means to allow any value of this parameter to be found.) if the requested grib field is found, then it is read from the grib file and unpacked. Its number is returned along with the associated unpacked parameters. the bitmap (if any), and the data values are unpacked only if argument "unpack" is set to true. if the grib field is not found, then the return code will be nonzero.

The decoded information for the selected GRIB field is returned in a derived type variable, gfld. Gfld is of type gribfield, which is defined in module grib_mod, so users of this routine will need to include the line "USE GRIB_MOD" in their calling routine. Each component of the gribfield type is described in the OUTPUT ARGUMENT LIST section below.

PROGRAM HISTORY LOG:

  • 1994-04-01 Mark Iredell
  • 1995-10-31 Mark Iredell modularized portions of code into subprograms and allowed for unspecified index file
  • 2002-01-11 Stephen Gilbert modified from getgb and getgbm to work with grib2
  • 2015-11-10 Boi Vuong modified doc block for gfld%ngrdpts and gfld%ndpts
Parameters
[in]LUGBinteger unit of the unblocked grib data file. file must be opened with baopen or baopenr before calling this routine.
[in]LUGIinteger unit of the unblocked grib index file. if nonzero, file must be opened with baopen baopenr before calling this routine.
  • >0 read index from index file lugi, if index doesn"t already exist.
  • =0 to get index buffer from the grib file, if index doesn"t already exist.
  • <0 force reread of index from index file abs(lugi).
  • =lugb force regeneration of index from grib2 file lugb.
[in]Jinteger number of fields to skip (=0 to search from beginning)
[in]JDISCgrib2 discipline number of requested field (if = -1, accept any discipline see code table 0.0)
  • 0 meteorological products
  • 1 hydrological products
  • 2 land surface products
  • 3 space products
  • 10 oceanographic products
[in]JIDSinteger array of values in the identification section (=-9999 for wildcard)
  • JIDS(1) identification of originating centre (see common code table c-1)
  • JIDS(2) identification of originating sub-centre
  • JIDS(3) grib master tables version number (see code table 1.0) 0 experimental;1 initial operational version number.
  • JIDS(4) grib local tables version number (see code table 1.1) 0 local tables not used; 1-254 number of local tables version used.
  • JIDS(5) significance of reference time (code table 1.2) 0 analysis; 1 start of forecast; 2 verifying time of forecast; 3 observation time
  • JIDS(6) year (4 digits)
  • JIDS(7) month
  • JIDS(8) day
  • JIDS(9) hour
  • JIDS(10) minute
  • JIDS(11) second
  • JIDS(12) production status of processed data (see code table 1.3) 0 operational products; 1 operational test products; 2 research products; 3 re-analysis products.
  • JIDS(13) 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.
[in]JPDTNinteger product definition template number (n) (if = -1, don't bother matching pdt - accept any)
[in]JPDTinteger array of values defining the product definition template 4.n of the field for which to search (=-9999 for wildcard)
[in]JGDTNinteger grid definition template number (m) (if = -1, don't bother matching gdt - accept any )
[in]JGDTinteger array of values defining the grid definition template 3.m of the field for which to search (=-9999 for wildcard)
[in]UNPACKlogical value indicating whether to unpack bitmap/data
  • .TRUE. unpack bitmap and data values
  • .FALSE. do not unpack bitmap and data values
[out]Kinteger field number unpacked
[out]GFLDderived type gribfield (defined in module grib_mod) (NOTE: See Remarks Section)
  • 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 actually a pointer to an array that holds the data.
  • gfld%idsect(1) Identification of originating Centre (see Common Code Table C-1) 7 US National Weather Service
  • gfld%idsect(2) Identification of originating Sub-centre
  • gfld%idsect(3) GRIB Master Tables Version Number (see Code Table 1.0) 0 Experimental; 1 Initial operational version number
  • gfld%idsect(4) 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(5) Significance of Reference Time (Code Table 1.2) 0 Analysis; 1 Start of forecast; 2 Verifying time of forecast; 3 Observation time.
  • gfld%idsect(6) Year (4 digits)
  • gfld%idsect(7) Month
  • gfld%idsect(8) Day
  • gfld%idsect(9) Hour
  • gfld%idsect(10) Minute
  • gfld%idsect(11) Second
  • gfld%idsect(12) 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(13) 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. Note that the number of actual data values returned from getgb2 (in gfld%ndpts) may be less than this value if a logical bitmap is in use with grid points that are being masked out.
  • 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 actually 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 actually 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 actually 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 actually 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. Note that this number may be different from the value of
  • gfld%ngrdpts if a logical bitmap is in use with grid points that are being masked out.
  • 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 actually 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 Logical*1 array containing decoded bitmap, if ibmap=0 or ibap=254. Otherwise nullified. This element is actually a pointer to an array that holds the data.
  • gfld%fld Array of gfld%ndpts unpacked data points. This element is actually a pointer to an array that holds the data.
[out]IRETinteger return code
  • 0 all ok
  • 96 error reading index
  • 97 error reading grib file
  • 99 request not found
  • other gf_getfld grib2 unpacker return code
Note
specify an index file if feasible to increase speed. do not engage the same logical unit from more than one processor. Note that derived type gribfield contains pointers to many arrays of data. The memory for these arrays is allocated when the values in the arrays are set, to help minimize problems with array overloading. Because of this users are encouraged to free up this memory, when it is no longer needed, by an explicit call to subroutine gf_free.
Author
Mark Iredell
Date
1994-04-01

Definition at line 227 of file getgb2.f.