NetCDF I/O

  

To create a netCDF file, one can use

      ret = zio_nf_create(filename,cmode,iocomm,filedesc)

which indicates that data will be written in the netCDF creation mode cmode (nf_clobber, nf_share, or nf_write) using the I/O staging communicator iocomm. This I/O channel is referred to as filedesc. Similarly a file can be open in the open mode omode with

      ret = zio_nf_open(filename,omode,iocomm,filedesc)

Many netCDF functions can be invoked in a similar way as the regular netCDF functions would be - only with a netCDF file ID replaced with a file descriptor:

      ret = zio_nf_set_fill(filedesc,nf_fill,old_fillmode)
      ret = zio_nf_def_dim(filedesc,'longitude',nx,lonid)
      ret = zio_nf_def_var(filedesc,'temperature',NF_DOUBLE,3,dimids,varid)
      ret = zio_nf_put_att_double(filedesc,varid,attname,xtype,length,arr)
      ret = zio_nf_enddef(filedesc)
      ret = zio_nf_inq_varid(filedesc,'temperature',varid)

Variables are written or read using

      ret = zio_nf_put_var_double(filedesc,varid,t)
      ret = zio_nf_get_var_double(filedesc,varid,t)

As in the case of the unformatted I/O, if the current process's parallel subdomain is made of multiple separate blocks, t contains all the local data contiguously one block after another, following the block order used to define distarray.

Writing or reading an array section of a variable can be done with:

      ret = zio_nf_get_vara_double(filedesc,varid,istart,icount,t)
      ret = zio_nf_put_vara_double(filedesc,varid,istart,icount,t)

In the examples above, the distributed array descriptor for variable t is assumed to be already added to the distributed array descriptor list using zio_add_to_list with the same variable name used for defining the netCDF variable (i.e., `temperature'). (See Section .) If it is not on the list or a user does not want to use the feature of storing to and retrieving from the list, the argument distarray must be provided at the end of the argument list.

NOTE: In netCDF istart and icount used to refer only to the array section in the netCDF data space in disk, but not array's memory space. However, currently we let istart and icount refer to an array section in both the netCDF data and memory space. That is, an array section in netCDF data space is written from or read into the corresponding section of the global array.

istart and icount must be in the output index order. That is, they must be in the order specified when the netCDF variable is defined.

One thing to remember when using ZioLib netCDF functions is that a Fortran 90 module provides an explicit interface for module procedures. One consequence is that, if a dummy argument for a procedure is an array, the actual argument must be an array, too. (But array ranks of the actual and dummy arguments do not have to match if the dummy argument is an assumed-size array.) For example, if a single scalar value, say `0', is to be written with zio_nf_put_vara_double, the actual argument must be in an array form:

      ret = zio_nf_put_vara_double(filedesc,varid,istart,icount,(/0/))

This restriction must be observed in other netCDF routines, too. For example, one must write

   ret = zio_nf_def_var(filedesc,'lat',NF_DOUBLE,1,(/latdim/),latvar)
   ret = zio_nf_def_var(filedesc,'P0', NF_DOUBLE,0,(/0/),ps0var) ! scalar var

instead of zio_nf_def_var(filedesc,'lat',NF_DOUBLE,1,latdim,latvar) and zio_nf_def_var (filedesc,'P0',NF_DOUBLE,0,0,ps0var), respectively.

Currently the functions of the varm and vars families are not supported.

A file is closed with

      ret = zio_nf_close(filedesc)