NAME:

   ncdf_quickread


SYNOPSIS:

   This is a routine for reading variables into an IDL session from a 
   NetCDF file, in just a very few commands.


DESCRIPTION:

1) Ensure that the supplied routines are installed in your IDL_PATH.

         ncdf_quickread.pro
         ncdf_quickread_helper.pro

2) Set the string variable NCFILE to the NetCDF filename you wish to write,
   For example:

         ncfile='myfile.nc'

3) Optionally set the following variables:

         ncprefix : prefix to prepend to all variable names when importing
                    from NetCDF variable name into IDL namespace

         ncverbose : set equal to 1 if you want to include attributes

         ncfields : Set to a string which is a space-separated list of
                    variables to read.  Only the variables specified will be
                    read in (and where ncverbose is set, only the attributes
                    associated with these variables and the global attributes).
                    If unset or the null string, then reads all fields.

4) Type:  @ncdf_quickread


USAGE EXAMPLES:

1) SIMPLE EXAMPLE.

      => You have the following NetCDF file:
           "ncdump -h mslp.djf.nc" reports the following:

         netcdf mslp.djf {
         dimensions:
                 longitude = 96 ;
                 latitude = 73 ;
                 msl = 1 ;
                 t = UNLIMITED ; // (100 currently)
         variables:
                 float longitude(longitude) ;
                         longitude:units = "degrees_east" ;
                         longitude:point_spacing = "even" ;
                         longitude:modulo = " " ;
                 float latitude(latitude) ;
                         latitude:units = "degrees_north" ;
                         latitude:point_spacing = "even" ;
                 float msl(msl) ;
                         msl:units = "level" ;
                         msl:positive = "up" ;
                 float t(t) ;
                         t:units = "days since 1991-09-01 00:00:00" ;
                         t:calendar = "360_day" ;
                         t:time_origin = "01-SEP-1991:00:00:00" ;
                 float p_2(t, msl, latitude, longitude) ;
                         p_2:source = "Unified Model Output (Vn 4.6):" ;
                         p_2:name = "p_2" ;
                         p_2:title = "PRESSURE AT MEAN SEA LEVEL" ;
                         p_2:date = "01/09/91" ;
                         p_2:time = "00:00" ;
                         p_2:long_name = "PRESSURE AT MEAN SEA LEVEL" ;
                         p_2:units = "Pa" ;
                         p_2:missing_value = 2.e+20f ;
                         p_2:_FillValue = 2.e+20f ;
                         p_2:valid_min = 97130.55f ;
                         p_2:valid_max = 103777.6f ;
         
         // global attributes:
                         :history = "Thu Oct  2 14:34:56 BST 2003 - XCONV V1.90 04-September-2002" ;
         }

      => You issue the following commands:

            ncfile='mslp.djf.nc'
            @ncdf_quickread

      =>  This imports the following into IDL:

                  LATITUDE        FLOAT     = Array[73]
                  LONGITUDE       FLOAT     = Array[96]
                  MSL             FLOAT     =       0.00000
                  P_2             FLOAT     = Array[96, 73, 100]
                  T               FLOAT     = Array[100]


          By the way, also a few variables get set as a side-effect,
          but these can be ignored.

                  NCFILE          STRING    = 'mslp.djf.nc'
                  NCPREFIX        UNDEFINED = <Undefined>
                  NCVERBOSE       UNDEFINED = <Undefined>
                  __COMMANDS      STRING    = Array[8]
                  __LOOP          INT       =        8
                  __NCID          LONG      =            1


2) MORE COMPLEX EXAMPLE.

      => You have the same NetCDF file shown above.

      => You issue the following commands:

           ncfile='mslp.djf.nc'
           ncverbose=1
           ncprefix='djf_'
           @ncdf_quickread

      =>  This imports the following into IDL:

             DJF_HISTORY     STRING    = 'Thu Oct  2 14:34:56 BST 2003 - XCONV V1.90 04'...
             DJF_LATITUDE    FLOAT     = Array[73]
             DJF_LATITUDE_POINT_SPACING
                             STRING    = 'even'
             DJF_LATITUDE_UNITS
                             STRING    = 'degrees_north'
             DJF_LONGITUDE   FLOAT     = Array[96]
             DJF_LONGITUDE_MODULO
                             STRING    = ' '
             DJF_LONGITUDE_POINT_SPACING
                             STRING    = 'even'
             DJF_LONGITUDE_UNITS
                             STRING    = 'degrees_east'
             DJF_MSL         FLOAT     =       0.00000
             DJF_MSL_POSITIVE
                             STRING    = 'up'
             DJF_MSL_UNITS   STRING    = 'level'
             DJF_P_2         FLOAT     = Array[96, 73, 100]
             DJF_P_2_DATE    STRING    = '01/09/91'
             DJF_P_2_LONG_NAME
                             STRING    = 'PRESSURE AT MEAN SEA LEVEL'
             DJF_P_2_MISSING_VALUE
                             STRING    = '  2.00000e+20'
             DJF_P_2_NAME    STRING    = 'p_2'
             DJF_P_2_SOURCE  STRING    = 'Unified Model Output (Vn 4.6):'
             DJF_P_2_TIME    STRING    = '00:00'
             DJF_P_2_TITLE   STRING    = 'PRESSURE AT MEAN SEA LEVEL'
             DJF_P_2_UNITS   STRING    = 'Pa'
             DJF_P_2_VALID_MAX
                             STRING    = '      103778.'
             DJF_P_2_VALID_MIN
                             STRING    = '      97130.5'
             DJF_P_2__FILLVALUE
                             STRING    = '  2.00000e+20'
             DJF_T           FLOAT     = Array[100]
             DJF_T_CALENDAR  STRING    = '360_day'
             DJF_T_TIME_ORIGIN
                             STRING    = '01-SEP-1991:00:00:00'
             DJF_T_UNITS     STRING    = 'days since 1991-09-01 00:00:00'

BUGS:

  => Not sure.


LIMITATIONS:

  => IDL variable names are case-insensitive, so there could be a namespace
     conflict if variable names in the NetCDF file differ only in case

AUTHOR:

   CDF2IDL original: S. Rupert
   Adapted by Alan Iwi <A.M.Iwi@rl.ac.uk>


COPYRIGHT:

   This routine is based on CDF2IDL which is in the public domain.
   The modifications by Alan Iwi are also in the public domain.

   But the IDL program itself is subject to copyright restrictions.


SEE ALSO:

    CDF2IDL original:  http://www-c4.ucsd.edu/~cids/software/visual.html