Debian Codegraph @

frmts/grib/degrib/g2clib/grib2c.doc

raw
1 GRIB2 USERS GUIDE (C)
2
3 Contents:
4
5 - Introduction
6 - GRIB2 Tables/Templates
7 - GRIB2 Encoding Routines
8 - GRIB2 Decoding Routines
9 - Decoding all GRIB2 Fields in a File
10 - Extracting Selected GRIB2 Fields from a GRIB2 file
11 - GRIB2 Routine Documentation
12
13 ===============================================================================
14
15 Introduction
16
17 This document briefly describes the routines available for encoding/decoding
18 GRIB Edition 2 (GRIB2) messages. A basic familiarity with GRIB is assumed.
19
20 A GRIB Edition 2 message is a machine independent format for storing
21 one or more gridded data fields. Each GRIB2 message consists of the
22 following sections:
23
24 SECTION 0 - Indicator Section
25 SECTION 1 - Identification Section
26 SECTION 2 - (Local Use Section) - optional }
27 SECTION 3 - Grid Definition Section } }
28 SECTION 4 - Product Definition Section } } }(repeated)
29 SECTION 5 - Data Representation Section } }(repeated) }
30 SECTION 6 - Bit-map Section }(repeated) } }
31 SECTION 7 - Data Section } } }
32 SECTION 8 - End Section } } }
33
34 Sequences of GRIB sections 2 to 7, 3 to 7, or sections 4 to 7 may be repeated
35 within a single GRIB message. All sections within such repeated sequences
36 must be present and shall appear in the numerical order noted above.
37 Unrepeated sections remain in effect until redefined.
38
39 The above overview was taken from WMO's FM 92-XII GRIB description
40 of the GRIB Edition 2 form.
41
42 ===============================================================================
43
44 GRIB2 Tables/Templates
45
46 WMO's GRIB2 specification "FM 92-XII GRIB - General Regularly-distributed
47 Information in Binary Form" contains descriptions of each template
48 and code table information. This document can be found at
49 http://www.wmo.ch/web/www/WMOCodes.html
50 (PDF and MSWord formats are available)
51
52 ===============================================================================
53
54 GRIB2 Encoding Routines
55
56 Since a GRIB2 message can contain gridded fields for many parameters on
57 a number of different grids, several routines are used to encode a message.
58 This should give users more flexibility in how to organize data
59 within one or more GRIB2 messages.
60
61 To start a new GRIB2 message, call function g2_create. G2_create
62 encodes Sections 0 and 1 at the beginning of the message. This routine
63 must be used to create each message.
64
65 Routine g2_addlocal can be used to add a Local Use Section ( Section 2 ).
66 Note that this section is optional and need not appear in a GRIB2 message.
67
68 Function g2_addgrid is used to encode a grid definition into Section 3.
69 This grid definition defines the geometry of the data values in the
70 fields that follow it. g2_addgrid can be called again to change the grid
71 definition describing subsequent data fields.
72
73 Each data field is added to the GRIB2 message using routine g2_addfield,
74 which adds Sections 4, 5, 6, and 7 to the message.
75
76 After all desired data fields have been added to the GRIB2 message, a
77 call to function g2_gribend is needed to add the final section 8 to the
78 message and to update the length of the message. A call to g2_gribend
79 is required for each GRIB2 message.
80
81 Please see the "GRIB2 Routine Documentation" section below for subroutine
82 argument usage for the routines mentioned above.
83
84 ===============================================================================
85
86 GRIB2 Decoding Routines
87
88 Routine g2_info can be used to find out how many Local Use sections
89 and data fields are contained in a given GRIB2 message. This routine also
90 returns all the information stored in Sections 0 and 1 of the GRIB2
91 message.
92
93 g2_getfld can be used to get all information pertaining to the nth
94 data field in the message. The subroutine returns all the unpacked metadata
95 for each Section and Template in a gribfield structure,
96 which is defined in include file grib2.h. An option exists that lets the
97 user decide if the decoder should unpack the Bit-map ( if applicable )
98 and the data values or just return the field description information.
99
100 Note that a struct gribfield is allocated by g2_getfld, and it also
101 contains pointers to many arrays of data that are allocated during decoding.
102 Because of this, users are encouraged to free up this memory, when it is
103 no longer needed, by an explicit call to routine g2_free.
104
105 Please see the "GRIB2 Routine Documentation" section below for subroutine
106 argument usage for the routines mentioned above.
107
108 ===============================================================================
109 Decoding all GRIB2 Fields in a File
110
111 Routines seekgb, g2_info and g2_getfld can be used to sequentially decode
112 all the GRIB2 fields in a file. This is illustrated by the following example:
113
114 #include <stdio.h>
115 #include <stdlib.h>
116 #include "grib2.h"
117
118 unsigned char *cgrib;
119 g2int listsec0[3],listsec1[13],numlocal,numfields;
120 long lskip,n,lgrib,iseek;
121 int unpack,ret,ierr;
122 gribfield *gfld;
123 FILE *fptr;
124 size_t lengrib;
125
126 iseek=0;
127 unpack=1;
128 expand=1;
129 fptr=fopen("inputgribfile","r");
130 for (;;) {
131 seekgb(fptr,iseek,32000,&lskip,&lgrib);
132 if (lgrib == 0) break; // end loop at EOF or problem
133 cgrib=(unsigned char *)malloc(lgrib);
134 ret=fseek(fptr,lskip,SEEK_SET);
135 lengrib=fread(cgrib,sizeof(unsigned char),lgrib,fptr);
136 iseek=lskip+lgrib;
137 ierr=g2_info(cgrib,listsec0,listsec1,&numfields,&numlocal);
138 for (n=0;n<numfields;n++) {
139 ierr=g2_getfld(cgrib,n+1,unpack,expand,&gfld);
140 .
141 . // Process Field Here
142 .
143 g2_free(gfld);
144 }
145 free(cgrib);
146 }
147
148
149 ===============================================================================
150
151 Extracting Selected GRIB2 Fields from a GRIB2 File
152
153 This feature not implemented in the "C" version of the GRIB2
154 library yet.
155
156 ===============================================================================
157
158 GRIB2 Routine Documentation
159
160 ////////////////// grib2.h ///////////////////////////////////////////
161 // . . . .
162 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-10-25
163 //
164 // Each element of structure gribfield is defined as:
165 //
166 // gribfield gfld;
167 //
168 // gfld->version = GRIB edition number ( currently 2 )
169 // gfld->discipline = Message Discipline ( see Code Table 0.0 )
170 // gfld->idsect = Contains the entries in the Identification
171 // Section ( Section 1 )
172 // This element is a pointer to an array
173 // that holds the data.
174 // gfld->idsect[0] = Identification of originating Centre
175 // ( see Common Code Table C-1 )
176 // 7 - US National Weather Service
177 // gfld->idsect[1] = Identification of originating Sub-centre
178 // gfld->idsect[2] = GRIB Master Tables Version Number
179 // ( see Code Table 1.0 )
180 // 0 - Experimental
181 // 1 - Initial operational version number
182 // gfld->idsect[3] = GRIB Local Tables Version Number
183 // ( see Code Table 1.1 )
184 // 0 - Local tables not used
185 // 1-254 - Number of local tables version used
186 // gfld->idsect[4] = Significance of Reference Time (Code Table 1.2)
187 // 0 - Analysis
188 // 1 - Start of forecast
189 // 2 - Verifying time of forecast
190 // 3 - Observation time
191 // gfld->idsect[5] = Year ( 4 digits )
192 // gfld->idsect[6] = Month
193 // gfld->idsect[7) = Day
194 // gfld->idsect[8] = Hour
195 // gfld->idsect[9] = Minute
196 // gfld->idsect[10] = Second
197 // gfld->idsect[11] = Production status of processed data
198 // ( see Code Table 1.3 )
199 // 0 - Operational products
200 // 1 - Operational test products
201 // 2 - Research products
202 // 3 - Re-analysis products
203 // gfld->idsect[12] = Type of processed data ( see Code Table 1.4 )
204 // 0 - Analysis products
205 // 1 - Forecast products
206 // 2 - Analysis and forecast products
207 // 3 - Control forecast products
208 // 4 - Perturbed forecast products
209 // 5 - Control and perturbed forecast products
210 // 6 - Processed satellite observations
211 // 7 - Processed radar observations
212 // gfld->idsectlen = Number of elements in gfld->idsect[].
213 // gfld->local = Pointer to character array containing contents
214 // of Local Section 2, if included
215 // gfld->locallen = length of array gfld->local[]
216 // gfld->ifldnum = field number within GRIB message
217 // gfld->griddef = Source of grid definition (see Code Table 3.0)
218 // 0 - Specified in Code table 3.1
219 // 1 - Predetermined grid Defined by originating centre
220 // gfld->ngrdpts = Number of grid points in the defined grid.
221 // gfld->numoct_opt = Number of octets needed for each
222 // additional grid points definition.
223 // Used to define number of
224 // points in each row ( or column ) for
225 // non-regular grids.
226 // = 0, if using regular grid.
227 // gfld->interp_opt = Interpretation of list for optional points
228 // definition. (Code Table 3.11)
229 // gfld->igdtnum = Grid Definition Template Number (Code Table 3.1)
230 // gfld->igdtmpl = Contains the data values for the specified Grid
231 // Definition Template ( NN=gfld->igdtnum ). Each
232 // element of this integer array contains an entry (in
233 // the order specified) of Grid Definition Template 3.NN
234 // This element is a pointer to an array
235 // that holds the data.
236 // gfld->igdtlen = Number of elements in gfld->igdtmpl[]. i.e. number of
237 // entries in Grid Definition Template 3.NN
238 // ( NN=gfld->igdtnum ).
239 // gfld->list_opt = (Used if gfld->numoct_opt .ne. 0) This array
240 // contains the number of grid points contained in
241 // each row ( or column ). (part of Section 3)
242 // This element is a pointer to an array
243 // that holds the data. This pointer is nullified
244 // if gfld->numoct_opt=0.
245 // gfld->num_opt = (Used if gfld->numoct_opt .ne. 0)
246 // The number of entries
247 // in array ideflist. i.e. number of rows ( or columns )
248 // for which optional grid points are defined. This value
249 // is set to zero, if gfld->numoct_opt=0.
250 // gfdl->ipdtnum = Product Definition Template Number(see Code Table 4.0)
251 // gfld->ipdtmpl = Contains the data values for the specified Product
252 // Definition Template ( N=gfdl->ipdtnum ). Each element
253 // of this integer array contains an entry (in the
254 // order specified) of Product Definition Template 4.N.
255 // This element is a pointer to an array
256 // that holds the data.
257 // gfld->ipdtlen = Number of elements in gfld->ipdtmpl[]. i.e. number of
258 // entries in Product Definition Template 4.N
259 // ( N=gfdl->ipdtnum ).
260 // gfld->coord_list = Real array containing floating point values
261 // intended to document the vertical discretisation
262 // associated to model data on hybrid coordinate
263 // vertical levels. (part of Section 4)
264 // This element is a pointer to an array
265 // that holds the data.
266 // gfld->num_coord = number of values in array gfld->coord_list[].
267 // gfld->ndpts = Number of data points unpacked and returned.
268 // gfld->idrtnum = Data Representation Template Number
269 // ( see Code Table 5.0)
270 // gfld->idrtmpl = Contains the data values for the specified Data
271 // Representation Template ( N=gfld->idrtnum ). Each
272 // element of this integer array contains an entry
273 // (in the order specified) of Product Definition
274 // Template 5.N.
275 // This element is a pointer to an array
276 // that holds the data.
277 // gfld->idrtlen = Number of elements in gfld->idrtmpl[]. i.e. number
278 // of entries in Data Representation Template 5.N
279 // ( N=gfld->idrtnum ).
280 // gfld->unpacked = logical value indicating whether the bitmap and
281 // data values were unpacked. If false,
282 // gfld->bmap and gfld->fld pointers are nullified.
283 // gfld->expanded = Logical value indicating whether the data field
284 // was expanded to the grid in the case where a
285 // bit-map is present. If true, the data points in
286 // gfld->fld match the grid points and zeros were
287 // inserted at grid points where data was bit-mapped
288 // out. If false, the data values in gfld->fld were
289 // not expanded to the grid and are just a consecutive
290 // array of data points corresponding to each value of
291 // "1" in gfld->bmap.
292 // gfld->ibmap = Bitmap indicator ( see Code Table 6.0 )
293 // 0 = bitmap applies and is included in Section 6.
294 // 1-253 = Predefined bitmap applies
295 // 254 = Previously defined bitmap applies to this field
296 // 255 = Bit map does not apply to this product.
297 // gfld->bmap = integer array containing decoded bitmap,
298 // if gfld->ibmap=0 or gfld->ibap=254.
299 // Otherwise nullified.
300 // This element is a pointer to an array
301 // that holds the data.
302 // gfld->fld = Array of gfld->ndpts unpacked data points.
303 // This element is a pointer to an array
304 // that holds the data.
305 ///////////////////////////////////////////////////////////////////////////
306
307
308
309 //$$$ SUBPROGRAM DOCUMENTATION BLOCK ////////////////////////////////////
310 //
311 // SUBPROGRAM: seekgb Searches a file for the next GRIB message.
312 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-10-28
313 //
314 // ABSTRACT: This subprogram searches a file for the next GRIB Message.
315 // The search is done starting at byte offset iseek of the file referenced
316 // by lugb for mseek bytes at a time.
317 // If found, the starting position and length of the message are returned
318 // in lskip and lgrib, respectively.
319 // The search is terminated when an EOF or I/O error is encountered.
320 //
321 // PROGRAM HISTORY LOG:
322 // 2002-10-28 GILBERT Modified from Iredell's skgb subroutine
323 //
324 // USAGE: seekgb(FILE *lugb,long iseek,long mseek,int *lskip,int *lgrib)
325 // INPUT ARGUMENTS:
326 // lugb - FILE pointer for the file to search. File must be
327 // opened before this routine is called.
328 // iseek - number of bytes in the file to skip before search
329 // mseek - number of bytes to search at a time
330 // OUTPUT ARGUMENTS:
331 // lskip - number of bytes to skip from the beginning of the file
332 // to where the GRIB message starts
333 // lgrib - number of bytes in message (set to 0, if no message found)
334 //
335 // ATTRIBUTES:
336 // LANGUAGE: C
337 //
338 //////////////////////////////////////////////////////////////////////////
339
340
341
342 //$$$ SUBPROGRAM DOCUMENTATION BLOCK ///////////////////////////////////
343 // . . . .
344 // SUBPROGRAM: g2_info
345 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-10-28
346 //
347 // ABSTRACT: This subroutine searches through a GRIB2 message and
348 // returns the number of gridded fields found in the message and
349 // the number (and maximum size) of Local Use Sections.
350 // Also various checks are performed
351 // to see if the message is a valid GRIB2 message.
352 //
353 // PROGRAM HISTORY LOG:
354 // 2002-10-28 Gilbert
355 //
356 // USAGE: int g2_info(unsigned char *cgrib,g2int *listsec0,g2int *listsec1,
357 // g2int *numfields,g2int *numlocal)
358 // INPUT ARGUMENT:
359 // cgrib - Character pointer to the GRIB2 message
360 //
361 // OUTPUT ARGUMENTS:
362 // listsec0 - pointer to an array containing information decoded from
363 // GRIB Indicator Section 0.
364 // Must be allocated with >= 3 elements.
365 // listsec0[0]=Discipline-GRIB Master Table Number
366 // (see Code Table 0.0)
367 // listsec0[1]=GRIB Edition Number (currently 2)
368 // listsec0[2]=Length of GRIB message
369 // listsec1 - pointer to an array containing information read from GRIB
370 // Identification Section 1.
371 // Must be allocated with >= 13 elements.
372 // listsec1[0]=Id of originating centre (Common Code Table C-1)
373 // listsec1[1]=Id of originating sub-centre (local table)
374 // listsec1[2]=GRIB Master Tables Version Number (Code Table 1.0)
375 // listsec1[3]=GRIB Local Tables Version Number
376 // listsec1[4]=Significance of Reference Time (Code Table 1.1)
377 // listsec1[5]=Reference Time - Year (4 digits)
378 // listsec1[6]=Reference Time - Month
379 // listsec1[7]=Reference Time - Day
380 // listsec1[8]=Reference Time - Hour
381 // listsec1[9]=Reference Time - Minute
382 // listsec1[10]=Reference Time - Second
383 // listsec1[11]=Production status of data (Code Table 1.2)
384 // listsec1[12]=Type of processed data (Code Table 1.3)
385 // numfields- The number of gridded fields found in the GRIB message.
386 // That is, the number of occurrences of Sections 4 - 7.
387 // numlocal - The number of Local Use Sections ( Section 2 ) found in
388 // the GRIB message.
389 //
390 // RETURN VALUES:
391 // ierr - Error return code.
392 // 0 = no error
393 // 1 = Beginning characters "GRIB" not found.
394 // 2 = GRIB message is not Edition 2.
395 // 3 = Could not find Section 1, where expected.
396 // 4 = End string "7777" found, but not where expected.
397 // 5 = End string "7777" not found at end of message.
398 // 6 = Invalid section number found.
399 //
400 // REMARKS: None
401 //
402 // ATTRIBUTES:
403 // LANGUAGE: C
404 // MACHINE:
405 //
406 //////////////////////////////////////////////////////////////////////////
407
408
409
410 //$$$ SUBPROGRAM DOCUMENTATION BLOCK ///////////////////////////////////
411 // . . . .
412 // SUBPROGRAM: g2_getfld
413 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-10-28
414 //
415 // ABSTRACT: This subroutine returns all the metadata, template values,
416 // Bit-map ( if applicable ), and the unpacked data for a given data
417 // field. All of the information returned is stored in a gribfield
418 // structure, which is defined in file grib2.h.
419 // Users of this routine will need to include "grib2.h" in their source
420 // code that calls this routine. Each component of the gribfield
421 // struct is also described in the OUTPUT ARGUMENTS section below.
422 //
423 // Since there can be multiple data fields packed into a GRIB2
424 // message, the calling routine indicates which field is being requested
425 // with the ifldnum argument.
426 //
427 // PROGRAM HISTORY LOG:
428 // 2002-10-28 Gilbert
429 //
430 // USAGE: #include "grib2.h"
431 // int g2_getfld(unsigned char *cgrib,g2int ifldnum,g2int unpack,
432 // g2int expand,gribfield **gfld)
433 // INPUT ARGUMENTS:
434 // cgrib - Character pointer to the GRIB2 message
435 // ifldnum - Specifies which field in the GRIB2 message to return.
436 // unpack - Boolean value indicating whether to unpack bitmap/data
437 // 1 = unpack bitmap and data values
438 // 0 = do not unpack bitmap and data values
439 // expand - Boolean value indicating whether the data points should be
440 // expanded to the correspond grid, if a bit-map is present.
441 // 1 = if possible, expand data field to grid, inserting zero
442 // values at gridpoints that are bitmapped out.
443 // (SEE REMARKS2)
444 // 0 = do not expand data field, leaving it an array of
445 // consecutive data points for each "1" in the bitmap.
446 // This argument is ignored if unpack == 0 OR if the
447 // returned field does not contain a bit-map.
448 //
449 // OUTPUT ARGUMENT:
450 // gribfield gfld; - pointer to structure gribfield containing
451 // all decoded data for the data field.
452 //
453 // gfld->version = GRIB edition number ( currently 2 )
454 // gfld->discipline = Message Discipline ( see Code Table 0.0 )
455 // gfld->idsect = Contains the entries in the Identification
456 // Section ( Section 1 )
457 // This element is a pointer to an array
458 // that holds the data.
459 // gfld->idsect[0] = Identification of originating Centre
460 // ( see Common Code Table C-1 )
461 // 7 - US National Weather Service
462 // gfld->idsect[1] = Identification of originating Sub-centre
463 // gfld->idsect[2] = GRIB Master Tables Version Number
464 // ( see Code Table 1.0 )
465 // 0 - Experimental
466 // 1 - Initial operational version number
467 // gfld->idsect[3] = GRIB Local Tables Version Number
468 // ( see Code Table 1.1 )
469 // 0 - Local tables not used
470 // 1-254 - Number of local tables version used
471 // gfld->idsect[4] = Significance of Reference Time (Code Table 1.2)
472 // 0 - Analysis
473 // 1 - Start of forecast
474 // 2 - Verifying time of forecast
475 // 3 - Observation time
476 // gfld->idsect[5] = Year ( 4 digits )
477 // gfld->idsect[6] = Month
478 // gfld->idsect[7) = Day
479 // gfld->idsect[8] = Hour
480 // gfld->idsect[9] = Minute
481 // gfld->idsect[10] = Second
482 // gfld->idsect[11] = Production status of processed data
483 // ( see Code Table 1.3 )
484 // 0 - Operational products
485 // 1 - Operational test products
486 // 2 - Research products
487 // 3 - Re-analysis products
488 // gfld->idsect[12] = Type of processed data ( see Code Table 1.4 )
489 // 0 - Analysis products
490 // 1 - Forecast products
491 // 2 - Analysis and forecast products
492 // 3 - Control forecast products
493 // 4 - Perturbed forecast products
494 // 5 - Control and perturbed forecast products
495 // 6 - Processed satellite observations
496 // 7 - Processed radar observations
497 // gfld->idsectlen = Number of elements in gfld->idsect[].
498 // gfld->local = Pointer to character array containing contents
499 // of Local Section 2, if included
500 // gfld->locallen = length of array gfld->local[]
501 // gfld->ifldnum = field number within GRIB message
502 // gfld->griddef = Source of grid definition (see Code Table 3.0)
503 // 0 - Specified in Code table 3.1
504 // 1 - Predetermined grid Defined by originating centre
505 // gfld->ngrdpts = Number of grid points in the defined grid.
506 // gfld->numoct_opt = Number of octets needed for each
507 // additional grid points definition.
508 // Used to define number of
509 // points in each row ( or column ) for
510 // non-regular grids.
511 // = 0, if using regular grid.
512 // gfld->interp_opt = Interpretation of list for optional points
513 // definition. (Code Table 3.11)
514 // gfld->igdtnum = Grid Definition Template Number (Code Table 3.1)
515 // gfld->igdtmpl = Contains the data values for the specified Grid
516 // Definition Template ( NN=gfld->igdtnum ). Each
517 // element of this integer array contains an entry (in
518 // the order specified) of Grid Definition Template 3.NN
519 // This element is a pointer to an array
520 // that holds the data.
521 // gfld->igdtlen = Number of elements in gfld->igdtmpl[]. i.e. number of
522 // entries in Grid Definition Template 3.NN
523 // ( NN=gfld->igdtnum ).
524 // gfld->list_opt = (Used if gfld->numoct_opt .ne. 0) This array
525 // contains the number of grid points contained in
526 // each row ( or column ). (part of Section 3)
527 // This element is a pointer to an array
528 // that holds the data. This pointer is nullified
529 // if gfld->numoct_opt=0.
530 // gfld->num_opt = (Used if gfld->numoct_opt .ne. 0)
531 // The number of entries
532 // in array ideflist. i.e. number of rows ( or columns )
533 // for which optional grid points are defined. This value
534 // is set to zero, if gfld->numoct_opt=0.
535 // gfdl->ipdtnum = Product Definition Template Number(see Code Table 4.0)
536 // gfld->ipdtmpl = Contains the data values for the specified Product
537 // Definition Template ( N=gfdl->ipdtnum ). Each element
538 // of this integer array contains an entry (in the
539 // order specified) of Product Definition Template 4.N.
540 // This element is a pointer to an array
541 // that holds the data.
542 // gfld->ipdtlen = Number of elements in gfld->ipdtmpl[]. i.e. number of
543 // entries in Product Definition Template 4.N
544 // ( N=gfdl->ipdtnum ).
545 // gfld->coord_list = Real array containing floating point values
546 // intended to document the vertical discretisation
547 // associated to model data on hybrid coordinate
548 // vertical levels. (part of Section 4)
549 // This element is a pointer to an array
550 // that holds the data.
551 // gfld->num_coord = number of values in array gfld->coord_list[].
552 // gfld->ndpts = Number of data points unpacked and returned.
553 // gfld->idrtnum = Data Representation Template Number
554 // ( see Code Table 5.0)
555 // gfld->idrtmpl = Contains the data values for the specified Data
556 // Representation Template ( N=gfld->idrtnum ). Each
557 // element of this integer array contains an entry
558 // (in the order specified) of Product Definition
559 // Template 5.N.
560 // This element is a pointer to an array
561 // that holds the data.
562 // gfld->idrtlen = Number of elements in gfld->idrtmpl[]. i.e. number
563 // of entries in Data Representation Template 5.N
564 // ( N=gfld->idrtnum ).
565 // gfld->unpacked = logical value indicating whether the bitmap and
566 // data values were unpacked. If false,
567 // gfld->bmap and gfld->fld pointers are nullified.
568 // gfld->expanded = Logical value indicating whether the data field
569 // was expanded to the grid in the case where a
570 // bit-map is present. If true, the data points in
571 // gfld->fld match the grid points and zeros were
572 // inserted at grid points where data was bit-mapped
573 // out. If false, the data values in gfld->fld were
574 // not expanded to the grid and are just a consecutive
575 // array of data points corresponding to each value of
576 // "1" in gfld->bmap.
577 // gfld->ibmap = Bitmap indicator ( see Code Table 6.0 )
578 // 0 = bitmap applies and is included in Section 6.
579 // 1-253 = Predefined bitmap applies
580 // 254 = Previously defined bitmap applies to this field
581 // 255 = Bit map does not apply to this product.
582 // gfld->bmap = integer array containing decoded bitmap,
583 // if gfld->ibmap=0 or gfld->ibap=254. Otherwise nullified
584 // This element is a pointer to an array
585 // that holds the data.
586 // gfld->fld = Array of gfld->ndpts unpacked data points.
587 // This element is a pointer to an array
588 // that holds the data.
589 //
590 //
591 // RETURN VALUES:
592 // ierr - Error return code.
593 // 0 = no error
594 // 1 = Beginning characters "GRIB" not found.
595 // 2 = GRIB message is not Edition 2.
596 // 3 = The data field request number was not positive.
597 // 4 = End string "7777" found, but not where expected.
598 // 6 = GRIB message did not contain the requested number of
599 // data fields.
600 // 7 = End string "7777" not found at end of message.
601 // 8 = Unrecognized Section encountered.
602 // 9 = Data Representation Template 5.NN not yet implemented.
603 // 15 = Error unpacking Section 1.
604 // 16 = Error unpacking Section 2.
605 // 10 = Error unpacking Section 3.
606 // 11 = Error unpacking Section 4.
607 // 12 = Error unpacking Section 5.
608 // 13 = Error unpacking Section 6.
609 // 14 = Error unpacking Section 7.
610 //
611 // REMARKS: Note that struct gribfield is allocated by this routine and it
612 // also contains pointers to many arrays of data that were allocated
613 // during decoding. Users are encouraged to free up this memory,
614 // when it is no longer needed, by an explicit call to routine g2_free.
615 // EXAMPLE:
616 // #include "grib2.h"
617 // gribfield *gfld;
618 // ret=g2_getfld(cgrib,1,1,1,&gfld);
619 // ...
620 // g2_free(gfld);
621 //
622 // Routine g2_info can be used to first determine
623 // how many data fields exist in a given GRIB message.
624 //
625 // REMARKS2: It may not always be possible to expand a bit-mapped data field.
626 // If a pre-defined bit-map is used and not included in the GRIB2
627 // message itself, this routine would not have the necessary
628 // information to expand the data. In this case, gfld->expanded would
629 // would be set to 0 (false), regardless of the value of input
630 // argument expand.
631 //
632 // ATTRIBUTES:
633 // LANGUAGE: C
634 // MACHINE:
635 //
636 ///////////////////////////////////////////////////////////////////////////
637
638
639
640 //$$$ SUBPROGRAM DOCUMENTATION BLOCK
641 // . . . .
642 // SUBPROGRAM: g2_create
643 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-10-31
644 //
645 // ABSTRACT: This routine initializes a new GRIB2 message and packs
646 // GRIB2 sections 0 (Indicator Section) and 1 (Identification Section).
647 // This routine is used with routines "g2_addlocal", "g2_addgrid",
648 // "g2_addfield", and "g2_gribend" to create a complete GRIB2 message.
649 // g2_create must be called first to initialize a new GRIB2 message.
650 // Also, a call to g2_gribend is required to complete GRIB2 message
651 // after all fields have been added.
652 //
653 // PROGRAM HISTORY LOG:
654 // 2002-10-31 Gilbert
655 //
656 // USAGE: int g2_create(unsigned char *cgrib,long *listsec0,long *listsec1)
657 // INPUT ARGUMENTS:
658 // cgrib - Character array to contain the GRIB2 message
659 // listsec0 - Contains information needed for GRIB Indicator Section 0.
660 // Must be dimensioned >= 2.
661 // listsec0[0]=Discipline-GRIB Master Table Number
662 // (see Code Table 0.0)
663 // listsec0[1]=GRIB Edition Number (currently 2)
664 // listsec1 - Contains information needed for GRIB Identification Section 1.
665 // Must be dimensioned >= 13.
666 // listsec1[0]=Id of originating centre (Common Code Table C-1)
667 // listsec1[1]=Id of originating sub-centre (local table)
668 // listsec1[2]=GRIB Master Tables Version Number (Code Table 1.0)
669 // listsec1[3]=GRIB Local Tables Version Number (Code Table 1.1)
670 // listsec1[4]=Significance of Reference Time (Code Table 1.2)
671 // listsec1[5]=Reference Time - Year (4 digits)
672 // listsec1[6]=Reference Time - Month
673 // listsec1[7]=Reference Time - Day
674 // listsec1[8]=Reference Time - Hour
675 // listsec1[9]=Reference Time - Minute
676 // listsec1[10]=Reference Time - Second
677 // listsec1[11]=Production status of data (Code Table 1.3)
678 // listsec1[12]=Type of processed data (Code Table 1.4)
679 //
680 // OUTPUT ARGUMENTS:
681 // cgrib - Char array to contain the new GRIB2 message.
682 // Must be allocated large enough to store the entire
683 // GRIB2 message.
684 //
685 // RETURN VALUES:
686 // ierr - return code.
687 // > 0 = Current size of new GRIB2 message
688 // -1 = Tried to use for version other than GRIB Edition 2
689 //
690 // REMARKS: This routine is intended for use with routines "g2_addlocal",
691 // "g2_addgrid", "g2_addfield", and "g2_gribend" to create a complete
692 // GRIB2 message.
693 //
694 // ATTRIBUTES:
695 // LANGUAGE: C
696 // MACHINE:
697 //
698 //$$$
699
700
701
702 //$$$ SUBPROGRAM DOCUMENTATION BLOCK
703 // . . . .
704 // SUBPROGRAM: g2_addlocal
705 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-11-01
706 //
707 // ABSTRACT: This routine adds a Local Use Section (Section 2) to
708 // a GRIB2 message. It is used with routines "g2_create",
709 // "g2_addgrid", "g2_addfield",
710 // and "g2_gribend" to create a complete GRIB2 message.
711 // g2_create must be called first to initialize a new GRIB2 message.
712 //
713 // PROGRAM HISTORY LOG:
714 // 2002-11-01 Gilbert
715 //
716 // USAGE: int g2_addlocal(unsigned char *cgrib,unsigned char *csec2,
717 // long lcsec2)
718 // INPUT ARGUMENTS:
719 // cgrib - Char array that contains the GRIB2 message to which section
720 // 2 should be added.
721 // csec2 - Character array containing information to be added in
722 // Section 2.
723 // lcsec2 - Number of bytes of character array csec2 to be added to
724 // Section 2.
725 //
726 // OUTPUT ARGUMENT:
727 // cgrib - Char array to contain the updated GRIB2 message.
728 // Must be allocated large enough to store the entire
729 // GRIB2 message.
730 //
731 // RETURN VALUES:
732 // ierr - Return code.
733 // > 0 = Current size of updated GRIB2 message
734 // -1 = GRIB message was not initialized. Need to call
735 // routine gribcreate first.
736 // -2 = GRIB message already complete. Cannot add new section.
737 // -3 = Sum of Section byte counts doesn't add to total byte count
738 // -4 = Previous Section was not 1 or 7.
739 //
740 // REMARKS: Note that the Local Use Section ( Section 2 ) can only follow
741 // Section 1 or Section 7 in a GRIB2 message.
742 //
743 // ATTRIBUTES:
744 // LANGUAGE: C
745 // MACHINE:
746 //
747 //$$$
748
749
750
751 //$$$ SUBPROGRAM DOCUMENTATION BLOCK
752 // . . . .
753 // SUBPROGRAM: g2_addgrid
754 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-11-01
755 //
756 // ABSTRACT: This routine packs up a Grid Definition Section (Section 3)
757 // and adds it to a GRIB2 message. It is used with routines "g2_create",
758 // "g2_addlocal", "g2_addfield",
759 // and "g2_gribend" to create a complete GRIB2 message.
760 // g2_create must be called first to initialize a new GRIB2 message.
761 //
762 // PROGRAM HISTORY LOG:
763 // 2002-11-01 Gilbert
764 //
765 // USAGE: int g2_addgrid(unsigned char *cgrib,long *igds,g2int *igdstmpl,
766 // long *ideflist,long idefnum)
767 // INPUT ARGUMENTS:
768 // cgrib - Char array that contains the GRIB2 message to which
769 // section should be added.
770 // igds - Contains information needed for GRIB Grid Definition Section 3
771 // Must be dimensioned >= 5.
772 // igds[0]=Source of grid definition (see Code Table 3.0)
773 // igds[1]=Number of grid points in the defined grid.
774 // igds[2]=Number of octets needed for each
775 // additional grid points definition.
776 // Used to define number of
777 // points in each row ( or column ) for
778 // non-regular grids.
779 // = 0, if using regular grid.
780 // igds[3]=Interpretation of list for optional points
781 // definition. (Code Table 3.11)
782 // igds[4]=Grid Definition Template Number (Code Table 3.1)
783 // igdstmpl - Contains the data values for the specified Grid Definition
784 // Template ( NN=igds[4] ). Each element of this integer
785 // array contains an entry (in the order specified) of Grid
786 // Definition Template 3.NN
787 // ideflist - (Used if igds[2] != 0) This array contains the
788 // number of grid points contained in each row ( or column )
789 // idefnum - (Used if igds[2] != 0) The number of entries
790 // in array ideflist. i.e. number of rows ( or columns )
791 // for which optional grid points are defined.
792 //
793 // OUTPUT ARGUMENTS:
794 // cgrib - Char array to contain the updated GRIB2 message.
795 // Must be allocated large enough to store the entire
796 // GRIB2 message.
797 //
798 // RETURN VALUES:
799 // ierr - Return code.
800 // > 0 = Current size of updated GRIB2 message
801 // -1 = GRIB message was not initialized. Need to call
802 // routine gribcreate first.
803 // -2 = GRIB message already complete. Cannot add new section.
804 // -3 = Sum of Section byte counts doesn't add to total byte count
805 // -4 = Previous Section was not 1, 2 or 7.
806 // -5 = Could not find requested Grid Definition Template.
807 //
808 // REMARKS: Note that the Grid Def Section ( Section 3 ) can only follow
809 // Section 1, 2 or Section 7 in a GRIB2 message.
810 //
811 // ATTRIBUTES:
812 // LANGUAGE: C
813 // MACHINE:
814 //
815 //$$$
816
817
818
819 //$$$ SUBPROGRAM DOCUMENTATION BLOCK
820 // . . . .
821 // SUBPROGRAM: g2_addfield
822 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-11-05
823 //
824 // ABSTRACT: This routine packs up Sections 4 through 7 for a given field
825 // and adds them to a GRIB2 message. They are Product Definition Section,
826 // Data Representation Section, Bit-Map Section and Data Section,
827 // respectively.
828 // This routine is used with routines "g2_create", "g2_addlocal",
829 // "g2_addgrid", and "g2_gribend" to create a complete GRIB2 message.
830 // g2_create must be called first to initialize a new GRIB2 message.
831 // Also, routine g2_addgrid must be called after g2_create and
832 // before this routine to add the appropriate grid description to
833 // the GRIB2 message. Also, a call to g2_gribend is required to complete
834 // GRIB2 message after all fields have been added.
835 //
836 // PROGRAM HISTORY LOG:
837 // 2002-11-05 Gilbert
838 //
839 // USAGE: int g2_addfield(unsigned char *cgrib,g2int ipdsnum,g2int *ipdstmpl,
840 // g2float *coordlist,g2int numcoord,g2int idrsnum,g2int *idrstmpl,
841 // g2float *fld,g2int ngrdpts,g2int ibmap,g2int *bmap)
842 // INPUT ARGUMENT LIST:
843 // cgrib - Char array that contains the GRIB2 message to which sections
844 // 4 through 7 should be added.
845 // ipdsnum - Product Definition Template Number ( see Code Table 4.0)
846 // ipdstmpl - Contains the data values for the specified Product Definition
847 // Template ( N=ipdsnum ). Each element of this integer
848 // array contains an entry (in the order specified) of Product
849 // Definition Template 4.N
850 // coordlist- Array containing floating point values intended to document
851 // the vertical discretisation associated to model data
852 // on hybrid coordinate vertical levels.
853 // numcoord - number of values in array coordlist.
854 // idrsnum - Data Representation Template Number ( see Code Table 5.0 )
855 // idrstmpl - Contains the data values for the specified Data Representation
856 // Template ( N=idrsnum ). Each element of this integer
857 // array contains an entry (in the order specified) of Data
858 // Representation Template 5.N
859 // Note that some values in this template (eg. reference
860 // values, number of bits, etc...) may be changed by the
861 // data packing algorithms.
862 // Use this to specify scaling factors and order of
863 // spatial differencing, if desired.
864 // fld[] - Array of data points to pack.
865 // ngrdpts - Number of data points in grid.
866 // i.e. size of fld and bmap.
867 // ibmap - Bitmap indicator ( see Code Table 6.0 )
868 // 0 = bitmap applies and is included in Section 6.
869 // 1-253 = Predefined bitmap applies
870 // 254 = Previously defined bitmap applies to this field
871 // 255 = Bit map does not apply to this product.
872 // bmap[] - Integer array containing bitmap to be added. ( if ibmap=0 )
873 //
874 // OUTPUT ARGUMENT LIST:
875 // cgrib - Character array to contain the updated GRIB2 message.
876 // Must be allocated large enough to store the entire
877 // GRIB2 message.
878 //
879 // RETURN VALUES:
880 // ierr - Return code.
881 // > 0 = Current size of updated GRIB2 message
882 // -1 = GRIB message was not initialized. Need to call
883 // routine gribcreate first.
884 // -2 = GRIB message already complete. Cannot add new section.
885 // -3 = Sum of Section byte counts doesn't add to total byte count
886 // -4 = Previous Section was not 3 or 7.
887 // -5 = Could not find requested Product Definition Template.
888 // -6 = Section 3 (GDS) not previously defined in message
889 // -7 = Tried to use unsupported Data Representationi Template
890 // -8 = Specified use of a previously defined bitmap, but one
891 // does not exist in the GRIB message.
892 //
893 // REMARKS: Note that the Sections 4 through 7 can only follow
894 // Section 3 or Section 7 in a GRIB2 message.
895 //
896 // ATTRIBUTES:
897 // LANGUAGE: C
898 // MACHINE:
899 //
900 //$$$
901
902
903
904 //$$$ SUBPROGRAM DOCUMENTATION BLOCK
905 // . . . .
906 // SUBPROGRAM: g2_gribend
907 // PRGMMR: Gilbert ORG: W/NP11 DATE: 2002-10-31
908 //
909 // ABSTRACT: This routine finalizes a GRIB2 message after all grids
910 // and fields have been added. It adds the End Section ( "7777" )
911 // to the end of the GRIB message and calculates the length and stores
912 // it in the appropriate place in Section 0.
913 // This routine is used with routines "g2_create", "g2_addlocal",
914 // "g2_addgrid", and "g2_addfield" to create a complete GRIB2 message.
915 // g2_create must be called first to initialize a new GRIB2 message.
916 //
917 // PROGRAM HISTORY LOG:
918 // 2002-10-31 Gilbert
919 //
920 // USAGE: int g2_gribend(unsigned char *cgrib)
921 // INPUT ARGUMENT:
922 // cgrib - Char array containing all the data sections added
923 // be previous calls to g2_create, g2_addlocal, g2_addgrid,
924 // and g2_addfield.
925 //
926 // OUTPUT ARGUMENTS:
927 // cgrib - Char array containing the finalized GRIB2 message
928 //
929 // RETURN VALUES:
930 // ierr - Return code.
931 // > 0 = Length of the final GRIB2 message in bytes.
932 // -1 = GRIB message was not initialized. Need to call
933 // routine g2_create first.
934 // -2 = GRIB message already complete.
935 // -3 = Sum of Section byte counts doesn't add to total byte count
936 // -4 = Previous Section was not 7.
937 //
938 // REMARKS: This routine is intended for use with routines "g2_create",
939 // "g2_addlocal", "g2_addgrid", and "g2_addfield" to create a complete
940 // GRIB2 message.
941 //
942 // ATTRIBUTES:
943 // LANGUAGE: C
944 // MACHINE:
945 //
946 //$$$