www.nws.noaa.gov
NOAA logo - Click to go to the NOAA homepage National Weather Service NWS logo - Click to go to the NWS homepage
EMC Logo



NCEP Home > EMC Home > BUFRLIB > BUFRLIB Table of Contents > Description and Format of Master BUFR Tables
Printer image icon. Printer Friendly Version

Description and Format of Master BUFR Tables

This document describes the format and concept of master BUFR tables. As explained in the introduction, these are required by the BUFRLIB software whenever the CIO='SEC3' option is specified during a call to subroutine OPENBF for the reading/decoding of a given file of BUFR messages. Otherwise, if a different value of CIO is specified, then only a DX BUFR tables file is required, and master BUFR tables are not needed.

Subroutine MTINFO

Whenever master BUFR tables are required, they are provided to the BUFRLIB software as a set of four system files. The actual format, content and naming conventions of these files will be described later, but first we'll show how to specify the location of these master table files.

        CALL MTINFO  ( CMTDIR, LUNMT1, LUNMT2 )

        Input argument:
            CMTDIR      CHAR*           Directory location of BUFR master tables
                                        on local file system
            LUNMT1      INTEGER         First logical unit number to use when
                                        reading BUFR master tables on system
            LUNMT2      INTEGER         Second logical unit number to use when
                                        reading BUFR master tables on system

This subroutine should be called immediately after the corresponding call to subroutine OPENBF for the BUFR file in question, but at any rate it must be called before any subsequent calls to subroutine READMG, READNS or READERME are attempted on the file. The subroutine takes three input arguments, the first of which is a string defining the directory path on the local filesystem where the BUFR master tables are located. Any full or relative pathname that is legal on the local filesystem is allowed, up to a total length of 100 characters, and the BUFRLIB software will automatically search within this directory for the necessary master table files when it is time for them to be opened and read. The last two arguments are logical unit numbers for the software to use when opening and reading these files. These can be any legal FORTRAN logical unit numbers on the local filesystem, but they must be distinct from each other and cannot already be assigned to any other system files within the application program.

Note that no actual master table file names are provided to this subroutine; rather, only the directory path where all of the master table files reside on the local filesystem is input to this routine. The names of the table files themselves are determined automatically by the software as described below. Whenever master tables need to be read, they are read as a corresponding set of four system files:

Actual filenames follow the following convention:

	Standard tables:     bufrtab.TableX_STD_M_V
	Local tables:        bufrtab.TableX_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 a new BUFR message is read from a logical unit that was previously opened using subroutine OPENBF with CIO='SEC3', the identification section (Section 1) of the message is automatically scanned to determine the above values for that message, then the software generates the four necessary filenames using those values and attempts to open and read each of those files from the directory that was specified by 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 ones 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.

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 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 these messages. Otherwise, if the messages to be decoded contain only standard descriptors (which is normally the case for data exchanged between 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 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:

Sample master Table B files

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 exist within the directory specified by CMTDIR during the previous call to subroutine MTINFO. The BUFRLIB software will scan the identification section (Section 1) of each BUFR message 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 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 shown:
 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:

Sample master Table D files

Subroutines CODFLG and GETCFMNG

As noted above, master table B and D files are required whenever Section 3 is used (i.e. whenever the CIO='SEC3' option is specified during a call to subroutine OPENBF) for the reading/decoding of a given file of BUFR messages. But in addition to these required files, there are optional code/flag table files which may also be read in and used to provide even more information about the decoded data. Doing so allows an application code to decode not only the numerical value stored for any table B descriptor that is a code or flag table, but also the corresponding meaning as a variable-length character string.

Again, this capability is fully optional as an add-on to the provision of the required master table B and D files, and it should only be employed if the application code intends to retrieve and make use of the underlying meaning strings, since it does require the use of additional memory and other system resources. To enable this capability, the following subroutine is used and may be called at any time after the initial call to OPENBF within the application program:

        CALL CODFLG  ( CF )

        Input argument:
            CF          CHARACTER       Flag indicating whether code/flag table
                                        information should be included when reading
                                        master tables B and D into internal memory:
                                         'N' = no (the default)
                                         'Y' = yes

Then, once this capability has been enabled, the application code can then search for and retrieve the meaning associated with any numerical code or flag table value decoded from the corresponding BUFR messages, as follows:

        CALL GETCFMNG  ( LUBFR, NEMOI, IVALI, NEMOD, IVALD, CMEANG, LNMNG, IRET )

        Input argument:
            LUBFR       INTEGER         Logical unit for BUFR file
            NEMOI       CHAR*(*)        Mnemonic to search for
            IVALI       INTEGER         Value (code figure or bit number) associated with NEMOI
            NEMOD       CHAR*(*)        Optional second mnemonic upon which the values NEMOI
                                        and IVALI depend; set to all blank characters if the
                                        meanings of NEMOI and IVALI do not depend on the value
                                        of any other mnemonic 
            IVALD       INTEGER         Value (code figure or bit number) associated with NEMOD;
                                        set to (-1) whenever NEMOD is set to all blank characters

        Output arguments:
            CMEANG      CHAR*(*)        If the initial search of the master code/flag tables was
                                        successful, then this string contains the meaning
                                        corresponding to NEMOI and IVALI (and to NEMOD and IVALD,
                                        if specified).  However, if the initial search was
                                        unsuccessful, and if NEMOD and IVALD were not specified,
                                        and if a second search of the tables determined that
                                        NEMOI and IVALI do indeed depend on one or more possible
                                        NEMOD mnemonics, then those possible mnemonics are
                                        returned within this string, as a series of IRET
                                        successive 8-byte substrings.
            LNMNG       INTEGER         Length of string returned in CMEANG
            IRET        INTEGER         Return code:
                                          0 = initial search was successful, and CMEANG contains
                                              meaning corresponding to NEMOI and IVALI (and to
                                              NEMOD and IVALD, if specified)
                                         -1 = initial search was unsuccessul, and no second
                                              search was attempted or possible
                                         >0 = initial search was unsuccessful, but second search
                                              was successful, and CMEANG contains one or more
                                              possible NEMOD mnemonics as a series of IRET
                                              successive 8-byte substrings

As noted above, this subroutine first does an initial search of the master code/flag tables based on the mnemonics and values provided. The input parameters NEMOI and IVALI specify the mnemonic and corresponding numerical code or flag table value for which the meaning is sought, and the optional secondary parameters NEMOD and IVALD are specified when needed to differentiate between multiple possible results. An example would be when a user is searching for the meaning of a numerical code table value for an originating sub-center (i.e. mnemonic GSES). The meaning of any originating sub-center value depends on the identity of the originating center for which the sub-center in question is a member, so in order for the subroutine to locate and return the proper one, information about the originating center must also be provided. So in this case the user would input GSES and the associated numerical value as NEMOI and IVALI, respectively, but the user would also need to specify an appropriate originating center mnemonic (e.g. GCLONG, OGCE or ORIGC) and associated value from the same BUFR message as input parameters NEMOD and IVALD, respectively, and then the subroutine will be able to locate and return the appropriate meaning string. Otherwise, if this information was not provided, the subroutine would return with an IRET value of 3, and with each of the mnemonics GCLONG, OGCE and ORIGC contained in successive 8-byte substrings of CMEANG (and with a corresponding value of 24 returned for LNMNG), as a hint to the user that more information needs to be input to the subroutine in order to achieve the desired result.

Note that, in cases where the meaning of a numerical code or flag table value associated with a mnemonic does not depend on the value associated with any other mnemonic, the input parameter NEMOD should be set to a field of all blank characters, and the input parameter IVALD should be set to a value of (-1). But also note that, in any and all cases where this subroutine is called, it is the user's responsibility to provide sufficient allocated space in parameter CMEANG for the returned meaning string; otherwise, the returned string will be truncated.

Code/Flag Tables

Whenever optional master code/flag tables are read in to supplement the required master table B and table D files, they must exist within the same local filesystem directory specified by CMTDIR during the previous call to subroutine MTINFO. And just like for table B and table D, they must exist as a set of two master code/flag tables, one containing all of the standard entries and one containing all of the local entries, and where the default local code/flag tables from NCEP 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 above, 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

In any case, 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:

Sample master Code/Flag Table files