Doug Schuster
                                                                Gregg Walters
                                                                September 10, 2010
                                                                Updated 09 October 2013
                                                                Kevin Manross

USING THE BUFR DECODING SOFTWARE

FOR UPPER AIR DATA IN THE NCAR RDA DATASET DS351.0
(NCEP ADP GLOBAL UPPER AIR OBSERVATIONS, DAILY OCT1999-CONTINUING)

Here is a list of the bufrdecode sub-directories and their descriptions.

    bufrobs     Use to hold BUFR data files for the dumpbufr.x decoder.
                  There is a README which describes how to handle some
                  machine dependencies.

    configs     Has a few sample configuration files, to be read by
                  the BUFR decoder, plus a descriptive template.

    docs        Contains files showing some basic parameter mnemonics
                  and a link to recent NCEP BUFR tables.

    exe         Where the install places the decoder executables.

    -grabbufr-  No longer needed
                  

    install     Has a shell script for compiling and installing BUFR
                  decoders.

    lib         NCEP BUFR decoder support library - mostly FORTRAN
                  source code, plus a few C source codes. Includes 
                  its own setup script 'makebufrlib.sh' which is called
                  from within install/install.sh so you shouldn't need
                  to run it, but may if you like.

    src         Two FORTRAN BUFR decoder source code files.  A
                  flexible, user configurable program plus a simple
                  dumping program.

    textobs     Used to receive text files generated by the decoders.


All directories (except "textobs") contain their own README files.

** The following text lists the steps necessary to build the software and
   decode the BUFR data. Steps include preparing the decoder software, preparing
   the input files, preparing the configuration files, 
   and finally running the decoder software.  *****

1.  PREPARING THE DECODER SOFTWARE:

   -To compile the BUFR libraries and extraction code, go to the "install"
    directory and execute the install.sh script to complete the compilations.  

    Note: install.sh is set to use 'gfortran' as the compiler and linker.  This 
    is tested and works for linux (including Mac/Darwin variants), but may need
    adjusted for other operating systems.

    The executables will be placed in the
    "exe" directory.  You could copy them to an arbitrary directory,
    notably your bin, where they could be executed from anywhere.

    bufrdecode/exe/bufrupprair.x:  used to make a selective dump from:
                                       gdas.adpupa.tHHz.YYYYMMDD.bufr files
                                       gdas.aircft.tHHz.YYYYMMDD.bufr files
                                       gdas.satwnd.tHHz.YYYYMMDD.bufr files
                                       gdas.aircar.tHHz.YYYYMMDD.bufr files 

    bufrdecode/exe/dumpbufr.x:     used to dump all contents of a BUFR file.

2.  PREPARING THE INPUT FILES:

    -Place your downloaded files, which have the naming structure 
               "gdasupaobs.yyyymmdd.tar.gz",
     in the bufrobs directory.
    -Run the "exe/preprocess.csh" script to untar files in bufrobs directory.
    -All individual BUFR files are extracted and placed in the "BUFROBS" directory. 
    -File names must appear in the following format to proceed further:
          gdas.adpupa.tHHz.YYYYMMDD.bufr          (radiosondes and pibals)
          gdas.aircft.tHHz.YYYYMMDD.bufr          (aircraft) 
          gdas.satwnd.tHHz.YYYYMMDD.bufr          (satellite winds)
          gdas.aircar.tHHz.YYYYMMDD.bufr          (aircar)
        
3.  PREPARING THE CONFIGURATION FILE:
 
    -Go to the "configs" directory for default configuration examples, and instructions
     on how to build your configuration file.
    -Copy the completed configuration file into the "bufrobs" directory.  The name of the
     production configuration file needs to be "bufrupprair_config".
    -Ensure that the configuration file includes the names of all BUFR files that you would
     like to be operated on. 
    
4.  RUNNING THE DECODER SOFTWARE:

    -To decode the BUFR data according to the instructions in your configuration file,
     go into the "bufrobs" directory and execute "../exe/bufrupprair.x"
    -To generically dump output from an individual file, go into the "bufrobs" directory and execute
     "../exe/dumpbufr.x".  From here you will be prompted to enter the name of the file
     from which you would like all output to be dumped. 



*** Additional information ***

Downloading the RDADB ds351.0 BUFR data files is supported from the "Data
Access" tab near the top of the ds351.0 home page

    http://rda.ucar.edu/datasets/ds351.0/ 

RDA ds351.0 file names have the form: gdasupaobs.yyyymmdd.tar.gz. Individual
BUFR files must be extracted from the tar.gz files for use with the decoders. 
This can be done after files are copied to the "bufrobs" directory, by editing
and running the "exe/preprocess.csh" shell script.

Linux users NO LONGER NEED to preprocess BUFR files using the "grabbufr" tool. 
The included BUFRLIB (v10.2.3 or greater) handles endian-ness internally.