Description and format of master BUFR tables for use with the library.

This document describes the format and concept of master BUFR tables. These are required by the NCEPLIBS-bufr software whenever the IO='SEC3' option is specified during a call to subroutine openbf() for the reading/decoding of a file of BUFR messages. Otherwise, if a different value of IO is specified, then only a DX BUFR tables file is normally required, and master BUFR tables are not needed.

Whenever master BUFR tables are used, they are read in by the BUFRLIB software as a corresponding set of four system files, from a directory on the local filesystem as specified within a separate preceding call to subroutine mtinfo() :

Standard Table B - an ordered listing of all descriptors corresponding to an official release (i.e. version number) of the standard, international BUFR Table B
Local Table B - an ordered listing of all local Table B descriptors supplementing the standard BUFR Table B, as defined for use within a particular local originating center
Standard Table D - an ordered listing of all descriptors corresponding to an official release (i.e. version number) of the standard, international BUFR Table D
Local Table D - an ordered listing of all local Table D descriptors supplementing the standard BUFR Table D, as defined for use within a particular local originating center

Actual filenames use the following convention:

Standard tables:     bufrtab.Table.X_STD_M_V
Local tables:        bufrtab.Table.X_LOC_M_C_L

        where:       X = Table type ('B' or 'D')
                     M = Master Table number ('0' for WMO, '10' for IOC, etc.)
                     V = Version number of Master Table used
                     C = Originating Center number ('7' for NCEP, etc.)
                     L = Version number of local tables used

Whenever any of the message-reading subroutines are used to read a new BUFR message from a Fortran logical unit that was previously opened using subroutine openbf() with IO='SEC3', the identification section (Section 1) of the message is automatically scanned to determine the above values for that message. The BUFRLIB software then automatically generates the four necessary filenames using those values and attempts to open and read each of those files from within the directory that was specified as CMTDIR during the previous call to subroutine mtinfo(). This table information is then retained and re-used in memory until a subsequent message is read which has a different value for any one of the above values, and at which point a new set of tables is then read in from the same directory in order to be applied to the new message. With this approach, the user can have multiple master table files stored within the same directory, and the BUFRLIB software will always locate and read the appropriate files depending on the corresponding values stored within Section 1 of each new message to be decoded. For more details about the above values, see the discussion on Section 1 within the official WMO Manual 306, Volume I.2.

Now that we've discussed the content and naming conventions for master BUFR table files, let's turn our attention to the actual format of these files:

Table B

As described above, two master Table B files (one standard and one local) are required for each BUFR message that is to be read and decoded. The BUFRLIB software will scan the identification section (Section 1) of each new message and then open and read the appropriate Table B files from within the directory specified by CMTDIR during the previous call to subroutine mtinfo(). In particular, a standard Table B file must be available corresponding to the version number of each BUFR message to be decoded, and the filename must follow the naming convention described above. In addition, if there are any local descriptors contained within the messages, then a local Table B file must also be available corresponding to the originating center and local version numbers encoded within Section 1 of those messages. Otherwise, if the messages to be decoded contain only standard descriptors (which is normally the case for data exchanged between operational centers), then the default local Table B file from NCEP (originating center 7) can be used as a placeholder since the software will not need to actually read any information from this table. In this way, users are relieved from having to provide a local Table B file for every originating center whose messages they wish to decode, and such a table only becomes necessary when the messages themselves actually contain one or more local descriptors defined by that particular originating center.

Here now is the format for each master Table B:

The first line of the file is as follows, where the symbols correspond to those used in the file naming convention described above. In this way, the software can perform internal consistency checks where needed. Note that the separator for each field is a "|" character, but otherwise the free use of white space is allowed within each field:

Standard table:     Table B STD | M | V
Local table:        Table B LOC | M | C | L

       where:       M = Master Table number ('0' for WMO, '10' for IOC, etc.)
                    V = Version number of Master Table used
                    C = Originating Center number ('7' for NCEP, etc.)
                    L = Version number of local tables used

Following this first header line, the remainder of the file contains a listing of all possible Table B descriptors corresponding to the specified version number of the table, ordered in ascending order with respect to the FXY number as shown below. Blank lines as well as comments (i.e. any line beginning with the character "#") are permitted throughout the file and will be ignored by the software, up until a line is reached which contains the string "END" in the first three characters, and which is a signal to the software to stop looking for any new Table B descriptor definitions in the table. Each definition line has the following format, where the "|" and ";" characters are required separators as shown, but otherwise the additional use of white space is allowed within each field.

 F-XX-YYY | SCALE | REFERENCE | BITS | UNITS  | MNEMONIC ; CODES ; ELEMENT NAME

The CODES field can be used for any annotations the user may wish to add for a particular definition line, or it can be left blank. All other fields should be self-explanatory based on earlier discussions and should contain a value. Here are some examples:

  0-01-018 |   0 |  0 |  40 | CCITT IA5   | SSTN    ; ; Short station or site name
  0-01-041 |   5 | -1073741824 |  31 | m/s | PS00   ;  ; Absolute platform velocity - first component
  0-05-002 |   2 |       -9000 |  15 | Degree(N+,S-)  | CLAT     ;     ; Latitude (coarse accuracy)
  0-07-002 |  -1 |         -40 |  16 | m              | HMSL     ;     ; Height or altitude

The above examples show how additional white space can vary from line to line and can be used according to individual preferences, but of course for overall readability it's usually best to pick one format and stick to it within a given table file. Here are some sample master Table B files that can be downloaded and used. These are also available as part of the standard distribution package for the software, within the tables subdirectory:

Table D

As was the case for Table B, two master Table D files (one standard and one local) are also required for each BUFR message that is to be read and decoded, and these files must also exist within the same directory specified by CMTDIR during the previous call to subroutine mtinfo(). The BUFRLIB software will then scan the identification section (Section 1) of each BUFR message as it is read, in order to determine the exact master table files to open and read for that message, and a local Table D file is necessary whenever local descriptors from the originating center in question are included within a message; otherwise, the default local Table D file from NCEP (originating center 7) can be used as a placeholder.

The format of the first line of each master Table D file is the same as for Table B:

Standard table:     Table D STD | M | V
Local table:        Table D LOC | M | C | L

       where:       M = Master Table number ('0' for WMO, '10' for IOC, etc.)
                    V = Version number of Master Table used
                    C = Originating Center number ('7' for NCEP, etc.)
                    L = Version number of local tables used

and blank lines and comment lines (beginning with a "#" in column 1) are likewise allowed, but otherwise the format for a master Table D file differs from that of a master Table B file since entries now span multiple file lines as follows:

 F-XX-YYY | MNEMONIC  ; CODES ; SEQUENCE_NAME
          | F-XX-YYY > | ELEMENT_NAME  
          | F-XX-YYY   | ELEMENT_NAME

As shown, the first line of each entry contains the FXY number of the Table D sequence, along with the corresponding sequence name, mnemonic and annotation codes (if any), and then each successive line contains a single element of that sequence. Each successive element is listed one per line, and note the ">" character after the FXY number within each element line up to, but not including, the last element of the sequence. The BUFRLIB software uses the lack of a ">" character to know when it has reached the last element of the sequence. Here are some examples:

  3-01-004 | SFCSTNID   ;  ; Surface station identification
           | 0-01-001 > | WMO block number
           | 0-01-002 > | WMO station number
           | 0-01-015 > | Station or site name
           | 0-02-001   | Type of station

  3-01-012 | HHMM       ; ;
           | 0-04-004 >  | Hour
           | 0-04-005    | Minute

  3-01-023 | LTLONC   ;   ;
           | 0-05-002 > | Latitude (coarse accuracy)
           | 0-06-002   | Longitude (coarse accuracy)

  3-01-025 | LTLONCDT   ;  ;
           | 3-01-023 > | Latitude and longitude (coarse accuracy)
           | 0-04-003 > | Day
           | 3-01-012   | Time

  3-01-045 | SATLOVEL   ;     ; Satellite location and velocity
           | 3-01-011 > | Year, month, day
           | 3-01-012 > | Time (hour, minute)
           | 2-01-138 > | Change width to 16 bits
           | 2-02-131 > | Change scale to 3
           | 0-04-006 > | Second
           | 2-01-000 > | Change width back to Table B
           | 2-02-000 > | Change scale back to Table B
           | 3-04-030 > | Location relative to the Earth's centre
           | 3-04-031   | Velocity relative to the Earth's centre

  3-03-050 | WDPLRAOB   ; ; Wind data at a pressure level with radiosonde position
           | 0-04-086 > | Long time period or displacement (since launch time)
           | 0-08-042 > | Extended vertical sounding significance
           | 0-07-004 > | Pressure
           | 0-05-015 > | Latitude displacement since launch site (high accuracy)
           | 0-06-015 > | Longitude displacement since launch site (high accuracy)
           | 0-11-001 > | Wind direction
           | 0-11-002   | Wind speed

As with master Table B files, the entries within a master Table D file must all be sorted in ascending order with respect to the FXY number, and the software will continue reading from the file until it reaches a line with the string "END" in the first three characters. Here are some sample master Table D files that can be downloaded and used. These are also available as part of the standard distribution package for the software, within the tables subdirectory:

Code/Flag Tables

Unlike for Table B and Table D, master Code/Flag tables are optional when the IO='SEC3' option is specified during a call to subroutine openbf() for the reading/decoding of BUFR messages. Instead, they are only required if the user intends to make one or more calls to subroutine getcfmng(), and in which case a prior call to subroutine codflg() is also required with the value of CF set to 'Y'.

Whenever master Code/Flag tables are used, they must exist within the same local filesystem directory specified by CMTDIR during the most recent call to subroutine mtinfo(). And just like for Table B and Table D, they must exist as a set of two separate tables files, one containing all of the standard entries and one containing all of the local entries, and where the default local Code/Flag tables file from NCEP (originating center 7) can be used as a placeholder for the local file whenever the BUFR messages to be decoded contain only standard descriptors.

The format of the first line of each master Code/Flag table file is the same as for Tables B and D:

Standard table:     Table F STD | M | V
Local table:        Table F LOC | M | C | L

       where:       M = Master Table number ('0' for WMO, '10' for IOC, etc.)
                    V = Version number of Master Table used
                    C = Originating Center number ('7' for NCEP, etc.)
                    L = Version number of local tables used

and blank lines and comment lines (beginning with a "#" in column 1) are likewise allowed throughout each table for readability. Entries span multiple lines and follow the format:

 F-XX-YYY | MNEMONIC ; CODE
          | F-XX-YYY=VAL
            | VAL > | MEANING
            | VAL   | MEANING

for code tables, and:

 F-XX-YYY | MNEMONIC ; FLAG
          | F-XX-YYY=BIT
            | BIT > | MEANING
            | BIT   | MEANING

for flag tables. As shown, the first line of each entry contains the FXY number and mnemonic of the associated Table B descriptor, along with the identifier "CODE" or "FLAG" depending on the table type. Successive lines contain individual entries within the associated table, grouped by dependency where applicable. For example, for mnemonic GSES (originating sub-center), whose meanings depend on that of the associated originating center as noted in the discussion for subroutine getcfmng(), the entry would look something like the following, and where 0-01-031, 0-01-033 and 0-01-035 are the respective FXY numbers for mnemonics GCLONG, OGCE and ORIGC:

  0-01-034 | GSES ; CODE
           | 0-01-031,0-01-033,0-01-035=39
              | 0 > | No sub-centre
              | 225 > | Beijing
              | 226 > | Guangzhou
              | 228 > | Urumuqi
           | 0-01-031,0-01-033,0-01-035=80
              | 0 > | No sub-centre
              | 101 > | Albania (NMC)
              | 102 > | National Research Council/Institute of Atmospheric Sciences and Climate (CNR-ISAC)
           | 0-01-031,0-01-033,0-01-035=7
              | 0 > | No sub-centre
              | 1 > | NCEP Reanalysis Project
              | 2 > | NCEP Ensemble Products
              | 3 > | NCEP Central Operations
              | 4 > | Environmental Modeling Center
              | 5 > | Weather Prediction Center
              | 6 > | Ocean Prediction Center
              | 7 > | Climate Prediction Center
              | 8 > | Aviation Weather Center
              | 9 > | Storm Prediction Center
              | 10 > | National Hurricane Center
              | 11 > | NWS Techniques Development Laboratory
              | 12 > | NESDIS Office of Research and Applications
              | 13 > | Federal Aviation Administration
              | 14 > | NWS Meteorological Development Laboratory
              | 15 > | North American Regional Reanalysis Project
              | 16 > | Space Weather Prediction Center
              | 17 > | ESRL Global Systems Division
           | 0-01-031,0-01-033,0-01-035=46
              | 0 > | No sub-centre
              | 10 > | Cachoeira Paulista (INPE)
              | 11 > | Cuiaba (INPE)
              | 12 > | Brasilia (INMET)
              | 13 > | Fortaleza (FUNCEME)
              | 14 > | Natal (Navy Hygrog. Centre)
              | 15 > | Manaus (SIVAM)
              | 16 > | Natal (INPE)
              | 17 > | Boa Vista
              | 25 > | São Paulo University - USP
           | 0-01-031,0-01-033,0-01-035=254
              | 0 > | No sub-centre
              | 10 > | Tromso (Norway)
              | 20 > | Maspalomas (Spain)
              | 30 > | Kangerlussuaq (Greenland)
              | 40 > | Edmonton (Canada)
              | 50 > | Bedford (Canada)
              | 60 > | Gander (Canada)
              | 70 > | Monterey (USA)
              | 80 > | Wallops Island (USA)
              | 90 > | Gilmor Creek (USA)
              | 100 > | Athens (Greece)
              | 120 > | Ewa Beach, Hawaii
              | 125 > | Ford Island, Hawaii
              | 130 > | Miami, Florida
              | 140 > | Lannion (France)
              | 150 > | Svalbard (Norway)
              | 170 > | St Denis (La Réunion)
              | 180 > | Moscow
              | 190 > | Muscat
              | 200 > | Khabarovsk
              | 210   | Novosibirsk

However, if the meanings of the code or flag table values for a particular mnemonic do not depend on those of any other mnemonic, then the dependency lines can be omitted from the above format, as shown in the following additional examples:

  0-02-003 | A4ME ; CODE
              | 0 > | Pressure Instrument associated with wind measuring equipment
              | 1 > | Optical theodolite
              | 2 > | Radio theodolite
              | 3 > | Radar
              | 4 > | VLF-Omega
              | 5 > | Loran C
              | 6 > | Wind profiler
              | 7 > | Satellite navigation
              | 8 > | Radio-acoustic Sounding System (RASS)
              | 9 > | Sodar
              | 10 > | LIDAR
              | 14   | Pressure instrument associated with wind measuring equipment but pressure element failed during ascent

  0-02-008 | TOFSP ; CODE
              | 0 > | Fixed platform
              | 1 > | Mobile offshore drill ship
              | 2 > | Jack-up rig
              | 3 > | Semi-submersible platform
              | 4 > | FPSO (floating production storage and offloading unit)
              | 5   | Light vessel

  0-02-016 | RCONF ; FLAG
              | 1 > | Train regulator
              | 2 > | Light unit
              | 3 > | Parachute
              | 4   | Rooftop release

  0-02-017 | CAHM ; CODE
              | 0 > | No corrections
              | 1 > | Time lag correction provided by the manufacturer
              | 2 > | Solar radiation correction provided by the manufacturer
              | 3 > | Solar radiation and time lag correction provided by the manufacturer
              | 7   | GRUAN solar radiation and time lag correction

  0-02-022 | SDPT ; FLAG
              | 1 > | Processing technique not defined
              | 2 > | Automated statistical regression
              | 3 > | Clear path
              | 4 > | Partly cloudy path
              | 5   | Cloudy path

Note that the values for any entry are always listed one per line, and note the ">" character after the value within each line up to, but not including, the last defined value/meaning pair for that entry. The BUFRLIB software uses this lack of a ">" character to know when it has reached the last value/meaning pair for the associated entry. And as was also the case for master Table B and Table D files, all entries in a master Code/Flag table file must be in sorted ascending order with respect to the FXY number, and the BUFRLIB software will continue reading from the file until it reaches a line with the string "END" in the first three characters. Here are some sample master code/flag table files that can be downloaded and used. These are also available as part of the standard distribution package for the software, within the tables subdirectory: