1.2 Reading a NetCDF file with Known Names

Here we consider the case where you know the names of not only the netCDF files, but also the names of their dimensions, variables, and attributes. (Otherwise you would have to do "inquire" calls.) The order of typical C calls to read data from those variables in a netCDF file is:

ncmpi_open                       /* open existing netCDF file (collective) */
    ... 
ncmpi_inq_dimid                  /* use file ID to get dimension IDs (independent) */
    ... 
ncmpi_inq_varid                  /* use file ID to get variable IDs (independent) */
    ... 
ncmpi_get_att                    /* use variable ID to get the variable's attribute values (independent) */
    ... 
ncmpi_inq_varndims               /* get the number of dimensions of variable (independent) */
    ... 
ncmpi_inq_vardimid               /* get the dimension IDs of the variable (independent) */
    ... 
ncmpi_inq_dimlen                 /* for each dimension ID, get the dimension size (independent) */
    ... 
/* use the variable's dimension information to allocate read buffer */
    ... 
ncmpi_get_var<kind>_<type>_all   /* read values of a variable (collective) */
    ... 
ncmpi_close                      /* close netCDF file (collective) */

First, a single call opens the netCDF file, given the file name, and returns a netCDF ID that is used to refer to the opened netCDF file in all subsequent calls. Next, one can make a call to ncmpi_inq_dimid to inquire the dimension ID of a given known dimension name. Similarly, each required variable ID is determined from its name by a call to ncmpi_inq_varid. Once variable IDs are known, variable attribute values can be retrieved using the netCDF ID, the variable ID, and the desired attribute name as input to a member of the ncmpi_get_att family (typically ncmpi_get_att_text or ncmpi_get_att_double) for each desired attribute. The IDs of dimensions used to defined a variable can be obtained by calling ncmpi_inq_vardimid. Together with ncmpi_inq_dimlen, which returns the size of a dimension, the dimension shape and size can be known and a read buffer can be allocated. Variable data values can be directly accessed from the netCDF file with calls to members of the ncmpi_get_var1 family for single values, the ncmpi_get_var family for entire variables, or various other members of the ncmpi_get_vara, ncmpi_get_vars, or ncmpi_get_varm families for array, subsampled or mapped access.

Finally, the netCDF file is closed with ncmpi_close. Close the file even if it is opened only for reading.

Full example C program

• get_vara.c