Latest changes 05/09/2003 by CAS

The changes to netopen should allow all COARDS-CF compatible files to be read via gridread and similar routines. In addition, you should be able to read all netCDF files that are COARDS compatible but don't have udunits times. In those cases, gridread and similar routines will return -99,-99,-99,-99 for
year, month,day and hour. Routines like timeindex or dayread that rely on time will NOT work for those files.

The gridread, gridreadx, dayread, and dayreadx subroutines are set up
to read rectangular or Gaussian gridded data of up to 1441x721 points
and return an array starting at the South pole and proceding North
regardless of how the data is stored in the actual netCDF file.
The specread subroutine is capable of reading up to 4032 spectral coefficients
(truncation of 124).
Further, since dynamic allocation is not standard in Fortran 77, it is
important that you pass in an array variable which is dimensioned
according to the size of the grid (or vector of spectral coefficients)
in the netCDF file. (Note: you can
determine this by using the ncdump -c command on the file). If you pass an
array that is too small the software will crash, and if it is too large the
indexing will be wrong.

This software can be used to read grid sizes larger than 1441x720 by changing the maxlat and maxlon parameters to the appropriate grid size.
Additionally, by changing the maxnumvalues parameter the spectral coefficient
truncation size readable can be increased.

Basic steps to reading a netCDF file in fortran code:

Put the following at the top of your program (starting in column 7 or
greater):

The filepathname should be the full name and might be something like /Datasets/cmap/enh/precip.mon.mean.nc". ierr and ierr2 are integers which can hold the return error code. variable is the netCDF variable such as "sst" or "hgt". You will use inet for the file id and ivar for the variable id for a particaular file.

To read a (previously opened) file and retrieve a rectangular or Gaussian
grid (depending on the file that was opened) for one time period,
you can use either gridread or gridreadx. The grid returned will be
ordered South to North regardless of the order of data in the netCDF file.
These routines have identical interfaces except that gridreadx returns
an extra longitude vector in the grid (a copy of the longitude vector in column
1 is placed in the last column e.g. 145x73 for 2.5 degree data).
Here is the details of calling gridread:

If you wish to have the subroutine increment the time index for you
automatically, set iadd=1 for gridread. The subroutine will automatically
advance the time increment for you at the START of the subroutine. So, be
sure to set itime to 1 less than the first time index if you use that
option.

To read more than one netCDF data variable or level at a time using the same
time index program variable, you should set iadd=0 for the calls to retrieve
the additional variables or levels. Time index values are specific to a
dataset. So if you are reading one dataset that starts on Jan 1, 1985 and
another dataset that starts on Dec 1 1984, the time index value for the same
time will NOT be the same. Therefore it is advisable to use a different
program variable for each of the datasets.

gridread and gridreadx will advance to the next file if the read extends beyond
the last record of the current file. (Like netread2 in the previous version).
To read more than one data variable at the same time, set iadd=0 for the other
data variables. Alternatively, use a separate time index variable for each
data variable.

All functions in this library return grids from South to North regardless of
how the data is stored in the netCDF file.

To read a (previously opened) file and retrieve a vector of spectral
coefficients for one time period,
you can use either specread.
This routine has an identical interface to that of the gridread routine.
Here is a description of the use of specread:

If you wish to have the subroutine increment the time index for you
automatically, set iadd=1 for gridread. The subroutine will automatically
advance the time increment for you at the START of the subroutine. So, be
sure to set itime to 1 less than the first time index if you use that
option.

To read more than one netCDF data variable or level at a time using the same
time index program variable, you should set iadd=0 for the calls to retrieve
the additional variables or levels. Time index values are specific to a
dataset. So if you are reading one dataset that starts on Jan 1, 1985 and
another dataset that starts on Dec 1 1984, the time index value for the same
time will NOT be the same. Therefore it is advisable to use a different
program variable for each of the datasets.

gridread and gridreadx will advance to the next file if the read extends beyond
the last record of the current file.

Where ny,nm,nd and nh are specified (iadd and itime are ignored on input,
itime is returned). Or if you would like an extra longitude vector
(like gridreadx) call dayreadx which has the same parameter list as dayread.
The grid returned will be ordered South to North regardless of the
order of the data in the netCDF file.

which has the same parameters as netread2 with the exception that nhead is a
single integer. nhead will take on one of four values indicating the following
interpolation information for the grid represented:

0) no interpolation
1) both hemispheres interpolated
2) just NH
3) just SH

Then use the automatic increment feature of gridread(x) and when the record
beyond the last record in dataset 1 is read, the same variable and statistic
(if existent) will be opened in dataset 2 and the netid and variable ids will
be set properly.

If you wished your program to resemble the sequential type read that you may
have used in previous programs, (where you needed the extra longitude vector
for IDL or something like that) your code could look something like this:

If you run into any problems when you run your netCDF reading program, see if
any of the below might apply. If not, I will be happy to look at your code.
If you discover any bugs or non-robustness of any of the subroutines or if you
have any suggestions, please bring them to my attention A.S.A.P..

If you run into problems because your code has too many files open, you
can use the NCCLOS command to close any files that you are finished with.
The syntax is CALL NCCLOS(nc_fileid, RCODE).

Make sure that the size of the grid or vector (spectral coefficients) is
the same as that in the netCDF file (use ncdump -h to learn
about the dimensions)

Be sure that all subroutine parameters are the right type
(i.e. integer,real, character, etc). NetCDF is very picky about such
things. Especially the new floating point level value!

Don't ask for data that does not exist. For example, there are
no relative humidities above 300mb and you can't get slp at 1000mb
for the NCEP data. Also, make sure you have spelled all dataset and variable
names correctly (see below).

Make sure that you are using the appropriate variable IDs and file
IDs.

If you choose to have the subroutine keep track of the time index,
don't have it advanced for other data variables you wish to read at the same
time (unless you use different names for the time index variable).

The data descriptions have more detailed descriptions of what is in a particular
dataset (e.g. dates, variable names, levels, statistics), references for that
dataset and caveats on the use of the data.
We also provide a
summary of PSD datasets.
ASCII versions of the dataset descriptions are in the README files
located in the
~ftp/Datasets subdirectories.

Levels in netopen are needed when files in the datasets are divided by levels.
This applies to the nmc2d, nmcltm, and cddb datasets. Levels are needed
in the gridread(x) and dayread(x) commands when a particular
file is divided into different levels. This applies to the nmc, nmcrean, nmcp,
and nmcmm. Levels should be specified as floating point values (1000.0, 850.0,
200.0, etc.).

There are several "special" levels in the netopen call.
The NCEP/NCAR and ECMWF surface is represented as 2000.0
The NCEP/NCAR Reanalysis tropopause level is represented as 3000.0.
Use 0.0 as the level for the NCEP/NCAR Reanalysis pressure level data and the
NCEP (Leetmaa) Ocean data and other data sets with multi-level files.

When referring to variable names, the following are applicable in netopen
- Note that not all datasets have all variables (in fact as you'll note below
some datasets use different variable names for the same physical variable)
so you should check the
PSD Data Directory
Dataset List for the variable(s)/dataset(s) in which you are interested.
These are sorted by netopen variable id for those variables that are in more
than one dataset.