Re: 19990223: Getting started with netcdf

>To: address@hidden
>From: David Larkin <address@hidden>
>Subject: Getting started with netcdf
>Organization: DJL Software Consultancy Ltd
>Keywords: 199902231443.HAA29030

Hi Dave,

> I'm new to netcdf, and have a couple of questions.
> I'd appreciate any advise you can offer.
> 
> Are there a set of example  tutorial programs anywhere ?
> I'm thinking along the lines of the excellent HDF examples at
> 
> http://hdf.ncsa.uiuc.edu/training/HDFtraining/
> 
> I remember being up and running in no time with HDF.
> 
> I'm struggling to get even the simplest examples together from the
> examples in Chapter 5 Datasets of the User's guide for C.
> I'm not sure whether this is down to my understanding of netcdf,
> or Visual C++ , to which I'm new, and on which I've installed netcdf.

No, unfortunately we haven't developed such a complete set of examples
for our C or Fortran interfaces.  However, here is a list of some less
complete examples that you may find useful:

1.  Output from "ncgen -c".  The ncgen program can generate C code for
    writing a netCDF file, if given a simple CDL text file describing the
    structure of the data.  For example, try putting the following in the
    file "foo.cdl" and then invoking "ncgen -c foo.cdl" and ncgen will
    generate C code on standard output that will write the netCDF file
    "foo.nc":
 
    netcdf foo {
    dimensions:
      nx=10; ny=5;
    variables:
      float data1(nx,ny);
    data:
      data1= 0, 1, 2, 3, 4,
             1, 2, 3, 4, 5,
             2, 3, 4, 5, 6,
             3, 4, 5, 6, 7,
             4, 5, 6, 7, 8,
             5, 6, 7, 8, 9,
             6, 7, 8, 9,10,
             7, 8, 9,10,11,
             8, 9,10,11,12,
             9,10,11,12,13;
    }

    Use of ncgen on the above will generate a file with the same
    structure as the first HDF example, sd_create.c, at
    http://hdf.ncsa.uiuc.edu/training/HDFtraining/examples/sd_create.c
    All the "check_err()" calls in the resulting code are just to
    provide an example with all possible error checking, so you can
    ignore those on first reading.  Note:  "ncgen -f" will generate
    the corresponding Fortran code.

2.  See the C and C++ examples in the cxx/ directory of the source
    distribution, "example.c" and "example.cc".  Both these examples
    show how to create and write a more complex netCDF file, first
    using the C interface, then using the C++ interface.  The file
    "nctst.cc" in that directory extends the C++ example to also read
    data in from the resulting file and print the data that was in
    it.

3.  The "do_ncdump" function in the file "ncdump/ncdump.c" from the
    source distribution shows how to read all the data from a generic
    netCDF file, by using the "inquire" functions and the read
    functions to determine all the necessary information about
    dimensions, variables, and attributes in the file.  This is
    complicated by the formatting ncdump does to try to make the
    output look nice, but it still provides a pretty good example of
    how to extract all the information from a netCDF file about which
    you nothing else is known.

4.  The user-contributed programs available from 
    http://www.unidata.ucar.edu/packages/netcdf/contrib.html
    provide a few more examples.  In particular, the program "nccat.c"
    is a simple, well-commented example of a utility that concatenates
    netCDF files, and "tbl2cdf.c" converts data in a flat ASCII table
    into a netCDF file.

5.  We've written a fairly complete set of examples for using the new
    netCDF for Java package, available from:

      http://www.unidata.ucar.edu/packages/netcdf/java/examples/

> I tried hunting through the mail list archives for example code and
> found a totally different programming style using nc* rather than
> nc_* functions.
> 
> eg
> 
> ncid = nccreate("foo.nc",NC_CLOBBER);
> 
> rather than
> 
> status = nc_create("foo.nc",NC_CLOBBER,&ncid);
> 
> Are they both legal/supported?
> I can't find any reference to the former in documentation.

This is the difference between the netCDF version 2 and netCDF version
3 interfaces.  The current netCDF software supports both interfaces,
and the file format has not changed.  An explanation of why we
designed the new netCDF-3 interface and what its advantages over the
netCDF-2 interface are is available from "Appendix D - NetCDF 2 C
Transition Guide", available online at:

  http://www.unidata.ucar.edu/packages/netcdf/guidec/guidec-20.html#HEADING20-0

You can write using either the version-2 or version-3 interfaces, or
even mix the two, though that can be confusing.  We still document the
old version 2 interfaces in the netCDF-2 User's Guide, available from
our documentation page at 

  http://www.unidata.ucar.edu/packages/netcdf/docs.html

The older examples above use the netCDF-2 interface, while the newer
ones and the output of ncgen use the netCDF-3 interface.  If you are
learning netCDF for the first time, I'd recommend the netCDF-3
interface, even though it's larger.  The new interface is more
orthogonal, which should make it easier to understand.  The interfaces
are very similar for most purposes; the differences are mostly due to
the clearer separation of internal and external representation in
netCDF-3 and to a different style of error handling.

--Russ

_____________________________________________________________________

Russ Rew                                         UCAR Unidata Program
address@hidden                     http://www.unidata.ucar.edu