10 NetCDF IO

10.1 Module cpl_iocdf_mod - create and write-to netcdf data file. (Source File: cpl_iocdf_mod.F90)

This module creates and writes data in a bundle to a file in machine-independent netCDF format. This module is intended to support the history writing sub-system of cpl6.

REMARKS:

      Typically this module would be used to support the history file subsystem
      of cpl6, but in fact it could be used to create netCDF data files for any
      purpose.  The netCDF data file format might provide an alternative to 
      binary data files.

REVISION HISTORY:

       2002-Oct-22 - B. Kauffman - major upgrade, refactoring
       2001-Dec-20 - B. Kauffman - first prototype

INTERFACE:

 
 module cpl_iocdf_mod

USES:

 
    use cpl_mct_mod       ! mct interface
    use cpl_comm_mod      ! mpi/mph communicator info
    use cpl_fields_mod    ! coupler/model data field indicies
    use cpl_bundle_mod    ! defines bundle
    use cpl_domain_mod    ! defines domain
    use cpl_kind_mod      ! defines F90 kinds
    use cpl_const_mod     ! defines constants (eg. spval)
    use cpl_control_mod, only: dbug=>cpl_control_infoDBug
    use shr_sys_mod       ! share system routines
    use shr_date_mod      ! defines date data-type
 
    implicit none
 
 #include <netcdf.inc>
 
    private ! except

PUBLIC TYPES:

 
   ! none

PUBLIC MEMBER FUNCTIONS:

 
    public :: cpl_iocdf_create   ! create a new file (an empty file)
    public :: cpl_iocdf_open     ! open a named file
    public :: cpl_iocdf_close    ! close an open file
    public :: cpl_iocdf_set64bit ! select 32 or 64 bit real data in file
    public :: cpl_iocdf_append   ! add data to an existing file

PUBLIC DATA MEMBERS:

 
    ! none

10.1.1 cpl_iocdf_create - create a new file.

Create a new netCDF file with name fName and no content other than global attributes. If optional argument desc is present, it will be placed in the ``description'' global attribute.

REVISION HISTORY:

      2002-Oct-22 - B. Kauffman, initial version

INTERFACE:

 
 subroutine cpl_iocdf_create(fName,desc)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    character(*),intent(in)          :: fName   ! file name
    character(*),intent(in),optional :: desc    ! description string

10.1.2 cpl_iocdf_open - open an existing file.

Open an existing file with name fName and return the NetCDF id in the output argument fid.

REVISION HISTORY:

      2002-Oct-22 - B. Kauffman, initial version

INTERFACE:

 
 subroutine cpl_iocdf_open(fName,fid)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    character(*),intent(in)  :: fName   ! file name
    integer(IN) ,intent(out) :: fid     ! file ID

10.1.3 cpl_iocdf_close - close a file.

Close the netCDF file with netCDF id fid.

REVISION HISTORY:

      2002-Oct-22 - B. Kauffman, initial version

INTERFACE:

 
 subroutine cpl_iocdf_close(fid)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    integer(IN),intent(in) :: fid     ! file ID

10.1.4 cpl_iocdf_set64bit - flags creation of 64 bit netCDF files.

Flags creation of 64 bit netCDF files, default is 32 bit. If argument flag is true, netCDF files with be 64 bit.

REMARKS:

      64 bit netCDF data was introduced for regression testing of coupled system.

REVISION HISTORY:

      2004-Mar-31 - B. Kauffman, initial version

INTERFACE:

 
 subroutine cpl_iocdf_set64bit(flag)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    logical,intent(in) :: flag    ! true <=> 64 bit

10.1.5 cpl_iocdf_append - add data to an existing file.

Append all data in bundle bun to an existing netCDF file with netCDF id fid. If fName is present, use cpl_iocdf_open to set fid.

If the input time given by the range dateS, dateE is not already in the time dimension of the file, it is appended to the end of the time dimension. This algorithm assumes that any input time value not already in the time dimension is greater than any value in the time dimension (so that time will be monotonically increasing).

If fName is not present, fid must be a valid netCDF file ID for an open netCDF file. This is presumably the normal mode of operation as it can minimize the opening and closing of a file.

If fName is present, the named file is opened, data is appended, and the file is closed. In this case, the input fid is not used, although it's value will be overwritten. This mode is handy for ``one-off'' debug files. In either case, the file being appended to must have previously been created.

REVISION HISTORY:

      2002-Oct-22 - B. Kauffman, initial version

INTERFACE:

 
 subroutine cpl_iocdf_append(fid,date,bun,dateS,dateE,fName)

USES:

 
    implicit none

INPUT/OUTPUT PARAMETERS:

 
    integer(IN)     ,intent(inout)       :: fid       ! file ID
    type(cpl_bundle),intent(in)          :: bun       ! bundle
    type(shr_date)  ,intent(in)          :: date      ! model date
    type(shr_date)  ,intent(in),optional :: dateS     ! time-bound start date
    type(shr_date)  ,intent(in),optional :: dateE     ! time-bound end   date
    character(*)    ,intent(in),optional :: fName     ! file name