1.3 Reading a netCDF file with Unknown Names

It is possible to write programs (e.g., generic software) which do such things as processing every variable, without needing to know in advance the names of these variables. Similarly, the names of dimensions and attributes may be unknown.

Names and other information about netCDF objects may be obtained from netCDF files by calling inquire functions. These return information about a whole netCDF file, a dimension, a variable, or an attribute. The following template illustrates how they are used:

    ncmpi_open                          /* open existing netCDF file */
      ... 
    ncmpi_inq                           /* find out what is in it */
         ... 
       ncmpi_inq_dim                    /* get dimension names, lengths */
         ... 
       ncmpi_inq_var                    /* get variable names, types, shapes */
            ... 
          ncmpi_inq_attname             /* get attribute names */
            ... 
          ncmpi_inq_att                 /* get attribute types and lengths */
            ... 
          ncmpi_get_att                 /* get attribute values */
            ... 
       ncmpi_get_var<kind>_<type>_all   /* (collectively) read values of a variable */
         ... 
    ncmpi_close                         /* close netCDF file */

As in the previous example, a single call opens the existing netCDF file, returning a netCDF ID. This netCDF ID is given to the ncmpi_inq routine, which returns the number of dimensions, the number of variables, the number of global attributes, and the ID of the unlimited dimension, if there is one.

All the inquire functions are inexpensive to use and require no I/O, since the information they provide is stored in memory when a netCDF file is first opened.

Dimension IDs use consecutive integers, beginning at 0. Also dimensions, once created, cannot be deleted. Therefore, knowing the number of dimension IDs in a netCDF file means knowing all the dimension IDs: they are the integers 0, 1, 2, ... up to the number of dimensions. For each dimension ID, a call to the inquire function ncmpi_inq_dim returns the dimension name and length.

Variable IDs are also assigned from consecutive integers 0, 1, 2, ... up to the number of variables. These can be used in ncmpi_inq_var calls to find out the names, types, shapes, and the number of attributes assigned to each variable.

Once the number of attributes for a variable is known, successive calls to ncmpi_inq_attname return the name for each attribute given the netCDF ID, variable ID, and attribute number. Armed with the attribute name, a call to ncmpi_inq_att returns its type and length. Given the type and length, you can allocate enough space to hold the attribute values. Then a call to a member of the ncmpi_get_att family returns the attribute values.

Once the IDs and shapes of netCDF variables are known, data values can be accessed by calling a member of the ncmpi_get_var1 family for single values, or members of the ncmpi_get_var, ncmpi_get_vara, ncmpi_get_vars, or ncmpi_get_varm for various kinds of array access.

Full example C program

• pnetcdf-read-standard.c