| blob | fad4c2bf74b8a3d7859c63e727c39fd767494205 |
1 C-----------------------------------------------------------------------
2 SUBROUTINE GETGB2(LUGB,LUGI,J,GUESS,JDISC,JIDS,JPDTN,JPDT,JGDTN,
3 & JGDT,UNPACK,K,GFLD,IRET)
4 C$$$ SUBPROGRAM DOCUMENTATION BLOCK
5 C
6 C SUBPROGRAM: GETGB2 FINDS AND UNPACKS A GRIB MESSAGE
7 C PRGMMR: IREDELL ORG: W/NMC23 DATE: 94-04-01
8 C
9 C ABSTRACT: FIND AND UNPACK A GRIB MESSAGE.
10 C READ A GRIB INDEX FILE (OR OPTIONALLY THE GRIB FILE ITSELF)
11 C TO GET THE INDEX BUFFER (I.E. TABLE OF CONTENTS) FOR THE GRIB FILE.
12 C FIND IN THE INDEX BUFFER A REFERENCE TO THE GRIB FIELD REQUESTED.
13 C THE GRIB FIELD REQUEST SPECIFIES THE NUMBER OF FIELDS TO SKIP
14 C AND THE UNPACKED IDENTIFICATION SECTION, GRID DEFINITION TEMPLATE AND
15 C PRODUCT DEFINTION SECTION PARAMETERS. (A REQUESTED PARAMETER
16 C OF -9999 MEANS TO ALLOW ANY VALUE OF THIS PARAMETER TO BE FOUND.)
17 C IF THE REQUESTED GRIB FIELD IS FOUND, THEN IT IS READ FROM THE
18 C GRIB FILE AND UNPACKED. ITS NUMBER IS RETURNED ALONG WITH
19 C THE ASSOCIATED UNPACKED PARAMETERS. THE BITMAP (IF ANY),
20 C AND THE DATA VALUES ARE UNPACKED ONLY IF ARGUMENT "UNPACK" IS SET TO
21 C TRUE. IF THE GRIB FIELD IS NOT FOUND, THEN THE
22 C RETURN CODE WILL BE NONZERO.
23 C
24 C The decoded information for the selected GRIB field
25 C is returned in a derived type variable, gfld.
26 C Gfld is of type gribfield, which is defined
27 C in module grib_mod, so users of this routine will need to include
28 C the line "USE GRIB_MOD" in their calling routine. Each component of the
29 C gribfield type is described in the OUTPUT ARGUMENT LIST section below.
30 C
31 C PROGRAM HISTORY LOG:
32 C 94-04-01 IREDELL
33 C 95-10-31 IREDELL MODULARIZED PORTIONS OF CODE INTO SUBPROGRAMS
34 C AND ALLOWED FOR UNSPECIFIED INDEX FILE
35 C 2002-01-11 GILBERT MODIFIED FROM GETGB AND GETGBM TO WORK WITH GRIB2
36 C
37 C USAGE: CALL GETGB2(LUGB,LUGI,J,JDISC,JIDS,JPDTN,JPDT,JGDTN,JGDT,
38 C & UNPACK,K,GFLD,IRET)
39 C INPUT ARGUMENTS:
40 C LUGB INTEGER UNIT OF THE UNBLOCKED GRIB DATA FILE.
41 C FILE MUST BE OPENED WITH BAOPEN OR BAOPENR BEFORE CALLING
42 C THIS ROUTINE.
43 C LUGI INTEGER UNIT OF THE UNBLOCKED GRIB INDEX FILE.
44 C IF NONZERO, FILE MUST BE OPENED WITH BAOPEN BAOPENR BEFORE
45 C CALLING THIS ROUTINE.
46 C >0 - READ INDEX FROM INDEX FILE LUGI, IF INDEX DOESN"T
47 C ALREADY EXIST.
48 C =0 - TO GET INDEX BUFFER FROM THE GRIB FILE, IF INDEX
49 C DOESN"T ALREADY EXIST.
50 C <0 - FORCE REREAD OF INDEX FROM INDEX FILE ABS(LUGI).
51 C =LUGB - FORCE REGENERATION OF INDEX FROM GRIB2 FILE LUGB.
52 C J INTEGER NUMBER OF FIELDS TO SKIP
53 C (=0 TO SEARCH FROM BEGINNING)
54 C JDISC GRIB2 DISCIPLINE NUMBER OF REQUESTED FIELD
55 C ( IF = -1, ACCEPT ANY DISCIPLINE)
56 C ( SEE CODE TABLE 0.0 )
57 C 0 - Meteorological products
58 C 1 - Hydrological products
59 C 2 - Land surface products
60 C 3 - Space products
61 C 10 - Oceanographic products
62 C JIDS() INTEGER ARRAY OF VALUES IN THE IDENTIFICATION SECTION
63 C (=-9999 FOR WILDCARD)
64 C JIDS(1) = IDENTIFICATION OF ORIGINATING CENTRE
65 C ( SEE COMMON CODE TABLE C-1 )
66 C JIDS(2) = IDENTIFICATION OF ORIGINATING SUB-CENTRE
67 C JIDS(3) = GRIB MASTER TABLES VERSION NUMBER
68 C ( SEE CODE TABLE 1.0 )
69 C 0 - Experimental
70 C 1 - Initial operational version number
71 C JIDS(4) = GRIB LOCAL TABLES VERSION NUMBER
72 C ( SEE CODE TABLE 1.1 )
73 C 0 - Local tables not used
74 C 1-254 - Number of local tables version used
75 C JIDS(5) = SIGNIFICANCE OF REFERENCE TIME (CODE TABLE 1.2)
76 C 0 - Analysis
77 C 1 - Start of forecast
78 C 2 - Verifying time of forecast
79 C 3 - Observation time
80 C JIDS(6) = YEAR ( 4 DIGITS )
81 C JIDS(7) = MONTH
82 C JIDS(8) = DAY
83 C JIDS(9) = HOUR
84 C JIDS(10) = MINUTE
85 C JIDS(11) = SECOND
86 C JIDS(12) = PRODUCTION STATUS OF PROCESSED DATA
87 C ( SEE CODE TABLE 1.3 )
88 C 0 - Operational products
89 C 1 - Operational test products
90 C 2 - Research products
91 C 3 - Re-analysis products
92 C JIDS(13) = TYPE OF PROCESSED DATA ( SEE CODE TABLE 1.4 )
93 C 0 - Analysis products
94 C 1 - Forecast products
95 C 2 - Analysis and forecast products
96 C 3 - Control forecast products
97 C 4 - Perturbed forecast products
98 C 5 - Control and perturbed forecast products
99 C 6 - Processed satellite observations
100 C 7 - Processed radar observations
101 C JPDTN INTEGER PRODUCT DEFINITION TEMPLATE NUMBER (N)
102 C ( IF = -1, DON'T BOTHER MATCHING PDT - ACCEPT ANY )
103 C JPDT() INTEGER ARRAY OF VALUES DEFINING THE PRODUCT DEFINITION
104 C TEMPLATE 4.N OF THE FIELD FOR WHICH TO SEARCH
105 C (=-9999 FOR WILDCARD)
106 C JGDTN INTEGER GRID DEFINITION TEMPLATE NUMBER (M)
107 C ( IF = -1, DON'T BOTHER MATCHING GDT - ACCEPT ANY )
108 C JGDT() INTEGER ARRAY OF VALUES DEFINING THE GRID DEFINITION
109 C TEMPLATE 3.M OF THE FIELD FOR WHICH TO SEARCH
110 C (=-9999 FOR WILDCARD)
111 C UNPACK LOGICAL VALUE INDICATING WHETHER TO UNPACK BITMAP/DATA
112 C .TRUE. = UNPACK BITMAP AND DATA VALUES
113 C .FALSE. = DO NOT UNPACK BITMAP AND DATA VALUES
114 C
115 C OUTPUT ARGUMENTS:
116 C K INTEGER FIELD NUMBER UNPACKED
117 C gfld - derived type gribfield ( defined in module grib_mod )
118 C ( NOTE: See Remarks Section )
119 C gfld%version = GRIB edition number ( currently 2 )
120 C gfld%discipline = Message Discipline ( see Code Table 0.0 )
121 C gfld%idsect() = Contains the entries in the Identification
122 C Section ( Section 1 )
123 C This element is actually a pointer to an array
124 C that holds the data.
125 C gfld%idsect(1) = Identification of originating Centre
126 C ( see Common Code Table C-1 )
127 C 7 - US National Weather Service
128 C gfld%idsect(2) = Identification of originating Sub-centre
129 C gfld%idsect(3) = GRIB Master Tables Version Number
130 C ( see Code Table 1.0 )
131 C 0 - Experimental
132 C 1 - Initial operational version number
133 C gfld%idsect(4) = GRIB Local Tables Version Number
134 C ( see Code Table 1.1 )
135 C 0 - Local tables not used
136 C 1-254 - Number of local tables version used
137 C gfld%idsect(5) = Significance of Reference Time (Code Table 1.2)
138 C 0 - Analysis
139 C 1 - Start of forecast
140 C 2 - Verifying time of forecast
141 C 3 - Observation time
142 C gfld%idsect(6) = Year ( 4 digits )
143 C gfld%idsect(7) = Month
144 C gfld%idsect(8) = Day
145 C gfld%idsect(9) = Hour
146 C gfld%idsect(10) = Minute
147 C gfld%idsect(11) = Second
148 C gfld%idsect(12) = Production status of processed data
149 C ( see Code Table 1.3 )
150 C 0 - Operational products
151 C 1 - Operational test products
152 C 2 - Research products
153 C 3 - Re-analysis products
154 C gfld%idsect(13) = Type of processed data ( see Code Table 1.4 )
155 C 0 - Analysis products
156 C 1 - Forecast products
157 C 2 - Analysis and forecast products
158 C 3 - Control forecast products
159 C 4 - Perturbed forecast products
160 C 5 - Control and perturbed forecast products
161 C 6 - Processed satellite observations
162 C 7 - Processed radar observations
163 C gfld%idsectlen = Number of elements in gfld%idsect().
164 C gfld%local() = Pointer to character array containing contents
165 C of Local Section 2, if included
166 C gfld%locallen = length of array gfld%local()
167 C gfld%ifldnum = field number within GRIB message
168 C gfld%griddef = Source of grid definition (see Code Table 3.0)
169 C 0 - Specified in Code table 3.1
170 C 1 - Predetermined grid Defined by originating centre
171 C gfld%ngrdpts = Number of grid points in the defined grid.
172 C gfld%numoct_opt = Number of octets needed for each
173 C additional grid points definition.
174 C Used to define number of
175 C points in each row ( or column ) for
176 C non-regular grids.
177 C = 0, if using regular grid.
178 C gfld%interp_opt = Interpretation of list for optional points
179 C definition. (Code Table 3.11)
180 C gfld%igdtnum = Grid Definition Template Number (Code Table 3.1)
181 C gfld%igdtmpl() = Contains the data values for the specified Grid
182 C Definition Template ( NN=gfld%igdtnum ). Each
183 C element of this integer array contains an entry (in
184 C the order specified) of Grid Defintion Template 3.NN
185 C This element is actually a pointer to an array
186 C that holds the data.
187 C gfld%igdtlen = Number of elements in gfld%igdtmpl(). i.e. number of
188 C entries in Grid Defintion Template 3.NN
189 C ( NN=gfld%igdtnum ).
190 C gfld%list_opt() = (Used if gfld%numoct_opt .ne. 0) This array
191 C contains the number of grid points contained in
192 C each row ( or column ). (part of Section 3)
193 C This element is actually a pointer to an array
194 C that holds the data. This pointer is nullified
195 C if gfld%numoct_opt=0.
196 C gfld%num_opt = (Used if gfld%numoct_opt .ne. 0) The number of entries
197 C in array ideflist. i.e. number of rows ( or columns )
198 C for which optional grid points are defined. This value
199 C is set to zero, if gfld%numoct_opt=0.
200 C gfdl%ipdtnum = Product Definition Template Number (see Code Table 4.0)
201 C gfld%ipdtmpl() = Contains the data values for the specified Product
202 C Definition Template ( N=gfdl%ipdtnum ). Each element
203 C of this integer array contains an entry (in the
204 C order specified) of Product Defintion Template 4.N.
205 C This element is actually a pointer to an array
206 C that holds the data.
207 C gfld%ipdtlen = Number of elements in gfld%ipdtmpl(). i.e. number of
208 C entries in Product Defintion Template 4.N
209 C ( N=gfdl%ipdtnum ).
210 C gfld%coord_list() = Real array containing floating point values
211 C intended to document the vertical discretisation
212 C associated to model data on hybrid coordinate
213 C vertical levels. (part of Section 4)
214 C This element is actually a pointer to an array
215 C that holds the data.
216 C gfld%num_coord = number of values in array gfld%coord_list().
217 C gfld%ndpts = Number of data points unpacked and returned.
218 C gfld%idrtnum = Data Representation Template Number
219 C ( see Code Table 5.0)
220 C gfld%idrtmpl() = Contains the data values for the specified Data
221 C Representation Template ( N=gfld%idrtnum ). Each
222 C element of this integer array contains an entry
223 C (in the order specified) of Product Defintion
224 C Template 5.N.
225 C This element is actually a pointer to an array
226 C that holds the data.
227 C gfld%idrtlen = Number of elements in gfld%idrtmpl(). i.e. number
228 C of entries in Data Representation Template 5.N
229 C ( N=gfld%idrtnum ).
230 C gfld%unpacked = logical value indicating whether the bitmap and
231 C data values were unpacked. If false,
232 C gfld%bmap and gfld%fld pointers are nullified.
233 C gfld%expanded = Logical value indicating whether the data field
234 C was expanded to the grid in the case where a
235 C bit-map is present. If true, the data points in
236 C gfld%fld match the grid points and zeros were
237 C inserted at grid points where data was bit-mapped
238 C out. If false, the data values in gfld%fld were
239 C not expanded to the grid and are just a consecutive
240 C array of data points corresponding to each value of
241 C "1" in gfld%bmap.
242 C gfld%ibmap = Bitmap indicator ( see Code Table 6.0 )
243 C 0 = bitmap applies and is included in Section 6.
244 C 1-253 = Predefined bitmap applies
245 C 254 = Previously defined bitmap applies to this field
246 C 255 = Bit map does not apply to this product.
247 C gfld%bmap() = Logical*1 array containing decoded bitmap,
248 C if ibmap=0 or ibap=254. Otherwise nullified.
249 C This element is actually a pointer to an array
250 C that holds the data.
251 C gfld%fld() = Array of gfld%ndpts unpacked data points.
252 C This element is actually a pointer to an array
253 C that holds the data.
254 C IRET INTEGER RETURN CODE
255 C 0 ALL OK
256 C 96 ERROR READING INDEX
257 C 97 ERROR READING GRIB FILE
258 C 99 REQUEST NOT FOUND
259 C OTHER GF_GETFLD GRIB2 UNPACKER RETURN CODE
260 C
261 C SUBPROGRAMS CALLED:
262 C GETIDX GET INDEX
263 C GETGB2S SEARCH INDEX RECORDS
264 C GETGB2R READ AND UNPACK GRIB RECORD
265 C GF_FREE FREES MEMORY USED BY GFLD ( SEE REMARKS )
266 C
267 C REMARKS: SPECIFY AN INDEX FILE IF FEASIBLE TO INCREASE SPEED.
268 C DO NOT ENGAGE THE SAME LOGICAL UNIT FROM MORE THAN ONE PROCESSOR.
269 C
270 C Note that derived type gribfield contains pointers to many
271 C arrays of data. The memory for these arrays is allocated
272 C when the values in the arrays are set, to help minimize
273 C problems with array overloading. Because of this users
274 C are encouraged to free up this memory, when it is no longer
275 C needed, by an explicit call to subroutine gf_free.
276 C ( i.e. CALL GF_FREE(GFLD) )
277 C
278 C ATTRIBUTES:
279 C LANGUAGE: FORTRAN 90
280 C
281 C$$$
282 USE GRIB_MOD
284 INTEGER,INTENT(IN) :: LUGB,LUGI,J,JDISC,JPDTN,JGDTN
285 INTEGER,INTENT(IN) :: GUESS
286 INTEGER,DIMENSION(:) :: JIDS(*),JPDT(*),JGDT(*)
287 LOGICAL,INTENT(IN) :: UNPACK
288 INTEGER,INTENT(OUT) :: K,IRET
289 TYPE(GRIBFIELD),INTENT(OUT) :: GFLD
291 CHARACTER(LEN=1),POINTER,DIMENSION(:) :: CBUF
293 C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
294 C DECLARE INTERFACES (REQUIRED FOR CBUF POINTER)
295 INTERFACE
296 SUBROUTINE GETIDX(LUGB,LUGI,CBUF,NLEN,NNUM,IRGI)
297 CHARACTER(LEN=1),POINTER,DIMENSION(:) :: CBUF
298 INTEGER,INTENT(IN) :: LUGB,LUGI
299 INTEGER,INTENT(OUT) :: NLEN,NNUM,IRGI
300 END SUBROUTINE GETIDX
301 END INTERFACE
302 C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
303 C DETERMINE WHETHER INDEX BUFFER NEEDS TO BE INITIALIZED
304 IRGI=0
305 CALL GETIDX(LUGB,LUGI,CBUF,NLEN,NNUM,IRGI)
306 IF(IRGI.GT.1) THEN
307 IRET=96
308 RETURN
309 ENDIF
310 C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
311 C SEARCH INDEX BUFFER
312 CALL GETGB2S(CBUF,NLEN,NNUM,J,GUESS,JDISC,JIDS,JPDTN,JPDT,JGDTN,
313 & JGDT,JK,GFLD,LPOS,IRGS)
314 IF(IRGS.NE.0) THEN
315 IRET=99
316 CALL GF_FREE(GFLD)
317 RETURN
318 ENDIF
320 C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
321 C READ LOCAL USE SECTION, IF AVAILABLE
322 CALL GETGB2L(LUGB,CBUF(LPOS),GFLD,IRET)
323 C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
324 C READ AND UNPACK GRIB RECORD
325 IF (UNPACK) THEN
326 ! NUMFLD=GFLD%IFLDNUM
327 ! CALL GF_FREE(GFLD)
328 CALL GETGB2R(LUGB,CBUF(LPOS),GFLD,IRET)
329 ENDIF
330 K=JK
331 C - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
332 RETURN
333 END