Go to the previous, next section.

Reading a netCDF File with Unknown Names

If you want to write generic software (i.e., a program that transposes specified variables by interchanging specified dimensions) you should make no assumptions about the dimension and variable names that are not specified. In such cases, you must find out about all the dimensions, variables, and attributes in a netCDF file by calling the inquire functions. Four inquire functions get information about a whole netCDF file, a dimension, a variable, or an attribute. The following template illustrates how they are used: 
    ncopen           /* open existing netCDF */
      ...
    ncinquire        /* find out what is in it */
         ...
       ncdiminq      /* get dimension names, sizes */
         ...
       ncvarinq      /* get variable names, types, shapes */
            ...
          ncattname  /* get attribute names */
            ...
          ncattinq   /* get attribute types and lengths */
            ...
          ncattget   /* get attribute values */
            ...
    ncvarget         /* get values of variables */
      ...
    ncclose          /* close netCDF */

In FORTRAN, the corresponding sequence looks like this: 

    NCOPN                 !  open existing netCDF 
      ...
    NCINQ                 !  find out what is in it 
         ...
       NCDINQ             !  get dimension names, sizes 
         ...
       NCVINQ             !  get variable names, types, shapes 
            ...
          NCANAM          !  get attribute names 
            ...
          NCAINQ          !  get attribute values 
            ...
          NCAGT or NCAGTC !  get attribute values 
            ...
    NCVGT or NCVGTC       !  get values of variables 
      ...
    NCCLOS                !  close netCDF

As in the previous example, a single call opens the existing netCDF file, returning a netCDF ID. This netCDF ID is given to the ncinquire (or NCINQ) 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.

Another inquire function, ncrecinq, is provided for convenience to return information about record variables, although the information is also obtainable by using the other inquire functions. The ncrecinq function returns the number of record variables, their variable IDs, and how much memory space is needed for a record's worth of data for each record variable.

All the inquire functions are quite inexpensive to use and require no I/O, since the information they provide is stored in a table in memory for each open netCDF file. In the C interface, the inquire functions also support getting a subset of information by providing NULL pointers instead of valid addresses for undesired information.

Dimension IDs are assigned by using consecutive integers (beginning at 0 in C, 1 in FORTRAN). 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, ..., (or 1, 2, 3, ... in FORTRAN). For each dimension ID, a call to the inquire function ncdiminq (or NCDINQ) returns the dimension name and size.

Like dimension IDs, variable IDs are also 0, 1, 2, ..., (or 1, 2, 3, ... in FORTRAN). These can be used in ncvarinq (or NCVINQ) 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 ncattname (or NCANAM) return the name for each attribute given the netCDF ID, variable ID, and attribute number. Armed with the attribute name, a call to ncattinq (or NCAINQ) returns its type and length. Given the type and length, the generic application can allocate enough space to hold the attribute values. Then a call to ncattget (or NCAGT or NCAGTC) returns the attribute values.

Once the names, IDs, types, shapes, and lengths of all netCDF components are known, data values can be accessed by calling ncvarget1 (or NCVGT1 or NCVG1C) for single values, ncvarget or ncvargetg (or NCVGT, NCVGTC, NCVGTG, or NCVGGC) for aggregates of values using hyperslab access, or ncrecget for aggregates of values using record access.

Go to the previous, next section.