Go to the previous, next section.

Creating a NetCDF File

The typical sequences of C netCDF calls used to create a new netCDF file follows. For clarity we only present the name of the routines, omit all declarations, parameters and error checking, and use ... to represent arbitrary sequences of other statements:

    nccreate      /* create netCDF file: enter define mode */
         ...
       ncdimdef   /* dimension definitions: from name and size */
         ...
       ncvardef   /* variable definitions: from name, type, dimensions */
         ...
       ncattput   /* attribute put: assign attribute values */
         ...
    ncendef       /* end definitions: leave define mode */
         ...
    ncvarput      /* variable put: provide values for variables */
      ...
    ncattput      /* attribute put: change attribute values */
      ...
    ncclose       /* close: save new netCDF file */

In FORTRAN, the corresponding sequence looks like this:

    NCCRE              ! create netCDF file: enter define mode
         ...
       NCDDEF          ! define dimensions: from name and size
         ...
       NCVDEF          ! define variables: from name, type, dimensions
         ...
       NCAPT or NCAPTC ! attribute put: assign attribute values
         ...
    NCENDF             ! end definitions: leave define mode
         ...
    NCVPT or NCVPTC    ! variable put: provide values for variables
      ...
    NCAPT or NCAPTC    ! attribute put: change attribute values
      ...
    NCCLOS             ! close: save new netCDF file

The FORTRAN interface provides two subroutines for defining attributes and providing values for variables, depending on whether a numeric or character string value is used. The FORTRAN template indicates that either of these subroutines could be called.

Only one call is needed to begin creating a netCDF file, at which point you will be in the first of two netCDF modes. When accessing a netCDF, you are either in define mode or data mode. In define mode, you can create dimensions, variables, and new attributes, but you cannot read or write variable data. In data mode, you can access data and change existing attributes, but you are not permitted to create new dimensions, variables, or attributes.

One call to ncdimdef (or NCDDEF) is needed for each dimension created. Similarly, one call to ncvardef (or NCVDEF) is needed for each variable creation, and one call to ncattput (or NCAPT or NCAPTC) is needed for each attribute defined and assigned a value. The only way to leave define mode and enter data mode is by a call to ncendef (or NCENDF).

Once in data mode, you can add new data to variables, change old values, and change values of existing attributes (so long as the attribute changes do not require more storage space for the attribute). Single values are written to a variable with ncvarput1 (or NCVPT1 or NCVP1C); while arbitrary hyperslabs of data are written using ncvarput or ncvarputg (or NCVPT, NCVPTC, NCVPTG, or NCVPGC) instead. Multi-variable records of data may be written using multiple calls to ncvarput (or NCVPT) or with a single call to ncrecput.

Finally, you should explicitly close all open netCDF files on which you are writing by calling ncclose (or NCCLOS) before the program exits. If a program terminates abnormally with netCDF files open for writing, you may lose one or more records of the most recently written record variable data as well as any attribute changes since the last call to ncsync (or NCSNC). It is possible to reduce the chance of losing data due to abnormal termination by explicitly calling ncsync (NCSNC) after every write to netCDF variables or change to attribute values. This can be expensive in computer resources, so such calls should ordinarily be omitted unless they are really needed.

Go to the previous, next section.