1.1 Creating a NetCDF file

Here is a typical sequence of PnetCDF calls to create a new netCDF file:

ncmpi_create                     /* create netCDF file and enter define mode (collective) */
       ... 
ncmpi_def_dim                    /* define dimensions: from name and length (collective) */
       ... 
ncmpi_def_var                    /* define variables: from name, type, ... (collective) */
       ... 
ncmpi_put_att                    /* put attribute: assign attribute values (collective) */
       ... 
ncmpi_enddef                     /* end definitions: leave define mode (collective) */
       ... 
ncmpi_put_var<kind>_<type>_all   /* (collectively) write values of a variable (collective) */
       ... 
ncmpi_begin_indep_data           /* enter independent data mode (collective) */
       ... 
ncmpi_put_var<kind>_<type>       /* write values of a variable (independent) */
       ... 
ncmpi_end_indep_data             /* exiting independent data mode (collective) */
       ... 
ncmpi_close                      /* close: save new netCDF file (collective) */

Only one call is needed to create a netCDF file, at which point you will be in the first of two netCDF modes. When accessing an open netCDF file, it is in either 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 ncmpi_def_dim is needed for each dimension created. Similarly, one call to ncmpi_def_var is needed for each variable creation, and one call to a member of the ncmpi_put_att family is needed for each attribute defined and assigned a value. To leave define mode and enter data mode, call ncmpi_enddef.

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). Single values may be written to a netCDF variable with one of the members of the ncmpi_put_var1 family, depending on what type of data you have to write. All the values of a variable may be written at once with one of the members of the ncmpi_put_var family. Arrays or array cross-sections of a variable may be written using members of the ncmpi_put_vara family. Subsampled array sections may be written using members of the ncmpi_put_vars family. Mapped array sections may be written using members of the ncmpi_put_varm family. (Subsampled and mapped access are general forms of data access that are explained later.)

Finally, you should explicitly close all netCDF files that have been opened for writing by calling ncmpi_close. PnetCDF might cache file header locally. If a program terminates abnormally with netCDF files open for writing, your most recent modifications may be lost.