| blob | 20cedddfe796c4045455495fded2dcb3f564f1d1 |
1 GRIB2 USERS GUIDE (FORTRAN 90)
3 Contents:
5 - Introduction
6 - GRIB2 Encoding Routines
7 - GRIB2 Decoding Routines
8 - Extracting GRIB2 Fields from a GRIB2 file
9 - GRIB2 Tables/Templates
10 - GRIB2 Routine Docblocks
12 ===============================================================================
14 Introduction
16 This document briefly describes the routines available for encoding/decoding
17 GRIB Edition 2 (GRIB2) messages. A basic familiarity with GRIB is assumed.
19 A GRIB Edition 2 message is a machine independent format for storing
20 one or more gridded data fields. Each GRIB2 message consists of the
21 following sections:
23 SECTION 0 - Indicator Section
24 SECTION 1 - Identification Section
25 SECTION 2 - (Local Use Section) - optional }
26 SECTION 3 - Grid Definition Section } }
27 SECTION 4 - Product Definition Section } } }(repeated)
28 SECTION 5 - Data Representation Section } }(repeated) }
29 SECTION 6 - Bit-map Section }(repeated) } }
30 SECTION 7 - Data Section } } }
31 SECTION 8 - End Section } } }
33 Sequences of GRIB sections 2 to 7, 3 to 7, or sections 4 to 7 may be repeated
34 within a single GRIB message. All sections within such repeated sequences
35 must be present and shall appear in the numerical order noted above.
36 Unrepeated sections remain in effect until redefined.
38 The above overview was taken from WMO's FM 92-XII GRIB description
39 of the experimental GRIB Edition 2 form.
41 ===============================================================================
43 GRIB2 Encoding Routines
45 Since a GRIB2 message can contain gridded fields for many parameters on
46 a number of different grids, several routines are used to encode a message.
47 This should give users more flexibility in how to organize data
48 within one or more GRIB2 messages.
50 To start a new GRIB2 message, call subroutine GRIBCREATE. GRIBCREATE
51 encodes Sections 0 and 1 at the beginning of the message. This routine
52 must be used to create each message.
54 Subroutine ADDLOCAL can be used to add a Local Use Section ( Section 2 ).
55 Note that section is optional and need not appear in a GRIB2 message.
57 Subroutine ADDGRID is used to encode a grid definition into Section 3.
58 This grid definition defines the geometry of the the data values in the
59 fields that follow it. ADDGRID can be called again to change the grid
60 definition describing subsequent data fields.
62 Each data field is added to the GRIB2 message using routine ADDFIELD,
63 which adds Sections 4, 5, 6, and 7 to the message.
65 After all desired data fields have been added to the GRIB2 message, a
66 call to routine GRIBEND is needed to add the final section 8 to the
67 message and to update the length of the message. A call to GRIBEND
68 is required for each GRIB2 message.
70 Please see the "GRIB2 Routine Docblocks" section below for subroutine
71 argument usage for the routines mentioned above.
73 ===============================================================================
75 GRIB2 Decoding Routines
77 Subroutine GB_INFO can be used to find out how many Local Use sections
78 and data fields are contained in a given GRIB2 message. In addition,
79 this routine also returns the number of octets of the largest Local Use
80 section in the message. This value can be used to ensure that the
81 output array of subroutine GETLOCAL ( described below ) is dimensioned
82 large enough.
84 Subroutine GETLOCAL will return the requested occurrence of Section 2
85 from a given GRIB2 message.
87 GF_GETFLD can be used to get all information pertaining to the nth
88 data field in the message. The subroutine returns all the unpacked values
89 for each Section and Template in a Fortran 90 derived type gribfield,
90 which is defined in module GRIB_MOD. An option exists that lets the
91 user decide if the subroutine should unpack the Bit-map ( if
92 applicable ) and the data values or just return the field description
93 information.
94 Note that derived type gribfield contains pointers to dynamically
95 allocated space that holds the contents of all arrays, and users are encouraged
96 to free up this memory, when it is no longer needed, by an explicit call
97 to subroutine GF_FREE.
99 Please see the "GRIB2 Routine Docblocks" section below for subroutine
100 argument usage for the routines mentioned above.
102 ===============================================================================
104 Extracting GRIB2 Fields from a GRIB2 file
106 Subroutine GETGB2 can be used to extract a specified field from a file
107 containing many GRIB2 messages. GETGB2 searches an index to find the
108 location of the user specified field. The index can be supplied from a
109 seperate GRIB2 index file, or it can be generated internally.
111 The GRIB2 file ( and the index file, if supplied ) must be opened with
112 a call to subroutine BAOPEN prior to the call to GETGB2.
114 The decoded information for the selected GRIB field is returned in a
115 derived type variable, gfld. Gfld is of type gribfield, which is defined
116 in module grib_mod, so users of this routine will need to include
117 the line "USE GRIB_MOD" in their calling routine. Each component of the
118 gribfield type is described in the OUTPUT ARGUMENT LIST in the docblock
119 for subroutine GETGB2 below.
121 Note that derived type gribfield contains pointers to many arrays of data.
122 The memory for these arrays is allocated when the values in the arrays
123 are set, to help minimize problems with array overloading. Because of this,
124 users are encouraged to free up this memory, when it is no longer
125 needed, by an explicit call to subroutine GF_FREE.
127 Example usage:
129 use grib_mod
130 type(gribfield) :: gfld
131 integer,dimension(200) :: jids,jpdt,jgdt
132 logical :: unpack=.true.
133 ifile=10
134 ! Open GRIB2 file
135 call baopenr(ifile,"filename",iret)
136 .
137 ! Set GRIB2 field identification values to search for
138 jdisc=
139 jids(?)=
140 jpdtn=
141 jpdt(?)=
142 jgdtn=
143 jgdt(?)=
145 ! Get field from file
146 call getgb2(ifile,0,j,jdisc,jids,jpdtn,jpdt,jgdtn,jgdt,
147 & unpack,j,gfld,iret)
149 ! Process field ...
150 firstval=gfld%fld(1)
151 lastval=gfld%fld(gfld%ndpts)
152 fldmax=maxval(gfld%fld)
153 fldmin=minval(gfld%fld)
155 ! Free memory when done with field
156 call gf_free(gfld)
158 stop
159 end
161 Please see the "GRIB2 Routine Docblocks" section below for subroutine
162 argument usage for the routines mentioned above.
164 ===============================================================================
166 GRIB2 Tables/Templates
168 WMO's GRIB2 specification "FM 92-XII GRIB - General Regularly-distributed
169 Information in Binary Form" contains descriptions of each template
170 and code table information. This document can be found at
171 http://www.wmo.ch/web/www/WMOCodes.html
172 (PDF and MSWord formats are available)
174 MDL has made an HTML version of the document available at
175 http://www.nws.noaa.gov/tdl/iwt/grib2/frameset_grib2.htm.
177 ===============================================================================
179 GRIB2 Routine Docblocks
181 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
182 ! . . . .
183 ! SUBPROGRAM: gribcreate
184 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-04-28
185 !
186 ! ABSTRACT: This subroutine initializes a new GRIB2 message and packs
187 ! GRIB2 sections 0 (Indicator Section) and 1 (Identification Section).
188 ! This routine is used with routines "addlocal", "addgrid", "addfield",
189 ! and "gribend" to create a complete GRIB2 message. Subroutine
190 ! gribcreate must be called first to initialize a new GRIB2 message.
191 ! Also, a call to gribend is required to complete GRIB2 message
192 ! after all fields have been added.
193 !
194 ! PROGRAM HISTORY LOG:
195 ! 2000-04-28 Gilbert
196 !
197 ! USAGE: CALL gribcreate(cgrib,lcgrib,listsec0,listsec1,ierr)
198 ! INPUT ARGUMENT LIST:
199 ! cgrib - Character array to contain the GRIB2 message
200 ! lcgrib - Maximum length (bytes) of array cgrib.
201 ! listsec0 - Contains information needed for GRIB Indicator Section 0.
202 ! Must be dimensioned >= 2.
203 ! listsec0(1)=Discipline-GRIB Master Table Number
204 ! (see Code Table 0.0)
205 ! listsec0(2)=GRIB Edition Number (currently 2)
206 ! listsec1 - Contains information needed for GRIB Identification Section 1.
207 ! Must be dimensioned >= 13.
208 ! listsec1(1)=Id of orginating centre (Common Code Table C-1)
209 ! listsec1(2)=Id of orginating sub-centre (local table)
210 ! listsec1(3)=GRIB Master Tables Version Number (Code Table 1.0)
211 ! listsec1(4)=GRIB Local Tables Version Number (Code Table 1.1)
212 ! listsec1(5)=Significance of Reference Time (Code Table 1.2)
213 ! listsec1(6)=Reference Time - Year (4 digits)
214 ! listsec1(7)=Reference Time - Month
215 ! listsec1(8)=Reference Time - Day
216 ! listsec1(9)=Reference Time - Hour
217 ! listsec1(10)=Reference Time - Minute
218 ! listsec1(11)=Reference Time - Second
219 ! listsec1(12)=Production status of data (Code Table 1.3)
220 ! listsec1(13)=Type of processed data (Code Table 1.4)
221 !
222 ! OUTPUT ARGUMENT LIST:
223 ! cgrib - Character array to contain the GRIB2 message
224 ! ierr - Error return code.
225 ! 0 = no error
226 ! 1 = Tried to use for version other than GRIB Edition 2
227 !
228 ! REMARKS: This routine is intended for use with routines "addlocal",
229 ! "addgrid", "addfield", and "gribend" to create a complete
230 ! GRIB2 message.
231 !
232 ! ATTRIBUTES:
233 ! LANGUAGE: Fortran 90
234 ! MACHINE: IBM SP
235 !
236 !$$$
238 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
239 ! . . . .
240 ! SUBPROGRAM: addlocal
241 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-01
242 !
243 ! ABSTRACT: This subroutine adds a Local Use Section (Section 2) to
244 ! a GRIB2 message.
245 ! This routine is used with routines "gribcreate", "addgrid", "addfield",
246 ! and "gribend" to create a complete GRIB2 message. Subroutine
247 ! gribcreate must be called first to initialize a new GRIB2 message.
248 !
249 ! PROGRAM HISTORY LOG:
250 ! 2000-05-01 Gilbert
251 !
252 ! USAGE: CALL addlocal(cgrib,lcgrib,csec2,lcsec2,ierr)
253 ! INPUT ARGUMENT LIST:
254 ! cgrib - Character array to contain the GRIB2 message
255 ! lcgrib - Maximum length (bytes) of array cgrib.
256 ! csec2 - Character array containing information to be added to
257 ! Section 2.
258 ! lcsec2 - Number of bytes of character array csec2 to be added to
259 ! Section 2.
260 !
261 ! OUTPUT ARGUMENT LIST:
262 ! cgrib - Character array to contain the GRIB2 message
263 ! ierr - Error return code.
264 ! 0 = no error
265 ! 1 = GRIB message was not initialized. Need to call
266 ! routine gribcreate first.
267 ! 2 = GRIB message already complete. Cannot add new section.
268 ! 3 = Sum of Section byte counts doesn't add to total byte count.
269 ! 4 = Previous Section was not 1 or 7.
270 !
271 ! REMARKS: Note that the Local Use Section ( Section 2 ) can only follow
272 ! Section 1 or Section 7 in a GRIB2 message.
273 !
274 ! ATTRIBUTES:
275 ! LANGUAGE: Fortran 90
276 ! MACHINE: IBM SP
277 !
278 !$$$
280 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
281 ! . . . .
282 ! SUBPROGRAM: addgrid
283 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-01
284 !
285 ! ABSTRACT: This subroutine packs up a Grid Definition Section (Section 3)
286 ! and adds it to a GRIB2 message.
287 ! This routine is used with routines "gribcreate", "addlocal", "addfield",
288 ! and "gribend" to create a complete GRIB2 message. Subroutine
289 ! gribcreate must be called first to initialize a new GRIB2 message.
290 !
291 ! PROGRAM HISTORY LOG:
292 ! 2000-05-01 Gilbert
293 !
294 ! USAGE: CALL addgrid(cgrib,lcgrib,igds,igdstmpl,igdstmplen,
295 ! ideflist,idefnum,ierr)
296 ! INPUT ARGUMENT LIST:
297 ! cgrib - Character array to contain the GRIB2 message
298 ! lcgrib - Maximum length (bytes) of array cgrib.
299 ! igds - Contains information needed for GRIB Grid Definition Section 3.
300 ! Must be dimensioned >= 5.
301 ! igds(1)=Source of grid definition (see Code Table 3.0)
302 ! igds(2)=Number of grid points in the defined grid.
303 ! igds(3)=Number of octets needed for each
304 ! additional grid points definition.
305 ! Used to define number of
306 ! points in each row ( or column ) for
307 ! non-regular grids.
308 ! = 0, if using regular grid.
309 ! igds(4)=Interpretation of list for optional points
310 ! definition. (Code Table 3.11)
311 ! igds(5)=Grid Definition Template Number (Code Table 3.1)
312 ! igdstmpl - Contains the data values for the specified Grid Definition
313 ! Template ( NN=igds(5) ). Each element of this integer
314 ! array contains an entry (in the order specified) of Grid
315 ! Defintion Template 3.NN
316 ! igdstmplen - Max dimension of igdstmpl()
317 ! ideflist - (Used if igds(3) .ne. 0) This array contains the
318 ! number of grid points contained in each row ( or column )
319 ! idefnum - (Used if igds(3) .ne. 0) The number of entries
320 ! in array ideflist. i.e. number of rows ( or columns )
321 ! for which optional grid points are defined.
322 !
323 ! OUTPUT ARGUMENT LIST:
324 ! cgrib - Character array to contain the GRIB2 message
325 ! ierr - Error return code.
326 ! 0 = no error
327 ! 1 = GRIB message was not initialized. Need to call
328 ! routine gribcreate first.
329 ! 2 = GRIB message already complete. Cannot add new section.
330 ! 3 = Sum of Section byte counts doesn't add to total byte count.
331 ! 4 = Previous Section was not 1, 2 or 7.
332 ! 5 = Could not find requested Grid Definition Template.
333 !
334 ! REMARKS: Note that the Local Use Section ( Section 2 ) can only follow
335 ! Section 1 or Section 7 in a GRIB2 message.
336 !
337 ! ATTRIBUTES:
338 ! LANGUAGE: Fortran 90
339 ! MACHINE: IBM SP
340 !
341 !$$$
343 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
344 ! . . . .
345 ! SUBPROGRAM: addfield
346 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-02
347 !
348 ! ABSTRACT: This subroutine packs up Sections 4 through 7 for a given field
349 ! and adds them to a GRIB2 message. They are Product Definition Section,
350 ! Data Representation Section, Bit-Map Section and Data Section,
351 ! respectively.
352 ! This routine is used with routines "gribcreate", "addlocal", "addgrid",
353 ! and "gribend" to create a complete GRIB2 message. Subroutine
354 ! gribcreate must be called first to initialize a new GRIB2 message.
355 ! Also, subroutine addgrid must be called after gribcreate and
356 ! before this routine to add the appropriate grid description to
357 ! the GRIB2 message. Also, a call to gribend is required to complete
358 ! GRIB2 message after all fields have been added.
359 !
360 ! PROGRAM HISTORY LOG:
361 ! 2000-05-02 Gilbert
362 ! 2002-12-17 Gilbert - Added support for new templates using
363 ! PNG and JPEG2000 algorithms/templates.
364 ! 2004-06-22 Gilbert - Added check to determine if packing algorithm failed.
365 !
366 ! USAGE: CALL addfield(cgrib,lcgrib,ipdsnum,ipdstmpl,ipdstmplen,
367 ! coordlist,numcoord,idrsnum,idrstmpl,
368 ! idrstmplen,fld,ngrdpts,ibmap,bmap,ierr)
369 ! INPUT ARGUMENT LIST:
370 ! cgrib - Character array to contain the GRIB2 message
371 ! lcgrib - Maximum length (bytes) of array cgrib.
372 ! ipdsnum - Product Definition Template Number ( see Code Table 4.0)
373 ! ipdstmpl - Contains the data values for the specified Product Definition
374 ! Template ( N=ipdsnum ). Each element of this integer
375 ! array contains an entry (in the order specified) of Product
376 ! Defintion Template 4.N
377 ! ipdstmplen - Max dimension of ipdstmpl()
378 ! coordlist- Array containg floating point values intended to document
379 ! the vertical discretisation associated to model data
380 ! on hybrid coordinate vertical levels.
381 ! numcoord - number of values in array coordlist.
382 ! idrsnum - Data Representation Template Number ( see Code Table 5.0 )
383 ! idrstmpl - Contains the data values for the specified Data Representation
384 ! Template ( N=idrsnum ). Each element of this integer
385 ! array contains an entry (in the order specified) of Data
386 ! Representation Template 5.N
387 ! Note that some values in this template (eg. reference
388 ! values, number of bits, etc...) may be changed by the
389 ! data packing algorithms.
390 ! Use this to specify scaling factors and order of
391 ! spatial differencing, if desired.
392 ! idrstmplen - Max dimension of idrstmpl()
393 ! fld() - Array of data points to pack.
394 ! ngrdpts - Number of data points in grid.
395 ! i.e. size of fld and bmap.
396 ! ibmap - Bitmap indicator ( see Code Table 6.0 )
397 ! 0 = bitmap applies and is included in Section 6.
398 ! 1-253 = Predefined bitmap applies
399 ! 254 = Previously defined bitmap applies to this field
400 ! 255 = Bit map does not apply to this product.
401 ! bmap() - Logical*1 array containing bitmap to be added.
402 ! ( if ibmap=0 or ibmap=254)
403 !
404 ! OUTPUT ARGUMENT LIST:
405 ! cgrib - Character array to contain the GRIB2 message
406 ! ierr - Error return code.
407 ! 0 = no error
408 ! 1 = GRIB message was not initialized. Need to call
409 ! routine gribcreate first.
410 ! 2 = GRIB message already complete. Cannot add new section.
411 ! 3 = Sum of Section byte counts doesn't add to total byte count.
412 ! 4 = Previous Section was not 3 or 7.
413 ! 5 = Could not find requested Product Definition Template.
414 ! 6 = Section 3 (GDS) not previously defined in message
415 ! 7 = Tried to use unsupported Data Representationi Template
416 ! 8 = Specified use of a previously defined bitmap, but one
417 ! does not exist in the GRIB message.
418 ! 9 = GDT of one of 5.50 through 5.53 required to pack
419 ! using DRT 5.51
420 ! 10 = Error packing data field.
421 !
422 ! REMARKS: Note that the Local Use Section ( Section 2 ) can only follow
423 ! Section 1 or Section 7 in a GRIB2 message.
424 !
425 ! ATTRIBUTES:
426 ! LANGUAGE: Fortran 90
427 ! MACHINE: IBM SP
428 !
429 !$$$
431 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
432 ! . . . .
433 ! SUBPROGRAM: gribend
434 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-02
435 !
436 ! ABSTRACT: This subroutine finalizes a GRIB message after all grids
437 ! and fields have been added. It adds the End Section ( "7777" )
438 ! to the end of the GRIB message and calculates the length and stores
439 ! it in the appropriate place in Section 0.
440 ! This routine is used with routines "gribcreate", "addlocal", "addgrid",
441 ! and "addfield" to create a complete GRIB2 message. Subroutine
442 ! gribcreate must be called first to initialize a new GRIB2 message.
443 !
444 ! PROGRAM HISTORY LOG:
445 ! 2000-05-02 Gilbert
446 !
447 ! USAGE: CALL gribend(cgrib,lcgrib,lengrib,ierr)
448 ! INPUT ARGUMENT LIST:
449 ! cgrib - Character array to contain the GRIB2 message
450 ! lcgrib - Maximum length (bytes) of array cgrib.
451 !
452 ! OUTPUT ARGUMENT LIST:
453 ! cgrib - Character array to contain the GRIB2 message
454 ! lengrib - Length of the final GRIB2 message in octets (bytes)
455 ! ierr - Error return code.
456 ! 0 = no error
457 ! 1 = GRIB message was not initialized. Need to call
458 ! routine gribcreate first.
459 ! 2 = GRIB message already complete.
460 ! 3 = Sum of Section byte counts doesn't add to total byte count.
461 ! 4 = Previous Section was not 7.
462 !
463 ! REMARKS: This routine is intended for use with routines "gribcreate",
464 ! "addlocal", "addgrid", and "addfield" to create a complete
465 ! GRIB2 message.
466 !
467 ! ATTRIBUTES:
468 ! LANGUAGE: Fortran 90
469 ! MACHINE: IBM SP
470 !
471 !$$$
474 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
475 ! . . . .
476 ! SUBPROGRAM: gb_info
477 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-25
478 !
479 ! ABSTRACT: This subroutine searches through a GRIB2 message and
480 ! returns the number of gridded fields found in the message and
481 ! the number (and maximum size) of Local Use Sections.
482 ! Also various checks are performed
483 ! to see if the message is a valid GRIB2 message.
484 !
485 ! PROGRAM HISTORY LOG:
486 ! 2000-05-25 Gilbert
487 !
488 ! USAGE: CALL gb_info(cgrib,lcgrib,listsec0,listsec1,
489 ! & numfields,numlocal,maxlocal,ierr)
490 ! INPUT ARGUMENT LIST:
491 ! cgrib - Character array that contains the GRIB2 message
492 ! lcgrib - Length (in bytes) of GRIB message in array cgrib.
493 !
494 ! OUTPUT ARGUMENT LIST:
495 ! listsec0 - Contains information decoded from GRIB Indicator Section 0.
496 ! Must be dimensioned >= 2.
497 ! listsec0(1)=Discipline-GRIB Master Table Number
498 ! (see Code Table 0.0)
499 ! listsec0(2)=GRIB Edition Number (currently 2)
500 ! listsec0(3)=Length of GRIB message
501 ! listsec1 - Contains information read from GRIB Identification Section 1.
502 ! Must be dimensioned >= 13.
503 ! listsec1(1)=Id of orginating centre (Common Code Table C-1)
504 ! listsec1(2)=Id of orginating sub-centre (local table)
505 ! listsec1(3)=GRIB Master Tables Version Number (Code Table 1.0)
506 ! listsec1(4)=GRIB Local Tables Version Number
507 ! listsec1(5)=Significance of Reference Time (Code Table 1.1)
508 ! listsec1(6)=Reference Time - Year (4 digits)
509 ! listsec1(7)=Reference Time - Month
510 ! listsec1(8)=Reference Time - Day
511 ! listsec1(9)=Reference Time - Hour
512 ! listsec1(10)=Reference Time - Minute
513 ! listsec1(11)=Reference Time - Second
514 ! listsec1(12)=Production status of data (Code Table 1.2)
515 ! listsec1(13)=Type of processed data (Code Table 1.3)
516 ! numfields- The number of gridded fields found in the GRIB message.
517 ! numlocal - The number of Local Use Sections ( Section 2 ) found in
518 ! the GRIB message.
519 ! maxlocal- The size of the largest Local Use Section ( Section 2 ).
520 ! Can be used to ensure that the return array passed
521 ! to subroutine getlocal is dimensioned large enough.
522 ! ierr - Error return code.
523 ! 0 = no error
524 ! 1 = Beginning characters "GRIB" not found.
525 ! 2 = GRIB message is not Edition 2.
526 ! 3 = Could not find Section 1, where expected.
527 ! 4 = End string "7777" found, but not where expected.
528 ! 5 = End string "7777" not found at end of message.
529 ! 6 = Invalid section number found.
530 !
531 ! REMARKS: None
532 !
533 ! ATTRIBUTES:
534 ! LANGUAGE: Fortran 90
535 ! MACHINE: IBM SP
536 !
537 !$$$
539 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
540 ! . . . .
541 ! SUBPROGRAM: getlocal
542 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-25
543 !
544 ! ABSTRACT: This subroutine returns the contents of Section 2 ( Local
545 ! Use Section ) from a GRIB2 message. Since there can be multiple
546 ! occurrences of Section 2 within a GRIB message, the calling routine
547 ! indicates which occurrence is being requested with the localnum argument.
548 !
549 ! PROGRAM HISTORY LOG:
550 ! 2000-05-25 Gilbert
551 !
552 ! USAGE: CALL getlocal(cgrib,lcgrib,localnum,csec2,lcsec2,ierr)
553 ! INPUT ARGUMENT LIST:
554 ! cgrib - Character array that contains the GRIB2 message
555 ! lcgrib - Length (in bytes) of GRIB message in array cgrib.
556 ! localnum - The nth occurrence of Section 2 requested.
557 !
558 ! OUTPUT ARGUMENT LIST:
559 ! csec2 - Character array containing information read from
560 ! Section 2.
561 ! The dimension of this array can be obtained in advance
562 ! from argument maxlocal, which is returned from subroutine
563 ! gb_info.
564 ! lcsec2 - Number of bytes of character array csec2 read from
565 ! Section 2.
566 ! ierr - Error return code.
567 ! 0 = no error
568 ! 1 = Beginning characters "GRIB" not found.
569 ! 2 = GRIB message is not Edition 2.
570 ! 3 = The section 2 request number was not positive.
571 ! 4 = End string "7777" found, but not where expected.
572 ! 5 = End string "7777" not found at end of message.
573 ! 6 = GRIB message did not contain the requested number of
574 ! Local Use Sections.
575 !
576 ! REMARKS: Note that subroutine gribinfo can be used to first determine
577 ! how many Local Use sections exist in a given GRIB message.
578 !
579 ! ATTRIBUTES:
580 ! LANGUAGE: Fortran 90
581 ! MACHINE: IBM SP
582 !
583 !$$$
586 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
587 ! . . . .
588 ! SUBPROGRAM: gf_getfld
589 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-26
590 !
591 ! ABSTRACT: This subroutine returns the Grid Definition, Product Definition,
592 ! Bit-map ( if applicable ), and the unpacked data for a given data
593 ! field. All of the information returned is stored in a derived
594 ! type variable, gfld. Gfld is of type gribfield, which is defined
595 ! in module grib_mod, so users of this routine will need to include
596 ! the line "USE GRIB_MOD" in their calling routine. Each component of the
597 ! gribfield type is described in the OUTPUT ARGUMENT LIST section below.
598 !
599 ! Since there can be multiple data fields packed into a GRIB2
600 ! message, the calling routine indicates which field is being requested
601 ! with the ifldnum argument.
602 !
603 ! PROGRAM HISTORY LOG:
604 ! 2000-05-26 Gilbert
605 ! 2002-01-24 Gilbert - Changed to pass back derived type gribfield
606 ! variable through argument list, instead of
607 ! having many different arguments.
608 !
609 ! USAGE: CALL gf_getfld(cgrib,lcgrib,ifldnum,unpack,expand,gfld,ierr)
610 ! INPUT ARGUMENT LIST:
611 ! cgrib - Character array that contains the GRIB2 message
612 ! lcgrib - Length (in bytes) of GRIB message array cgrib.
613 ! ifldnum - Specifies which field in the GRIB2 message to return.
614 ! unpack - Logical value indicating whether to unpack bitmap/data
615 ! .true. = unpack bitmap and data values
616 ! .false. = do not unpack bitmap and data values
617 ! expand - Boolean value indicating whether the data points should be
618 ! expanded to the correspond grid, if a bit-map is present.
619 ! 1 = if possible, expand data field to grid, inserting zero
620 ! values at gridpoints that are bitmapped out.
621 ! (SEE REMARKS2)
622 ! 0 = do not expand data field, leaving it an array of
623 ! consecutive data points for each "1" in the bitmap.
624 ! This argument is ignored if unpack == 0 OR if the
625 ! returned field does not contain a bit-map.
626 !
627 ! OUTPUT ARGUMENT LIST:
628 ! gfld - derived type gribfield ( defined in module grib_mod )
629 ! ( NOTE: See Remarks Section )
630 ! gfld%version = GRIB edition number ( currently 2 )
631 ! gfld%discipline = Message Discipline ( see Code Table 0.0 )
632 ! gfld%idsect() = Contains the entries in the Identification
633 ! Section ( Section 1 )
634 ! This element is actually a pointer to an array
635 ! that holds the data.
636 ! gfld%idsect(1) = Identification of originating Centre
637 ! ( see Common Code Table C-1 )
638 ! 7 - US National Weather Service
639 ! gfld%idsect(2) = Identification of originating Sub-centre
640 ! gfld%idsect(3) = GRIB Master Tables Version Number
641 ! ( see Code Table 1.0 )
642 ! 0 - Experimental
643 ! 1 - Initial operational version number
644 ! gfld%idsect(4) = GRIB Local Tables Version Number
645 ! ( see Code Table 1.1 )
646 ! 0 - Local tables not used
647 ! 1-254 - Number of local tables version used
648 ! gfld%idsect(5) = Significance of Reference Time (Code Table 1.2)
649 ! 0 - Analysis
650 ! 1 - Start of forecast
651 ! 2 - Verifying time of forecast
652 ! 3 - Observation time
653 ! gfld%idsect(6) = Year ( 4 digits )
654 ! gfld%idsect(7) = Month
655 ! gfld%idsect(8) = Day
656 ! gfld%idsect(9) = Hour
657 ! gfld%idsect(10) = Minute
658 ! gfld%idsect(11) = Second
659 ! gfld%idsect(12) = Production status of processed data
660 ! ( see Code Table 1.3 )
661 ! 0 - Operational products
662 ! 1 - Operational test products
663 ! 2 - Research products
664 ! 3 - Re-analysis products
665 ! gfld%idsect(13) = Type of processed data ( see Code Table 1.4 )
666 ! 0 - Analysis products
667 ! 1 - Forecast products
668 ! 2 - Analysis and forecast products
669 ! 3 - Control forecast products
670 ! 4 - Perturbed forecast products
671 ! 5 - Control and perturbed forecast products
672 ! 6 - Processed satellite observations
673 ! 7 - Processed radar observations
674 ! gfld%idsectlen = Number of elements in gfld%idsect().
675 ! gfld%ifldnum = field number within GRIB message
676 ! gfld%griddef = Source of grid definition (see Code Table 3.0)
677 ! 0 - Specified in Code table 3.1
678 ! 1 - Predetermined grid Defined by originating centre
679 ! gfld%ngrdpts = Number of grid points in the defined grid.
680 ! gfld%numoct_opt = Number of octets needed for each
681 ! additional grid points definition.
682 ! Used to define number of
683 ! points in each row ( or column ) for
684 ! non-regular grids.
685 ! = 0, if using regular grid.
686 ! gfld%interp_opt = Interpretation of list for optional points
687 ! definition. (Code Table 3.11)
688 ! gfld%igdtnum = Grid Definition Template Number (Code Table 3.1)
689 ! gfld%igdtmpl() = Contains the data values for the specified Grid
690 ! Definition Template ( NN=gfld%igdtnum ). Each
691 ! element of this integer array contains an entry (in
692 ! the order specified) of Grid Defintion Template 3.NN
693 ! This element is actually a pointer to an array
694 ! that holds the data.
695 ! gfld%igdtlen = Number of elements in gfld%igdtmpl(). i.e. number of
696 ! entries in Grid Defintion Template 3.NN
697 ! ( NN=gfld%igdtnum ).
698 ! gfld%list_opt() = (Used if gfld%numoct_opt .ne. 0) This array
699 ! contains the number of grid points contained in
700 ! each row ( or column ). (part of Section 3)
701 ! This element is actually a pointer to an array
702 ! that holds the data. This pointer is nullified
703 ! if gfld%numoct_opt=0.
704 ! gfld%num_opt = (Used if gfld%numoct_opt .ne. 0) The number of entries
705 ! in array ideflist. i.e. number of rows ( or columns )
706 ! for which optional grid points are defined. This value
707 ! is set to zero, if gfld%numoct_opt=0.
708 ! gfdl%ipdtnum = Product Definition Template Number (see Code Table 4.0)
709 ! gfld%ipdtmpl() = Contains the data values for the specified Product
710 ! Definition Template ( N=gfdl%ipdtnum ). Each element
711 ! of this integer array contains an entry (in the
712 ! order specified) of Product Defintion Template 4.N.
713 ! This element is actually a pointer to an array
714 ! that holds the data.
715 ! gfld%ipdtlen = Number of elements in gfld%ipdtmpl(). i.e. number of
716 ! entries in Product Defintion Template 4.N
717 ! ( N=gfdl%ipdtnum ).
718 ! gfld%coord_list() = Real array containing floating point values
719 ! intended to document the vertical discretisation
720 ! associated to model data on hybrid coordinate
721 ! vertical levels. (part of Section 4)
722 ! This element is actually a pointer to an array
723 ! that holds the data.
724 ! gfld%num_coord = number of values in array gfld%coord_list().
725 ! gfld%ndpts = Number of data points unpacked and returned.
726 ! gfld%idrtnum = Data Representation Template Number
727 ! ( see Code Table 5.0)
728 ! gfld%idrtmpl() = Contains the data values for the specified Data
729 ! Representation Template ( N=gfld%idrtnum ). Each
730 ! element of this integer array contains an entry
731 ! (in the order specified) of Product Defintion
732 ! Template 5.N.
733 ! This element is actually a pointer to an array
734 ! that holds the data.
735 ! gfld%idrtlen = Number of elements in gfld%idrtmpl(). i.e. number
736 ! of entries in Data Representation Template 5.N
737 ! ( N=gfld%idrtnum ).
738 ! gfld%unpacked = logical value indicating whether the bitmap and
739 ! data values were unpacked. If false,
740 ! gfld%bmap and gfld%fld pointers are nullified.
741 ! gfld%expanded = Logical value indicating whether the data field
742 ! was expanded to the grid in the case where a
743 ! bit-map is present. If true, the data points in
744 ! gfld%fld match the grid points and zeros were
745 ! inserted at grid points where data was bit-mapped
746 ! out. If false, the data values in gfld%fld were
747 ! not expanded to the grid and are just a consecutive
748 ! array of data points corresponding to each value of
749 ! "1" in gfld%bmap.
750 ! gfld%ibmap = Bitmap indicator ( see Code Table 6.0 )
751 ! 0 = bitmap applies and is included in Section 6.
752 ! 1-253 = Predefined bitmap applies
753 ! 254 = Previously defined bitmap applies to this field
754 ! 255 = Bit map does not apply to this product.
755 ! gfld%bmap() = Logical*1 array containing decoded bitmap,
756 ! if ibmap=0 or ibap=254. Otherwise nullified.
757 ! This element is actually a pointer to an array
758 ! that holds the data.
759 ! gfld%fld() = Array of gfld%ndpts unpacked data points.
760 ! This element is actually a pointer to an array
761 ! that holds the data.
762 ! ierr - Error return code.
763 ! 0 = no error
764 ! 1 = Beginning characters "GRIB" not found.
765 ! 2 = GRIB message is not Edition 2.
766 ! 3 = The data field request number was not positive.
767 ! 4 = End string "7777" found, but not where expected.
768 ! 6 = GRIB message did not contain the requested number of
769 ! data fields.
770 ! 7 = End string "7777" not found at end of message.
771 ! 8 = Unrecognized Section encountered.
772 ! 9 = Data Representation Template 5.NN not yet implemented.
773 ! 15 = Error unpacking Section 1.
774 ! 10 = Error unpacking Section 3.
775 ! 11 = Error unpacking Section 4.
776 ! 12 = Error unpacking Section 5.
777 ! 13 = Error unpacking Section 6.
778 ! 14 = Error unpacking Section 7.
779 !
780 ! REMARKS: Note that derived type gribfield contains pointers to many
781 ! arrays of data. The memory for these arrays is allocated
782 ! when the values in the arrays are set, to help minimize
783 ! problems with array overloading. Because of this users
784 ! are encouraged to free up this memory, when it is no longer
785 ! needed, by an explicit call to subroutine gf_free.
786 ! ( i.e. CALL GF_FREE(GFLD) )
787 !
788 ! Subroutine gb_info can be used to first determine
789 ! how many data fields exist in a given GRIB message.
790 !
791 ! REMARKS2: It may not always be possible to expand a bit-mapped data field.
792 ! If a pre-defined bit-map is used and not included in the GRIB2
793 ! message itself, this routine would not have the necessary
794 ! information to expand the data. In this case, gfld%expanded would
795 ! would be set to 0 (false), regardless of the value of input
796 ! argument expand.
797 !
798 ! ATTRIBUTES:
799 ! LANGUAGE: Fortran 90
800 ! MACHINE: IBM SP
801 !
802 !$$$
805 !$$$ SUBPROGRAM DOCUMENTATION BLOCK
806 ! . . . .
807 ! SUBPROGRAM: gf_free
808 ! PRGMMR: Gilbert ORG: W/NP11 DATE: 2000-05-26
809 !
810 ! ABSTRACT: This subroutine frees up memory that was used to store
811 ! array values in derived type gribfield.
812 !
813 ! PROGRAM HISTORY LOG:
814 ! 2000-05-26 Gilbert
815 !
816 ! USAGE: CALL gf_free(gfld)
817 ! INPUT ARGUMENT LIST:
818 ! gfld - derived type gribfield ( defined in module grib_mod )
819 !
820 ! OUTPUT ARGUMENT LIST:
821 ! gfld - derived type gribfield ( defined in module grib_mod )
822 ! gfld%version = GRIB edition number
823 ! gfld%discipline = Message Discipline ( see Code Table 0.0 )
824 ! gfld%idsect() = Contains the entries in the Identification
825 ! Section ( Section 1 )
826 ! This element is actually a pointer to an array
827 ! that holds the data.
828 ! gfld%idsect(1) = Identification of originating Centre
829 ! ( see Common Code Table C-1 )
830 ! gfld%idsect(2) = Identification of originating Sub-centre
831 ! gfld%idsect(3) = GRIB Master Tables Version Number
832 ! ( see Code Table 1.0 )
833 ! gfld%idsect(4) = GRIB Local Tables Version Number
834 ! ( see Code Table 1.1 )
835 ! gfld%idsect(5) = Significance of Reference Time (Code Table 1.2)
836 ! gfld%idsect(6) = Year ( 4 digits )
837 ! gfld%idsect(7) = Month
838 ! gfld%idsect(8) = Day
839 ! gfld%idsect(9) = Hour
840 ! gfld%idsect(10) = Minute
841 ! gfld%idsect(11) = Second
842 ! gfld%idsect(12) = Production status of processed data
843 ! ( see Code Table 1.3 )
844 ! gfld%idsect(13) = Type of processed data ( see Code Table 1.4 )
845 ! gfld%idsectlen = Number of elements in gfld%idsect().
846 ! gfld%ifldnum = field number within GRIB message
847 ! gfld%griddef = Source of grid definition (see Code Table 3.0)
848 ! gfld%ngrdpts = Number of grid points in the defined grid.
849 ! gfld%numoct_opt = Number of octets needed for each
850 ! additional grid points definition.
851 ! Used to define number of
852 ! points in each row ( or column ) for
853 ! non-regular grids.
854 ! = 0, if using regular grid.
855 ! gfld%interp_opt = Interpretation of list for optional points
856 ! definition. (Code Table 3.11)
857 ! gfld%igdtnum = Grid Definition Template Number (Code Table 3.1)
858 ! gfld%igdtmpl() = Contains the data values for the specified Grid
859 ! Definition Template ( NN=gfld%igdtnum ). Each
860 ! element of this integer array contains an entry (in
861 ! the order specified) of Grid Defintion Template 3.NN
862 ! This element is actually a pointer to an array
863 ! that holds the data.
864 ! gfld%igdtlen = Number of elements in gfld%igdtmpl(). i.e. number of
865 ! entries in Grid Defintion Template 3.NN
866 ! ( NN=gfld%igdtnum ).
867 ! gfld%list_opt() = (Used if gfld%numoct_opt .ne. 0) This array
868 ! contains the number of grid points contained in
869 ! each row ( or column ). (part of Section 3)
870 ! This element is actually a pointer to an array
871 ! that holds the data. This pointer is nullified
872 ! if gfld%numoct_opt=0.
873 ! gfld%num_opt = (Used if gfld%numoct_opt .ne. 0) The number of entries
874 ! in array ideflist. i.e. number of rows ( or columns )
875 ! for which optional grid points are defined. This value
876 ! is set to zero, if gfld%numoct_opt=0.
877 ! gfdl%ipdtnum = Product Definition Template Number (see Code Table 4.0)
878 ! gfld%ipdtmpl() = Contains the data values for the specified Product
879 ! Definition Template ( N=gfdl%ipdtnum ). Each element
880 ! of this integer array contains an entry (in the
881 ! order specified) of Product Defintion Template 4.N.
882 ! This element is actually a pointer to an array
883 ! that holds the data.
884 ! gfld%ipdtlen = Number of elements in gfld%ipdtmpl(). i.e. number of
885 ! entries in Product Defintion Template 4.N
886 ! ( N=gfdl%ipdtnum ).
887 ! gfld%coord_list() = Real array containing floating point values
888 ! intended to document the vertical discretisation
889 ! associated to model data on hybrid coordinate
890 ! vertical levels. (part of Section 4)
891 ! This element is actually a pointer to an array
892 ! that holds the data.
893 ! gfld%num_coord = number of values in array gfld%coord_list().
894 ! gfld%ndpts = Number of data points unpacked and returned.
895 ! gfld%idrtnum = Data Representation Template Number
896 ! ( see Code Table 5.0)
897 ! gfld%idrtmpl() = Contains the data values for the specified Data
898 ! Representation Template ( N=gfld%idrtnum ). Each
899 ! element of this integer array contains an entry
900 ! (in the order specified) of Product Defintion
901 ! Template 5.N.
902 ! This element is actually a pointer to an array
903 ! that holds the data.
904 ! gfld%idrtlen = Number of elements in gfld%idrtmpl(). i.e. number
905 ! of entries in Data Representation Template 5.N
906 ! ( N=gfld%idrtnum ).
907 ! gfld%unpacked = logical value indicating whether the bitmap and
908 ! data values were unpacked. If false, gfld%ndpts
909 ! is set to zero, and gfld%bmap and gfld%fld
910 ! pointers are nullified.
911 ! gfld%expanded = Logical value indicating whether the data field
912 ! was expanded to the grid in the case where a
913 ! bit-map is present. If true, the data points in
914 ! gfld%fld match the grid points and zeros were
915 ! inserted at grid points where data was bit-mapped
916 ! out. If false, the data values in gfld%fld were
917 ! not expanded to the grid and are just a consecutive
918 ! array of data points corresponding to each value of
919 ! "1" in gfld%bmap.
920 ! gfld%ibmap = Bitmap indicator ( see Code Table 6.0 )
921 ! 0 = bitmap applies and is included in Section 6.
922 ! 1-253 = Predefined bitmap applies
923 ! 254 = Previously defined bitmap applies to this field
924 ! 255 = Bit map does not apply to this product.
925 ! gfld%bmap() - Logical*1 array containing decoded bitmap,
926 ! if ibmap=0 or ibap=254. Otherwise nullified.
927 ! This element is actually a pointer to an array
928 ! that holds the data.
929 ! gfld%fld() = Array of gfld%ndpts unpacked data points.
930 ! This element is actually a pointer to an array
931 ! that holds the data.
932 !
933 ! REMARKS:
934 !
935 ! ATTRIBUTES:
936 ! LANGUAGE: Fortran 90
937 ! MACHINE: IBM SP
938 !
939 !$$$
943 C$$$ SUBPROGRAM DOCUMENTATION BLOCK
944 C
945 C SUBPROGRAM: GETGB2 FINDS AND UNPACKS A GRIB MESSAGE
946 C PRGMMR: IREDELL ORG: W/NMC23 DATE: 94-04-01
947 C
948 C ABSTRACT: FIND AND UNPACK A GRIB MESSAGE.
949 C READ A GRIB INDEX FILE (OR OPTIONALLY THE GRIB FILE ITSELF)
950 C TO GET THE INDEX BUFFER (I.E. TABLE OF CONTENTS) FOR THE GRIB FILE.
951 C FIND IN THE INDEX BUFFER A REFERENCE TO THE GRIB FIELD REQUESTED.
952 C THE GRIB FIELD REQUEST SPECIFIES THE NUMBER OF FIELDS TO SKIP
953 C AND THE UNPACKED IDENTIFICATION SECTION, GRID DEFINITION TEMPLATE AND
954 C PRODUCT DEFINTION SECTION PARAMETERS. (A REQUESTED PARAMETER
955 C OF -9999 MEANS TO ALLOW ANY VALUE OF THIS PARAMETER TO BE FOUND.)
956 C IF THE REQUESTED GRIB FIELD IS FOUND, THEN IT IS READ FROM THE
957 C GRIB FILE AND UNPACKED. ITS NUMBER IS RETURNED ALONG WITH
958 C THE ASSOCIATED UNPACKED PARAMETERS. THE BITMAP (IF ANY),
959 C AND THE DATA VALUES ARE UNPACKED ONLY IF ARGUMENT "UNPACK" IS SET TO
960 C TRUE. IF THE GRIB FIELD IS NOT FOUND, THEN THE
961 C RETURN CODE WILL BE NONZERO.
962 C
963 C The decoded information for the selected GRIB field
964 C is returned in a derived type variable, gfld.
965 C Gfld is of type gribfield, which is defined
966 C in module grib_mod, so users of this routine will need to include
967 C the line "USE GRIB_MOD" in their calling routine. Each component of the
968 C gribfield type is described in the OUTPUT ARGUMENT LIST section below.
969 C
970 C PROGRAM HISTORY LOG:
971 C 94-04-01 IREDELL
972 C 95-10-31 IREDELL MODULARIZED PORTIONS OF CODE INTO SUBPROGRAMS
973 C AND ALLOWED FOR UNSPECIFIED INDEX FILE
974 C 2002-01-11 GILBERT MODIFIED FROM GETGB AND GETGBM TO WORK WITH GRIB2
975 C
976 C USAGE: CALL GETGB2(LUGB,LUGI,J,JDISC,JIDS,JPDTN,JPDT,JGDTN,JGDT,
977 C & UNPACK,K,GFLD,IRET)
978 C INPUT ARGUMENTS:
979 C LUGB INTEGER UNIT OF THE UNBLOCKED GRIB DATA FILE.
980 C FILE MUST BE OPENED WITH BAOPEN OR BAOPENR BEFORE CALLING
981 C THIS ROUTINE.
982 C LUGI INTEGER UNIT OF THE UNBLOCKED GRIB INDEX FILE.
983 C IF NONZERO, FILE MUST BE OPENED WITH BAOPEN BAOPENR BEFORE
984 C CALLING THIS ROUTINE.
985 C >0 - READ INDEX FROM INDEX FILE LUGI, IF INDEX DOESN"T
986 C ALREADY EXIST.
987 C =0 - TO GET INDEX BUFFER FROM THE GRIB FILE, IF INDEX
988 C DOESN"T ALREADY EXIST.
989 C <0 - FORCE REREAD OF INDEX FROM INDEX FILE ABS(LUGI).
990 C =LUGB - FORCE REGENERATION OF INDEX FROM GRIB2 FILE LUGB.
991 C J INTEGER NUMBER OF FIELDS TO SKIP
992 C (=0 TO SEARCH FROM BEGINNING)
993 C JDISC GRIB2 DISCIPLINE NUMBER OF REQUESTED FIELD
994 C ( IF = -1, ACCEPT ANY DISCIPLINE)
995 C ( SEE CODE TABLE 0.0 )
996 C 0 - Meteorological products
997 C 1 - Hydrological products
998 C 2 - Land surface products
999 C 3 - Space products
1000 C 10 - Oceanographic products
1001 C JIDS() INTEGER ARRAY OF VALUES IN THE IDENTIFICATION SECTION
1002 C (=-9999 FOR WILDCARD)
1003 C JIDS(1) = IDENTIFICATION OF ORIGINATING CENTRE
1004 C ( SEE COMMON CODE TABLE C-1 )
1005 C JIDS(2) = IDENTIFICATION OF ORIGINATING SUB-CENTRE
1006 C JIDS(3) = GRIB MASTER TABLES VERSION NUMBER
1007 C ( SEE CODE TABLE 1.0 )
1008 C 0 - Experimental
1009 C 1 - Initial operational version number
1010 C JIDS(4) = GRIB LOCAL TABLES VERSION NUMBER
1011 C ( SEE CODE TABLE 1.1 )
1012 C 0 - Local tables not used
1013 C 1-254 - Number of local tables version used
1014 C JIDS(5) = SIGNIFICANCE OF REFERENCE TIME (CODE TABLE 1.2)
1015 C 0 - Analysis
1016 C 1 - Start of forecast
1017 C 2 - Verifying time of forecast
1018 C 3 - Observation time
1019 C JIDS(6) = YEAR ( 4 DIGITS )
1020 C JIDS(7) = MONTH
1021 C JIDS(8) = DAY
1022 C JIDS(9) = HOUR
1023 C JIDS(10) = MINUTE
1024 C JIDS(11) = SECOND
1025 C JIDS(12) = PRODUCTION STATUS OF PROCESSED DATA
1026 C ( SEE CODE TABLE 1.3 )
1027 C 0 - Operational products
1028 C 1 - Operational test products
1029 C 2 - Research products
1030 C 3 - Re-analysis products
1031 C JIDS(13) = TYPE OF PROCESSED DATA ( SEE CODE TABLE 1.4 )
1032 C 0 - Analysis products
1033 C 1 - Forecast products
1034 C 2 - Analysis and forecast products
1035 C 3 - Control forecast products
1036 C 4 - Perturbed forecast products
1037 C 5 - Control and perturbed forecast products
1038 C 6 - Processed satellite observations
1039 C 7 - Processed radar observations
1040 C JPDTN INTEGER PRODUCT DEFINITION TEMPLATE NUMBER (N)
1041 C ( IF = -1, DON'T BOTHER MATCHING PDT - ACCEPT ANY )
1042 C JPDT() INTEGER ARRAY OF VALUES DEFINING THE PRODUCT DEFINITION
1043 C TEMPLATE 4.N OF THE FIELD FOR WHICH TO SEARCH
1044 C (=-9999 FOR WILDCARD)
1045 C JGDTN INTEGER GRID DEFINITION TEMPLATE NUMBER (M)
1046 C ( IF = -1, DON'T BOTHER MATCHING GDT - ACCEPT ANY )
1047 C JGDT() INTEGER ARRAY OF VALUES DEFINING THE GRID DEFINITION
1048 C TEMPLATE 3.M OF THE FIELD FOR WHICH TO SEARCH
1049 C (=-9999 FOR WILDCARD)
1050 C UNPACK LOGICAL VALUE INDICATING WHETHER TO UNPACK BITMAP/DATA
1051 C .TRUE. = UNPACK BITMAP AND DATA VALUES
1052 C .FALSE. = DO NOT UNPACK BITMAP AND DATA VALUES
1053 C
1054 C OUTPUT ARGUMENTS:
1055 C K INTEGER FIELD NUMBER UNPACKED
1056 C gfld - derived type gribfield ( defined in module grib_mod )
1057 C ( NOTE: See Remarks Section )
1058 C gfld%version = GRIB edition number ( currently 2 )
1059 C gfld%discipline = Message Discipline ( see Code Table 0.0 )
1060 C gfld%idsect() = Contains the entries in the Identification
1061 C Section ( Section 1 )
1062 C This element is actually a pointer to an array
1063 C that holds the data.
1064 C gfld%idsect(1) = Identification of originating Centre
1065 C ( see Common Code Table C-1 )
1066 C 7 - US National Weather Service
1067 C gfld%idsect(2) = Identification of originating Sub-centre
1068 C gfld%idsect(3) = GRIB Master Tables Version Number
1069 C ( see Code Table 1.0 )
1070 C 0 - Experimental
1071 C 1 - Initial operational version number
1072 C gfld%idsect(4) = GRIB Local Tables Version Number
1073 C ( see Code Table 1.1 )
1074 C 0 - Local tables not used
1075 C 1-254 - Number of local tables version used
1076 C gfld%idsect(5) = Significance of Reference Time (Code Table 1.2)
1077 C 0 - Analysis
1078 C 1 - Start of forecast
1079 C 2 - Verifying time of forecast
1080 C 3 - Observation time
1081 C gfld%idsect(6) = Year ( 4 digits )
1082 C gfld%idsect(7) = Month
1083 C gfld%idsect(8) = Day
1084 C gfld%idsect(9) = Hour
1085 C gfld%idsect(10) = Minute
1086 C gfld%idsect(11) = Second
1087 C gfld%idsect(12) = Production status of processed data
1088 C ( see Code Table 1.3 )
1089 C 0 - Operational products
1090 C 1 - Operational test products
1091 C 2 - Research products
1092 C 3 - Re-analysis products
1093 C gfld%idsect(13) = Type of processed data ( see Code Table 1.4 )
1094 C 0 - Analysis products
1095 C 1 - Forecast products
1096 C 2 - Analysis and forecast products
1097 C 3 - Control forecast products
1098 C 4 - Perturbed forecast products
1099 C 5 - Control and perturbed forecast products
1100 C 6 - Processed satellite observations
1101 C 7 - Processed radar observations
1102 C gfld%idsectlen = Number of elements in gfld%idsect().
1103 C gfld%local() = Pointer to character array containing contents
1104 C of Local Section 2, if included
1105 C gfld%locallen = length of array gfld%local()
1106 C gfld%ifldnum = field number within GRIB message
1107 C gfld%griddef = Source of grid definition (see Code Table 3.0)
1108 C 0 - Specified in Code table 3.1
1109 C 1 - Predetermined grid Defined by originating centre
1110 C gfld%ngrdpts = Number of grid points in the defined grid.
1111 C gfld%numoct_opt = Number of octets needed for each
1112 C additional grid points definition.
1113 C Used to define number of
1114 C points in each row ( or column ) for
1115 C non-regular grids.
1116 C = 0, if using regular grid.
1117 C gfld%interp_opt = Interpretation of list for optional points
1118 C definition. (Code Table 3.11)
1119 C gfld%igdtnum = Grid Definition Template Number (Code Table 3.1)
1120 C gfld%igdtmpl() = Contains the data values for the specified Grid
1121 C Definition Template ( NN=gfld%igdtnum ). Each
1122 C element of this integer array contains an entry (in
1123 C the order specified) of Grid Defintion Template 3.NN
1124 C This element is actually a pointer to an array
1125 C that holds the data.
1126 C gfld%igdtlen = Number of elements in gfld%igdtmpl(). i.e. number of
1127 C entries in Grid Defintion Template 3.NN
1128 C ( NN=gfld%igdtnum ).
1129 C gfld%list_opt() = (Used if gfld%numoct_opt .ne. 0) This array
1130 C contains the number of grid points contained in
1131 C each row ( or column ). (part of Section 3)
1132 C This element is actually a pointer to an array
1133 C that holds the data. This pointer is nullified
1134 C if gfld%numoct_opt=0.
1135 C gfld%num_opt = (Used if gfld%numoct_opt .ne. 0) The number of entries
1136 C in array ideflist. i.e. number of rows ( or columns )
1137 C for which optional grid points are defined. This value
1138 C is set to zero, if gfld%numoct_opt=0.
1139 C gfdl%ipdtnum = Product Definition Template Number (see Code Table 4.0)
1140 C gfld%ipdtmpl() = Contains the data values for the specified Product
1141 C Definition Template ( N=gfdl%ipdtnum ). Each element
1142 C of this integer array contains an entry (in the
1143 C order specified) of Product Defintion Template 4.N.
1144 C This element is actually a pointer to an array
1145 C that holds the data.
1146 C gfld%ipdtlen = Number of elements in gfld%ipdtmpl(). i.e. number of
1147 C entries in Product Defintion Template 4.N
1148 C ( N=gfdl%ipdtnum ).
1149 C gfld%coord_list() = Real array containing floating point values
1150 C intended to document the vertical discretisation
1151 C associated to model data on hybrid coordinate
1152 C vertical levels. (part of Section 4)
1153 C This element is actually a pointer to an array
1154 C that holds the data.
1155 C gfld%num_coord = number of values in array gfld%coord_list().
1156 C gfld%ndpts = Number of data points unpacked and returned.
1157 C gfld%idrtnum = Data Representation Template Number
1158 C ( see Code Table 5.0)
1159 C gfld%idrtmpl() = Contains the data values for the specified Data
1160 C Representation Template ( N=gfld%idrtnum ). Each
1161 C element of this integer array contains an entry
1162 C (in the order specified) of Product Defintion
1163 C Template 5.N.
1164 C This element is actually a pointer to an array
1165 C that holds the data.
1166 C gfld%idrtlen = Number of elements in gfld%idrtmpl(). i.e. number
1167 C of entries in Data Representation Template 5.N
1168 C ( N=gfld%idrtnum ).
1169 C gfld%unpacked = logical value indicating whether the bitmap and
1170 C data values were unpacked. If false,
1171 C gfld%bmap and gfld%fld pointers are nullified.
1172 C gfld%expanded = Logical value indicating whether the data field
1173 C was expanded to the grid in the case where a
1174 C bit-map is present. If true, the data points in
1175 C gfld%fld match the grid points and zeros were
1176 C inserted at grid points where data was bit-mapped
1177 C out. If false, the data values in gfld%fld were
1178 C not expanded to the grid and are just a consecutive
1179 C array of data points corresponding to each value of
1180 C "1" in gfld%bmap.
1181 C gfld%ibmap = Bitmap indicator ( see Code Table 6.0 )
1182 C 0 = bitmap applies and is included in Section 6.
1183 C 1-253 = Predefined bitmap applies
1184 C 254 = Previously defined bitmap applies to this field
1185 C 255 = Bit map does not apply to this product.
1186 C gfld%bmap() = Logical*1 array containing decoded bitmap,
1187 C if ibmap=0 or ibap=254. Otherwise nullified.
1188 C This element is actually a pointer to an array
1189 C that holds the data.
1190 C gfld%fld() = Array of gfld%ndpts unpacked data points.
1191 C This element is actually a pointer to an array
1192 C that holds the data.
1193 C IRET INTEGER RETURN CODE
1194 C 0 ALL OK
1195 C 96 ERROR READING INDEX
1196 C 97 ERROR READING GRIB FILE
1197 C 99 REQUEST NOT FOUND
1198 C OTHER GF_GETFLD GRIB2 UNPACKER RETURN CODE
1199 C
1200 C SUBPROGRAMS CALLED:
1201 C GETIDX GET INDEX
1202 C GETGB2S SEARCH INDEX RECORDS
1203 C GETGB2R READ AND UNPACK GRIB RECORD
1204 C GF_FREE FREES MEMORY USED BY GFLD ( SEE REMARKS )
1205 C
1206 C REMARKS: SPECIFY AN INDEX FILE IF FEASIBLE TO INCREASE SPEED.
1207 C DO NOT ENGAGE THE SAME LOGICAL UNIT FROM MORE THAN ONE PROCESSOR.
1208 C
1209 C Note that derived type gribfield contains pointers to many
1210 C arrays of data. The memory for these arrays is allocated
1211 C when the values in the arrays are set, to help minimize
1212 C problems with array overloading. Because of this users
1213 C are encouraged to free up this memory, when it is no longer
1214 C needed, by an explicit call to subroutine gf_free.
1215 C ( i.e. CALL GF_FREE(GFLD) )
1216 C
1217 C ATTRIBUTES:
1218 C LANGUAGE: FORTRAN 90
1219 C
1220 C$$$