     [file version-tutorial.texi not included]

     [file defines.texi not included]

NetCDF Tutorial
***************

This tutorial aims to give a quick and painless introduction to netCDF. Then again, the guillotine was also intended to be painless.

The first chapter, ``What is NetCDF?,'' covers the basics concepts of netCDF. Read this to understand the netCDF data model.

The second chapter, ``Example Programs,'' contains three sets of examples of increasing complexity. The example programs are provided for each of four netCDF API languages, C, C++, F77, and F90.

The final chapter, ``The Functions You Need in NetCDF-3,'' provides a quick reference to the important functions in each API, with hyper-links to the full documentation of each function.

This document applies to netCDF version VERSION; it was last updated on UPDATED.

What is NetCDF?
***************

NetCDF is a set of data formats, programming interfaces, and software libraries that help read and write scientific data files.

NetCDF was developed and is maintained at Unidata.

Unidata, funded primarily by the National Science Foundation, is one of eight programs in the University Corporation for Atmospheric Research (UCAR) Office of Programs (UOP).

Unidata provides data and software tools for use in geoscience education and research. For more information see the web sites of Unidata (unidata-url), UOP (uop-url), and UCAR (ucar-url).

This tutorial may serve as an introduction to netCDF. Full netCDF documentation is available on-line (see Documentation).

The NetCDF Data Model
=====================

The netCDF data model consists of variables, dimensions, and attributes.

Variables
     N-dimensional arrays of data. Variables in netCDF files can be one of six types (char, byte, short, int, float, double). For more information see Variables (n-man).

Dimensions
     describe the axes of the data arrays. A dimension has a name and a length. An unlimited dimension has a length that can be expanded at any time, as more data are written to it. NetCDF files can contain at most one unlimited dimension. For more information see Dimensions (n-man).

Attributes
     annotate variables or files with small notes or supplementary metadata. Attributes are always scalar values or 1D arrays, which can be associated with either a variable or the file as a whole. Although there is no enforced limit, the user is expected to keep attributes small. For more information see Attributes (n-man).

For more information on the netCDF data model see The NetCDF Data Model (n-man).

Meteorological Example
----------------------

NetCDF can be used to store many kinds of data, but it was originally developed for the Earth science community.

NetCDF views the world of scientific data in the same way that an atmospheric scientist might: as sets of related arrays. There are various physical quantities (such as pressure and temperature) located at points at a particular latitude, longitude, vertical level, and time.

A scientist might also like to store supporting information, such as the units, or some information about how the data were produced.

The axis information (latitude, longitude, level, and time) would be stored as netCDF dimensions. Dimensions have a length and a name.

The physical quantities (pressure, temperature) would be stored as netCDF variables. Variables are N-dimensional arrays of data, with a name and an associated set of netCDF dimensions.

It is also customary to add one variable for each dimension, to hold the values along that axis. These variables are call ``coordinate variables.'' The latitude coordinate variable would be a one-dimensional variable (with latitude as it's dimension), and it would hold the latitude values at each point along the axis.

The additional bits of metadata would be stored as netCDF attributes.

Attributes are always single values or one-dimensional arrays. (This works out well for a string, which is a one-dimensional array of ASCII characters.)

The pres_temp_4D example in this tutorial shows how to write and read a file containing some four-dimensional pressure and temperature data, including all the metadata needed. See pres_temp_4D.

NetCDF Error Handling
=====================

Each netCDF function in the C, Fortran 77, and Fortran 90 APIs returns 0 on success, in the tradition of C. (For C++, see below).

When programming with netCDF in these languages, always check return values of every netCDF API call. The return code can be looked up in netcdf.h (for C programmers) or netcdf.inc (for Fortran programmers), or you can use the strerror function to print out an error message. (See nc_strerror (c-man)/NF_STRERROR (f77-man)/NF90_STRERROR (f90-man)).

In general, if a function returns an error code, you can assume it didn't do what you hoped it would. The exception is the NC_ERANGE error, which is returned by any of the reading or writing functions when one or more of the values read or written exceeded the range for the type. (For example if you were to try to read 1000 into an unsigned byte.)

In the case of NC_ERANGE errors, the netCDF library completes the read/write operation, and then returns the error. The type conversion is handled like a C type conversion, whether or not it is within range. This may yield bad data, but the netCDF library just returns NC_ERANGE and leaves it up to the user to handle. (For more information about type conversion see Type Conversion (c-man)).

Error handling in C++ is different. For some objects, the is_valid() method should be called. Other error handling is controlled by the NcError class. For more information see Class NcError (cxx-man).

For a complete list of netCDF error codes see Error Codes (c-man).

Unlimited Dimensions
====================

Sometimes you don't know the size of all dimensions when you create a file, or you would like to arbitrarily extend the file along one of the dimensions.

For example, model output usually has a time dimension. Rather than specifying that there will be forty-two output times when creating the file, you might like to create it with one time, and then add data for additional times, until you wanted to stop.

For this purpose netCDF provides the unlimited dimension. By specifying a length of ``unlimited'' when defining a dimension, you indicate to netCDF that the dimension may be extended, and its length may increase.

In netCDF files, there can only be one unlimited dimension, and it must be declared first in the list of dimensions for a variable.

For programmers, the unlimited dimension will correspond with the slowest-varying dimension. In C this is the first dimension of an array, in Fortran, the last.

The third example in this tutorial, pres_temp_4D, demonstrates how to write and read data one time step at a time along an unlimited dimension. See pres_temp_4D.

For more detailed information about dimensions see Dimensions (n-man).

Fill Values
===========

Sometimes there are missing values in the data, and some value is needed to represent them.

For example, what value do you put in a sea-surface temperature variable for points over land?

In netCDF, you can create an attribute for the variable (and of the same type as the variable) called ``_FillValue'' that contains a value that you have used for missing data. Applications that read the data file can use this to know how to represent these values.

Using attributes it is possible to capture metadata that would otherwise be separated from the data. Various conventions have been established. By using a set of conventions, a data producer is more likely to produce files that can be easily shared within the research community, and that contain enough details to be useful as a long-term archive.

For more information on _FillValue and other attribute conventions, see Attribute Conventions (n-man).

Climate and meteorological users are urged to follow the Climate and Forecast (CF) metadata conventions when producing data files. For more information about the CF conventions, see cf-url.

For information about creating attributes, see Creation.

Tools for Manipulating NetCDF Files
===================================

Many existing software applications can read and manipulate netCDF files. Before writing your own program, check to see if any existing programs meet your needs.

Two utilities come with the netCDF distribution: ncdump and ncgen. The ncdump command reads a netCDF file and outputs ASCII in a format called CDL. The ncgen command reads an ASCII file in CDL format, and generates a netCDF data file.

One common use for ncdump is to examine the metadata of a netCDF file, to see what it contains. At the beginning of each example in this tutorial, an ncdump of the resulting data file is shown. See simple_xy.

For more information about ncdump and ncgen see NetCDF Utilities (n-man).

The following general-purpose tools have been found to be useful in many situations. Some of the tools on this list are developed at Unidata. The others are developed elsewhere, and we can make no guarantees about their continued availability or success. All of these tools are open-source.

UDUNITS
Unidata library to help with scientific units.
udunits-url

IDV
Unidata's Integrated Data Viewer, a 3D visualization and analysis
package (Java based).
idv-url

NCL
NCAR Command Language, a graphics and data manipulation package.
ncl-url

GrADS
The Grid Analysis and Display System package.
grads-url

NCO
NetCDF Command line Operators, tools to manipulate netCDF files.
nco-url

For a list of netCDF tools that we know about see netcdf-software-url. If you know of any that should be added to this list, send email to netcdf-support-email.

The NetCDF Programming APIs
===========================

Unidata supports netCDF APIs in C, C++, Fortran 77, Fortran 90, and Java.

The Java API is a complete implementation of netCDF in Java. It is distributed independently of the other APIs. For more information see the netCDF Java page: netcdf-java-url. If you are writing web server software, you should certainly be doing so in Java.

The C, C++, Fortran 77 and Fortran 90 APIs are distributed and installed when the netCDF C library is built, if compilers exist to build them, and if they are not turned off when configuring the netCDF build.

The C++ and Fortran APIs depend on the C API. Due to the nature of C++ and Fortran 90, users of those languages can also use the C and Fortran 77 APIs (respectively) directly.

Full documentation exists for each API (see Documentation).

In addition, many other language APIs exist, including Perl, Python, and Ruby. Most of these APIs were written and supported by netCDF users. Some of them are listed on the netCDF software page, see netcdf-software-url.

In addition to the main netCDF-3 C API, there is an additional (older) C API, the netCDF-2 API. This API produces exactly the same files as the netCDF-3 API - only the API is different. (That is, users can create either classic format files, the default, or 64-bit offset files.)

The version 2 API was the API before netCDF-3.0 came out. It is still fully supported, however. Programs written to the version 2 API will continue to work.

Users writing new programs should use the netCDF-3 API, which contains better type checking, better error handling, and better documentation.

The netCDF-2 API is provided for backward compatibility. Documentation for the netCDF-2 API can be found on the netCDF website, see v2-docs-url.

NetCDF Documentation
====================

This tutorial is brief. A much more complete description of netCDF can be found in n-man. It fully describes the netCDF model and format. For more information see n-man.

The netCDF distribution, in various forms, can be obtained from the netCDF web site: netcdf-url.

A porting and installation guide for the C, C++, Fortran 77, and Fortran 90 APIs describes how to build these APIs on a variety of platforms. See i-man.

Language specific programming guides are available for netCDF for the C, C++, Fortran 77, Fortran 90, and Java APIs:

C
     c-man.

C++
     cxx-man.

Fortran 77
     f77-man.

Fortran 90
     f90-man.

Java
     netcdf-java-man-url.

Man pages for the C, F77, and F90 interfaces, and ncgen and ncdump, are available on the documentation page of the netCDF web site (docs-url), and are installed with the netCDF distribution.

The latest version of all netCDF documentation can always be found at the documentation page of the netCDF web site: docs-url

A Note on NetCDF Versions and Formats
=====================================

NetCDF has changed (and improved) over its lifetime. That means the user must have some understanding of netCDF versions.

To add to the confusion, there are versions for the APIs, and also for the data files that they produce. The API version is the version number that appears in the tarball file that is downloaded from the netCDF website. For example the current version is VERSION.

Since version 3.6.0 there are two versions of the netCDF file format. Both underlying formats are accessed by the same netCDF API, but are stored differently on disk. The formats are called ``classic format,'' and ``64-bit offset format.''

The good news is that all netCDF files ever written can always be read by the latest netCDF release. That is, we guarantee backward data compatibility.

As long as you have a version of netCDF greater than 3.6.0, you can use either format. To share data in 64-bit offset format, everyone who wants to read the data must use at least version 3.6.0.

The default format is classic format. To get 64-bit offset format, set a flag when creating the file. For more information about the format, see Format (n-man).

Classic format has some strict limitations for files larger than two gigabytes. (see NetCDF Classic Format Limitations (n-man)).

64-bit offset is very useful for very large data files (over two gigabytes), however these files can only be shared with those who have upgraded to version 3.6.0 (or better) of netCDF. Earlier versions of netCDF will not be able to read these files.

The Future of NetCDF
====================

NetCDF continues under active development at Unidata (see unidata-url).

The upcoming and long anticipated release of netCDF-4.0 will introduce another format: HDF5. This does not represent the weakening of support for the classic and 64-bit offset formats! NetCDF-4.0 will maintain full backward compatibility, and will continue to use classic format by default. NetCDF-4.0 will introduce many interesting new features, such as groups and compound data types, which will only be available for files using the HDF5 format. Classic and 64-bit offset files will behave as always, and will be fully supported in netCDF-4.

NetCDF-4 is in advanced alpha release, and adventurous users can try it out for themselves, but it is not ready for operational use and won't be until HDF5 1.8.0 is released. See netcdf-4-url.

The netCDF-Java library has many advanced capabilities, and is actively maintained and developed. See netcdf-java-man-url.

Example Programs
****************

The netCDF example programs show how to use netCDF.

In the netCDF distribution, the ``examples'' directory contains examples in C, Fortran 77, Fortran 90, C++, and CDL. There are three sets of example programs in each language. Each language has its own subdirectory under the ``examples'' directory (for example, the Fortran 77 examples are in ``examples/F77'').

The examples are built and run with the ``make check'' command. (For more information on building netCDF, see i-man).

The examples create, and then read, three different example files, of increasing complexity.

The corresponding examples in each language create identical netCDF data files. For example, the C program sfc_pres_temp_wr.c produces the same data file as the Fortran 77 program sfc_pres_temp_wr.f.

For convenience, the complete source code in each language can be found in this tutorial, as well as in the netCDF distribution.

The simple_xy Example
=====================

This example is an unrealistically simple netCDF file, to demonstrate the minimum operation of the netCDF APIs. Users should seek to make their netCDF files more self-describing than this primitive example.

As in all the netCDF tutorial examples, this example file is created by C, Fortran 77, Fortran 90, and C++ programs, and by ncgen, which creates it from a CDL script. All examples create identical files, ``simple_xy.nc.''

The programs that create this sample file all have the base name ``simple_xy_wr'', with different extensions depending on the language.

Therefore the example files that create simple_xy.nc can be found in: C/simple_xy_wr.c, F77/simple_xy_wr.f, F90/simple_xy_wr.f90, CXX/simple_xy_wr.cpp, and CDL/simple_xy_wr.cdl.

Corresponding read programs (C/simple_xy_rd.c, etc.) read the simple_xy.nc data file, and ensure that it contains the correct values.

The simple_xy.nc data file contains two dimensions, ``x'' and ``y'', and one netCDF variable, ``data.''

The utility ncdump can be used to show the contents of netCDF files. By default, ncdump shows the CDL description of the file. This CDL description can be fed into ncgen to create the data file.

The CDL for this example is shown below. For more information on ncdump and ncgen see NetCDF Utilities (n-man).

          [file simple_xy.cdl not included]

simple_xy_wr.c and simple_xy_rd.c
---------------------------------

These example programs can be found in the netCDF distribution, under examples/C.

The example program simple_xy_wr.c creates the example data file simple_xy.nc. The example program simple_xy_rd.c reads the data file.

simple_xy_wr.c
..............

          [file simple_xy_wr.c not included]

simple_xy_rd.c
..............

          [file simple_xy_rd.c not included]

simple_xy_wr.f and simple_xy_rd.f
---------------------------------

These example programs can be found in the netCDF distribution, under examples/F77.

The example program simple_xy_wr.f creates the example data file simple_xy.nc. The example program simple_xy_rd.f reads the data file.

simple_xy_wr.f
..............

          [file simple_xy_wr.f not included]

simple_xy_rd.f
..............

          [file simple_xy_rd.f not included]

simple_xy_wr.f90 and simple_xy_rd.f90
-------------------------------------

These example programs can be found in the netCDF distribution, under examples/F90.

The example program simple_xy_wr.f90 creates the example data file simple_xy.nc. The example program simple_xy_rd.f90 reads the data file.

simple_xy_wr.f90
................

          [file simple_xy_wr.f90 not included]

simple_xy_rd.f90
................

          [file simple_xy_rd.f90 not included]

simple_xy_wr.cpp and simple_xy_rd.cpp
-------------------------------------

These example programs can be found in the netCDF distribution, under examples/CXX.

The example program simple_xy_wr.cpp creates the example data file simple_xy.nc. The example program simple_xy_rd.cpp reads the data file.

simple_xy_wr.cpp
................

          [file simple_xy_wr.cpp not included]

simple_xy_rd.cpp
................

          [file simple_xy_rd.cpp not included]

The sfc_pres_temp Example
=========================

This example has been constructed for the meteorological mind.

Suppose you have some data you want to write to a netCDF file. For example, you have one time step of surface temperature and surface pressure, on a 6 x 12 latitude longitude grid.

To store this in netCDF, create a file, add two dimensions (latitude and longitude) and two variables (pressure and temperature).

In this example we add some netCDF attributes, as is typical in scientific applications, to further describe the data. In this case we add a units attribute to every netCDF variable.

In this example we also add additional netCDF variables to describe the coordinate system. These ``coordinate variables'' allow us to specify the latitudes and longitudes that describe the data grid.

The CDL version of the data file, generated by ncdump, is shown below.

For more information on ncdump and ncgen see NetCDF Utilities (n-man).

          [file sfc_pres_temp.cdl not included]

sfc_pres_temp_wr.c and sfc_pres_temp_rd.c
-----------------------------------------

These example programs can be found in the netCDF distribution, under examples/C.

The example program sfc_pres_temp_wr.c creates the example data file sfc_pres_temp.nc. The example program sfc_pres_temp_rd.c reads the data file.

sfc_pres_temp_wr.c
..................

          [file sfc_pres_temp_wr.c not included]

sfc_pres_temp_rd.c
..................

          [file sfc_pres_temp_rd.c not included]

sfc_pres_temp_wr.f and sfc_pres_temp_rd.f
-----------------------------------------

These example programs can be found in the netCDF distribution, under examples/F77.

The example program sfc_pres_temp_wr.f creates the example data file sfc_pres_temp.nc. The example program sfc_pres_temp_rd.f reads the data file.

sfc_pres_temp_wr.f
..................

          [file sfc_pres_temp_wr.f not included]

sfc_pres_temp_rd.f
..................

          [file sfc_pres_temp_rd.f not included]

sfc_pres_temp_wr.f90 and sfc_pres_temp_rd.f90
---------------------------------------------

These example programs can be found in the netCDF distribution, under examples/F90.

The example program sfc_pres_temp_wr.f90 creates the example data file sfc_pres_temp.nc. The example program sfc_pres_temp_rd.f90 reads the data file.

sfc_pres_temp_wr.f90
....................

          [file sfc_pres_temp_wr.f90 not included]

sfc_pres_temp_rd.f90
....................

          [file sfc_pres_temp_rd.f90 not included]

sfc_pres_temp_wr.cpp and sfc_pres_temp_rd.cpp
---------------------------------------------

These example programs can be found in the netCDF distribution, under examples/CXX.

The example program sfc_pres_temp_wr.cpp creates the example data file sfc_pres_temp.nc. The example program sfc_pres_temp_rd.cpp reads the data file.

sfc_pres_temp_wr.cpp
....................

          [file sfc_pres_temp_wr.cpp not included]

sfc_pres_temp_rd.cpp
....................

          [file sfc_pres_temp_rd.cpp not included]

The pres_temp_4D Example
========================

This example expands on the previous example by making our two-dimensional data into four-dimensional data, adding a vertical level axis and an unlimited time step axis.

Additionally, in this example the data are written and read one time step at a time, as is typical in scientific applications that use the unlimited dimension.

The sample data file created by pres_temp_4D_wr can be examined with the utility ncdump. The output is shown below. For more information on ncdump see NetCDF Utilities (n-man).

          [file pres_temp_4D.cdl not included]

pres_temp_4D_wr.c and pres_temp_4D_rd.c
---------------------------------------

These example programs can be found in the netCDF distribution, under examples/C.

The example program pres_temp_4D_wr.c creates the example data file pres_temp_4D.nc. The example program pres_temp_4D_rd.c reads the data file.

pres_temp_4D_wr.c
.................

          [file pres_temp_4D_wr.c not included]

pres_temp_4D_rd.c
.................

          [file pres_temp_4D_rd.c not included]

pres_temp_4D_wr.f and pres_temp_4D_rd.f
---------------------------------------

These example programs can be found in the netCDF distribution, under examples/F77.

The example program pres_temp_4D_wr.f creates the example data file pres_temp_4D.nc. The example program pres_temp_4D_rd.f reads the data file.

pres_temp_4D_wr.f
.................

          [file pres_temp_4D_wr.f not included]

pres_temp_4D_rd.f
.................

          [file pres_temp_4D_wr.f not included]

pres_temp_4D_wr.f90 and pres_temp_4D_rd.f90
-------------------------------------------

These example programs can be found in the netCDF distribution, under examples/F90.

The example program pres_temp_4D_wr.f90 creates the example data file pres_temp_4D.nc. The example program pres_temp_4D_rd.f90 reads the data file.

pres_temp_4D_wr.f90
...................

          [file pres_temp_4D_wr.f90 not included]

pres_temp_4D_rd.f90
...................

          [file pres_temp_4D_wr.f90 not included]

pres_temp_4D_wr.cpp and pres_temp_4D_rd.cpp
-------------------------------------------

These example programs can be found in the netCDF distribution, under examples/CXX.

The example program pres_temp_4D_wr.cpp creates the example data file pres_temp_4D.nc. The example program pres_temp_4D_rd.cpp reads the data file.

pres_temp_4D_wr.cpp
...................

          [file pres_temp_4D_wr.cpp not included]

pres_temp_4D_rd.cpp
...................

          [file pres_temp_4D_wr.cpp not included]

The Functions You Need in NetCDF-3
**********************************

The netCDF-3 C and Fortran APIs each have over 100 functions, but most users need only a handful. Listed below are the essential netCDF functions for four important tasks in netCDF: creating new files, reading existing files, learning about a netCDF file of unknown structure, and reading and writing subsets of data.

In each case the functions are presented for each of the four language APIs: C, Fortran 77, Fortran 90, and C++, with hyper-links to the detailed documentation of each function.

Creating New Files and Metadata, an Overview
============================================

To construct a netCDF file you need to:

create the file
     Specify the name, optionally the format: classic (the default) or 64bit-offset.

define metadata
     Specify the names and types of dimensions, data variables, and attributes.

write data
     Write arrays of data from program variables to the netCDF file. Arrays of data may be written all at once, or in subsets.

close the file
     Close the file to flush all buffers to the disk and free all resources allocated for this file.

Creating a NetCDF File in C
---------------------------

Use nc_create to create a file. Then use nc_def_dim to define each shared dimension. The data variables are then specified with nc_def_var. Any attributes are added with nc_put_att. Finally, call nc_enddef to tell the library that you are done defining the metadata, and ready to start writing the data.

After all data are written to the file, call nc_close to ensure that all buffers are flushed, and any resources associated with the open file are returned to the operating system.

For a very simple example, see simple_xy in C.

For a typical sequence of calls to the C versions of these functions, see Creating a NetCDF Dataset (c-man).

nc_create (c-man)
create a new netCDF file

nc_def_dim (c-man)
define a dimension

nc_def_var (c-man)
define a variable

nc_put_att_ type (c-man)
write attributes

nc_enddef (c-man)
leave define mode

nc_put_vara_ type (c-man)
write arrays of data

nc_close (c-man)
close a file

Creating a NetCDF File in Fortran 77
------------------------------------

Use NF_CREATE to create a file. Then use NF_DEF_DIM to define each shared dimension. The data variables are then specified with NF_DEF_VAR. Any attributes are added with NF_PUT_ATT. Finally, call NF_ENDDEF to tell the library that you are done defining the metadata, and ready to start writing the data.

After all data are written to the file, call NF_CLOSE to ensure that all buffers are flushed, and any resources associated with the open file are returned to the operating system.

For a typical sequence of calls see Creating a NetCDF Dataset (f77-man).

Fortran users take note: the netCDF Fortran 77 API consists of wrappers around the functions of the netCDF C library. There is no Fortran 77 code in netCDF except for these wrappers, and tests to ensure that the wrappers work.

The name of each Fortran function shows the outline of the C function it wraps (for example, NF_CREATE is a wrapper around nc_create).

NF_CREATE (f77-man)
create a new netCDF file

NF_DEF_DIM (f77-man)
define a dimension

NF_DEF_VAR (f77-man)
define a variable

NF_PUT_ATT_ type (f77-man)
write an attribute

NF_ENDDEF (f77-man)
end define mode

NF_PUT_VARA_ type (f77-man)
write arrays of data

NF_CLOSE (f77-man)
close the netCDF file

Creating a NetCDF File in Fortran 90
------------------------------------

Use NF90_CREATE to create a file. Then use NF90_DEF_DIM to define each shared dimension. The data variables are then specified with NF90_DEF_VAR. Any attributes are added with NF90_PUT_ATT. Finally, call NF90_ENDDEF to tell the library that you are done defining the metadata, and ready to start writing the data.

After all data are written to the file, call NF90_CLOSE to ensure that all buffers are flushed, and any resources associated with the open file are returned to the operating system.

For a typical sequence of calls see Creating a NetCDF Dataset (f90-man).

The netCDF Fortran 90 API calls the Fortran 77 API, which in turn calls the netCDF C library.

The name of each Fortran function shows the outline of the F77 function it wraps (for example, NF90_CREATE is a wrapper around NF_CREATE). The F77 functions are, in turn, wrappers around the C functions.

NF90_CREATE (f90-man)
create a netCDF file

NF90_DEF_DIM (f90-man)
define a dimension

NF90_DEF_VAR (f90-man)
define a variable

NF90_PUT_ATT_ type (f90-man)
write an attribute

NF90_ENDDEF (f90-man)
end define mode

NF90_PUT_VARA_ type (f90-man)
write arrays of data

NF90_CLOSE (f90-man)
close the netCDF file

Creating a NetCDF File in C++
-----------------------------

Create an instance of the NcFile class to create a netCDF file. Use its add_dim and add_var methods to add dimensions and variables. The add_att method is available for both NcFile and NcVar.

Use the NcError class to specify error handling behavior.

For an example creating a simple file see simple_xy_wr.cpp. For a more complex example see pres_temp_4D_wr.cpp.

Class NcFile (cxx-man)
a C++ class to manipulate netCDF files

Class NcDim (cxx-man)
a C++ class to manipulate netCDF dimensions

Class NcVar (cxx-man)
a C++ class to manipulate netCDF variables

Class NcAtt (cxx-man)
a C++ class to manipulate netCDF attributes

Class NcError (cxx-man)
a C++ class to control netCDF error handling

Reading NetCDF Files of Known Structure
=======================================

To read a netCDF file of known structure, you need to:

open the file
     Specify the file name and whether you want read-write or read-only access.

read variable or attribute data
     Read the data or attributes of interest.

close the file
     Release all resources associated with this file.

Use ncdump to learn the structure of a file (use the -h option). For more information about ncdump see NetCDF Utilities (n-man).

Numbering of NetCDF IDs
-----------------------

In C, Fortran 77, and Fortran 90, netCDF objects are identified by an integer: the ID. NetCDF functions use this ID to identify the object. It's helpful for the programmer to understand these IDs.

Open data files, dimensions, variables, and attributes are each numbered independently, and are always numbered in the order in which they were defined. (They also appear in this order in ncdump output.) Numbering starts with 0 in C, and 1 in Fortran 77/90.

For example, the first variable defined in a file will have an ID of 0 in C programs, and 1 in Fortran programs, and functions that apply to a variable will need to know the ID of the variable you mean.

(The numbering of files is an exception: file IDs are assigned by the operating system when a file is opened, and are not permanently associated with the file. IDs for netCDF dimensions and variables are persistent, but deleting an attribute changes subsequent attribute numbers.)

Although netCDF refers to everything by an integer id (varid, dimid, attnum), there are inquiry functions which, given a name, will return an ID. For example, in the C API, nc_inq_varid will take a character string (the name), and give back the ID of the variable of that name. The variable ID is then used in subsequent calls (to read the data, for example).

Other inquiry functions exist to further describe the file. (see Inquiry Functions).

Reading a Known NetCDF File in C
--------------------------------

For a typical sequence of calls to these C functions see Reading a NetCDF Dataset with Known Names (c-man).

nc_open (c-man)
open a netCDF file

nc_get_att (c-man)
read an attribute

nc_get_vara_ type (c-man)
read arrays of data

nc_close (c-man)
close the file

Reading a Known NetCDF File in Fortran 77
-----------------------------------------

For a typical sequence of calls to these functions see Reading a NetCDF Dataset with Known Names (f77-man).

NF_OPEN (f77-man)
open a netCDF file

NF_GET_ATT (f77-man)
read an attribute

NF_GET_VARA_ type (f77-man)
read arrays of data

NF_CLOSE (f77-man)
close the file

Reading a Known NetCDF File in Fortran 90
-----------------------------------------

For a typical sequence of calls to these functions see Reading a NetCDF Dataset with Known Names (f90-man).

NF90_OPEN (f90-man)
open a netCDF file

NF90_GET_ATT (f90-man)
read an attribute

NF90_GET_VARA (f90-man)
read arrays of data

NF90_CLOSE (f90-man)
close the file

Reading a Known NetCDF File in C++
----------------------------------

Class NcFile (cxx-man)
a C++ class to manipulate netCDF files

Class NcDim (cxx-man)
a C++ class to manipulate netCDF dimensions

Class NcVar (cxx-man)
a C++ class to manipulate netCDF variables

Class NcAtt (cxx-man)
a C++ class to manipulate netCDF attributes

Reading NetCDF Files of Unknown Structure
=========================================

Perhaps you would like to write your software to handle more general cases, so that you don't have to adjust your source every time the grid size changes, or a variable is added to the file.

There are inquiry functions that let you find out everything you need to know about a file. These functions contain ``inq'' or ``INQ'' in their names.

Using the inquiry functions, it is possible to write code that will read and understand any netCDF file, whatever its contents. (For example, ncdump does just that.)

Inquiry in C
------------

First use nc_inq, which will tell you how many variables and global attributes there are in the file.

Start with global attribute 0, and proceed to natts - 1, the number of global attributes minus one. The nc_inq_att function will tell you the name, type, and length of each global attribute.

Then start with dimid 0, and proceed to dimid ndims - 1, calling nc_inq_dim. This will tell you the name and length of each dimension, and whether it is unlimited.

Then start with varid 0, and proceed to varid nvars - 1, calling nc_inq_var. This will tell you the number of dimensions of this variable, and their associated IDs. It will also get the name and type of this variable, and whether there are any attributes attached. If there are attributes attached, use the nc_inq_att function to get their names, types, and lengths.

(To read an attribute, use the appropriate nc_get_att_<TYPE> function, like nc_get_att_int() to get the data from an attribute that is an array of integers.)

There are also functions that return an item's ID, given its name. To find IDs from the names, use functions nc_inq_dimid, nc_inq_attnum, and nc_inq_varid.

For a typical sequence of calls to these functions see Reading a netCDF Dataset with Unknown Names (c-man).

NULL Parameters in Inquiry Functions
....................................

With any of the C inquiry functions, a NULL pointer can be used to ignore a return parameter. Consider the nc_inq function:

     EXTERNL int
     nc_inq(int ncid, int *ndimsp, int *nvarsp, int *nattsp, int *unlimdimidp);

If you call this with NULL for the last three parameters, you can learn the number of dimensions without bothering about the number of variables, number of global attributes, and the ID of the unlimited dimension.

For further convenience, we provide functions like nc_inq_ndims, which only finds the number of dimensions, exactly as if you had called nc_inq, with NULLs in all parameters except ndimsp. (In fact, this is just what the nc_inq_ndims functions does).

nc_inq (c-man)
Find number of dimensions, variables, and global attributes, and the unlimited dimid.

nc_inq_att (c-man)
Find attribute name, type, and length.

nc_inq_dim Family (c-man)
Find dimension name and length.

nc_inq_var (c-man)
Find variable name, type, num dimensions, dim IDs, and num attributes.

nc_inq_dimid (c-man)
Find dimension ID from its name.

nc_inq_varid (c-man)
Find variable ID from its name.

nc_inq_format (c-man)
Find file format: classic or 64-bit offset

nc_inq_libvers (c-man)
Find the netCDF version. (Currently VERSION).

Inquiry in Fortran 77
---------------------

First use NF_INQ, which will tell you how many variables and global attributes there are in the file. Then start with varid 1, and proceed to varid nvars, calling NF_INQ_VAR.

For a typical sequence of calls to these functions see Reading a netCDF Dataset with Unknown Names (f77-man).

NF_INQ (f77-man).
Find number of dimensions, variables, and global attributes, and the unlimited dimid.

NF_INQ_DIM (f77-man).
Find dimension name and length.

NF_INQ_VARID (f77-man).
Find variable ID from its name.

NF_INQ_VAR (f77-man).
Find variable name, type, num dimensions, dim IDs, and num attributes.

NF_INQ_DIMID (f77-man).
Find dimension ID from its name.

NF_INQ_DIM (f77-man).
Find dimension name and length.

NF_INQ_ATT (f77-man).
Find attribute name, type, and length.

NF_INQ_FORMAT (f77-man).
Find file format: classic or 64-bit offset

NF_INQ_LIBVERS (f77-man).
Find the netCDF version. (Currently VERSION).

Inquiry in Fortran 90
---------------------

First use NF90_INQ, which will tell you how many variables and global attributes there are in the file. Then start with varid 1, and proceed to varid nvars, calling NF90_INQ_VAR.

For a typical sequence of calls to these functions, see Reading a netCDF Dataset with Unknown Names (f90-man).

NF90_INQ (f90-man).
Find number of dimensions, variables, and global attributes, and the unlimited dimid.

NF90_INQ_DIM (f90-man).
Find dimension name and length.

NF90_INQ_VARID (f90-man).
Find variable ID from its name.

NF90_INQ_VAR (f90-man).
Find variable name, type, num dimensions, dim IDs, and num attributes.

NF90_INQ_DIMID (f90-man).
Find dimension ID from its name.

NF90_INQ_DIM (f90-man).
Find dimension name and length.

NF90_INQ_ATT (f90-man).
Find attribute name, type, and length.

NF90_INQ_FORMAT (f90-man).
Find file format: classic or 64-bit offset

NF90_INQ_LIBVERS (f90-man).
Find the netCDF version. (Currently VERSION).

Inquiry Functions in the C++ API
--------------------------------

Class NcFile (cxx-man)
a C++ class to manipulate netCDF files

Class NcDim (cxx-man)
a C++ class to manipulate netCDF dimensions

Class NcVar (cxx-man)
a C++ class to manipulate netCDF variables

Class NcAtt (cxx-man)
a C++ class to manipulate netCDF attributes

Reading and Writing Subsets of Data
===================================

Usually users are interested in reading or writing subsets of variables in a netCDF data file. The netCDF APIs provide a variety of functions for this purpose.

In the simplest case, you will use the same type for both file and in-memory storage, but in some cases you may wish to use different types. For example, you might have a netCDF file that contains integer data, and you wish to read it into floating-point storage, converting the data as it is read. The same sort of type conversion can be done when writing the data.

To convert to a type while reading data, use the appropriate nc_get_vara_<TYPE> or NF_GET_VARA_<TYPE> function. For example, the C function nc_get_vara_float(), and the Fortran function NF_GET_VARA_REAL will read netCDF data of any numeric type into a floating-point array, automatically converting each element to the desired type.

To convert from a type while writing data, use the appropriate nc_put_vara_<TYPE> or NF_PUT_VARA_<TYPE> function. For example, the C function nc_put_vara_float(), and the Fortran function NC_PUT_VARA_REAL will write floating-point data into netCDF arrays, automatically converting each element of the array to the type of the netCDF variable.

The <TYPE> in the function name refers to the type of the in-memory data, in both cases. They type of the file data is determined when the netCDF variable is defined.

Reading and Writing Subsets of Data in C
----------------------------------------

The type of the data may be automatically converted on read or write. For more information about type conversion see Type Conversion (c-man).

Read the entire variable at once
nc_get_var_ type (c-man)

Write the entire variable at once
nc_put_var_ type (c-man)

Read just one value
nc_get_var1_ type (c-man)

Write just one value
nc_put_var1_ type (c-man)

Read an array subset
nc_get_vara_ type (c-man)

Write an array subset
nc_put_vara_ type (c-man)

Read an array with strides
nc_get_vars_ type (c-man)

Write an array with strides
nc_put_vars_ type (c-man)

Reading and Writing Subsets of Data in Fortran 77
-------------------------------------------------

The type of the data may be automatically converted on read or write. For more information about type conversion see Type Conversion (f77-man).

Read the entire variable at once
NF_GET_VAR_ type (f77-man)

Write the entire variable at once
NF_PUT_VAR_ type (f77-man)

Read just one value
NF_GET_VAR1_ type (f77-man)

Write just one value
NF_PUT_VAR1_ type (f77-man)

Read an array subset
NF_GET_VARA_ type (f77-man)

Write an array subset
NF_PUT_VARA_ type (f77-man)

Read an array with strides
NF_GET_VARS_ type (f77-man)

Write an array with strides
NF_PUT_VARS_ type (f77-man)

Reading and Writing Subsets of Data in Fortran 90
-------------------------------------------------

The type of the data may be automatically converted on read or write. For more information about type conversion see Type Conversion (f90-man).

Read the entire variable at once
NF90_GET_VAR_ type (f90-man)

Write the entire variable at once
NF90_PUT_VAR_ type (f90-man)

Read just one value
NF90_GET_VAR1_ type (f90-man)

Write just one value
NF90_PUT_VAR1_ type (f90-man)

Read an array subset
NF90_GET_VARA_ type (f90-man)

Write an array subset
NF90_PUT_VARA_ type (f90-man)

Read an array with strides
NF90_GET_VARS_ type (f90-man)

Write an array with strides
NF90_PUT_VARS_ type (f90-man)

Reading and Writing Subsets of Data in C++
------------------------------------------

To read a record of data at a time, use the set_cur method of the NcVar class to set the number of the record of interest, and then use the get method to read the record.

Class NcVar (cxx-man)
a C++ class to manipulate netCDF variables, use the set_cur and
get methods to read records from a file.