----------------------
RSASDUMP Program Usage
----------------------


1.0  Introduction
-----------------

The MADIS RSASDUMP software can be used to read a netCDF file
containing analyzed and derived surface grids produced by the FSL
Rapid Update Cycle (RUC) Surface Assimilation System (RSAS) and output
selected grids to a text file, which can then be further processed by
your application software.  In addition to the grids themselves, the
indices of the grid points can be output, as well as their latitude
and longitude coordinates.  The analyzed elevations of the stations
whose data were assimilated are also available.

The operation of the program is controlled by a text parameter file
that allows the user to select which variables and location
information to output, as well as the units to be used, the number of
significant digits, and the separator to be used between fields.

The output will consist of one line per grid point that will contain
all of the variables that have been selected, using the field
separator that has been selected, and output with the number of
significant digits that have been selected.  Since the grid is ordered
I=1-580 in the X direction (east to west), and J=1-548 in the Y
direction (south to north), there will be 580 * 548 lines in all.  The
grid is scanned from south to north, one column at a time.  In other
words, J=1, I=1,...,580 produces the first 580 lines, then J=2,
I=1,...,580, etc.

For example, if you asked for I, J, latitude, longitude,
temperature (in degrees F), and pressure (in mb), with 7 
significant digits and a comma separator, the first few
lines of output would look like this:

1.000000,1.000000,9.961596,-128.0000,76.29261,1010.247
2.000000,1.000000,9.994704,-127.9206,76.35594,1010.246
3.000000,1.000000,10.02772,-127.8412,76.41637,1010.247
4.000000,1.000000,10.06065,-127.7616,76.47251,1010.247
5.000000,1.000000,10.09348,-127.6820,76.52211,1010.247
6.000000,1.000000,10.12621,-127.6023,76.56353,1010.247

This document describes how to setup the parameter file, how to run the 
program, and what to expect in the way of outputs.  


2.0  How to Run
---------------

1.  Setup the desired parameters in a rsasdump parameter file.

2.  Move to the directory in which you'll be running the program.

4.  Copy the parameter file to the run directory, and make sure that its 
    name is "rsasdump.par".

5.  Run the program.  (rsasdump.exe)

6.  Outputs:

    a.  The input parameters will be output to the screen.
    
    b.  Any error messages will be output to the screen.

    b.  The data that's been obtained will be written to the output file
        specified in rsasdump.par.  


3.0  How to Setup the Parameter File
------------------------------------

A sample parameter file is contained in the software distribution package.
The parameter file is split into two sections, with each section delimited
by a line of "----------"'s.  


3.1  Control Section
---------------------

---------------------------------------------------------------------------------
              Control Parameters                          FIXED LENGTH SECTION
              ------------------
20050210_1200                    INPUT NETCDF FILE     
1200.txt                         TEXT OUTPUT DUMP
7                                NUMBER OF SIGNIFICANT DIGITS (1-7)
F                                TEMPERATURE UNITS (C,K,F)             
MPH                              WIND SPEED UNITS (M/S,MPH,KTS)
MB                               PRESSURE UNITS (PA,MB)
M                                ELEVATION UNITS (M,F)
C                                VARIABLE DATA SEPARATOR (S(SPACE),C(COMMA))
---------------------------------------------------------------------------------

The user selects the input file (which must already be unzipped), the
output file and the options on units and output format.  The options
are not case sensitive, so either lower or upper-case characters can
be used.  The options include the number of significant digits, units
scale, and the variable separator character.  The number of
significant digits can be from 1 to 7. The temperature units allowed
are C, K, and F.  The wind units allowed are M/S, MPH, and KTS.  The
pressure units allowed are PA and MB.  The elevation units allowed are
M and F.  The variable separators allowed are "S" for space or "C" for
comma.

If you are accessing the input file via OPeNDAP/DODS from the MADIS
web server the input file name should be a URL pointing to the desired
file on the server for your data distribution category, with the
username and password embedded in the URL.  Here's an example for user
SAMPLE_madis_public, with password xyz123.  [This should all be
specified on one line, it's been split into two lines here for
readability.]

http://SAMPLE_madis_public:xyz123@www.madis-fsl.org/madisPublic/cgi-bin/
nph-dods/DODS/madis/public/Grid/FSL/netCDF/RSAS/20050210_1200.gz

Note that the labels on the right in the Control Section, such as 
"INPUT NETCDF FILE", don't have to be there at all, or can be pushed to the
right if you need more space for your filenames (such as with this 
OPeNDAP/DODS URL).


3.2  Variables Section
----------------------

---------------------------------------------------------------------------------
              Variables (1 per line, until end of file)   VARIABLE LENGTH SECTION
              --------- 
I
J
LAT
LON
T
P
---------------------------------------------------------------------------------

This is the last section in the parameter file.  The code names for
the variables to be dumped should be listed, one per line, until the
end of file is reached.  (The section delimiter line shown here is
simply for readability.  If you have this line or any other
non-variable line in the real parameter file you'll get an error.)

The variables should be specified in the order in which you want them
output (left-to-right) on each line, separated by the selected separator.  
The code names are not case sensitive.

The complete list of variables names and definitions follows:

I       - X grid point index (1 to 580)
J       - Y grid point (1 to 548)
LAT     - Latitude
LON     - Longitude
T       - Temperature
TD      - Dew point temperature
U       - U wind component
V       - V wind component
EPT     - Equivalent potential temperature
P       - Pressure
ELEV    - Topography
PT3     - 3-hr pressure tendency
THETA   - Potential temperature
DPD     - Dew point depression
RMSLP   - RSAS mean sea level pressure
MSLP    - NWS mean sea level pressure
ALT     - Altimeter
Q       - Specific humidity


4.0  How to compile the source code
------------------------------------

Prebuilt RSASDUMP binaries are available for most Unix/Linux platforms
and can be found at:

  http://www-sdd.fsl.noaa.gov/MADIS/rsasdump.html

If your platform isn't supported, or if you want to try to build with
OPeNDAP capability on a platform other than Linux, see the instructions
on that webpage.
