This module creates, writes-to, and reads data in a bundle to/from a file in machine-dependent binary format. This module is intended to support the restart sub-system of cpl6.
REMARKS:
This module could be used to create binary data files for any
purpose. The binary data file format is self-describing and extensible and
thus might provide an alternative to netCDF files.
REVISION HISTORY:
2002-nov-08 - B. Kauffman - initial versionINTERFACE:
module cpl_iobin_modUSES:
use cpl_mct_mod ! mct interface
use cpl_comm_mod ! mpi/mph communicator info
use cpl_fields_mod ! coupler/model data field indices
use cpl_bundle_mod ! defines bundle
use cpl_domain_mod ! defines domain
use cpl_kind_mod ! defines F90 kinds
use cpl_control_mod, only: dbug=>cpl_control_infoDBug
use shr_sys_mod ! share system routines
use shr_date_mod ! defines date data-type
use shr_mpi_mod ! layer on MPI
implicit none
private ! except
PUBLIC TYPES:
! none
PUBLIC MEMBER FUNCTIONS:
public :: cpl_iobin_create ! create a new file (an empty file)
public :: cpl_iobin_open ! open a named file
public :: cpl_iobin_close ! close an open file
public :: cpl_iobin_appendBun ! add bundle data to a file
public :: cpl_iobin_readBun ! read bundle data from a file
public :: cpl_iobin_appendReal ! add real array data to a file
public :: cpl_iobin_readReal ! read real array data from a file
public :: cpl_iobin_readDate ! read data date from a file
PUBLIC DATA MEMBERS:
! none
Open a file with name fName and write a small header of 6 character strings each with length CL. Use Fortran unformatted write. If optional argument desc is present, it will be included in the header.
REVISION HISTORY:
2002-Nov-08 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_create(fName,desc)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
character(*),intent(in) :: fName ! file name
character(*),intent(in),optional :: desc ! description string
Open the pre-existing file with name fName and assign it the unit number fid. Also read the header information and write it to stdout.
REVISION HISTORY:
2002-Nov-08 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_open(fName,fid)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
character(*),intent(in) :: fName ! file name
integer(IN) ,intent(out) :: fid ! file ID (file unit number)
Call close on file with unit number fid.
REVISION HISTORY:
2002-Nov-08 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_close(fid)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
integer(IN),intent(in) :: fid ! file ID (file unit number)
Append the data in bundle bun to the pre-existing file with the unit number fid. Also write the date contained in date to the file. fid must be a valid fortran unit number for an open file.
All processors call this function and the root node will MPI_gather the data and write it to the file.
REMARKS:
Domain data associated with the bundle is not written
but this functionality could be added, if desired.
The file format utilizes an extensible, self-describing data format.
REVISION HISTORY:
2002-Nov-08 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_appendBun(fid,date,bun)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
integer(IN) ,intent(inout) :: fid ! file ID
type(shr_date) ,intent(in) :: date ! model date
type(cpl_bundle) ,intent(in) :: bun ! bundle
Read data from file with unit number fid and return in in the bundle bun. Argument date is currently ignored. Data is read on node 0 and scattered using the information in the domain associated with bun. On return, bun contains the data for points local to the calling processor.
REVISION HISTORY:
2002-Nov-08 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_readBun(fid,date,bun)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
integer(IN) ,intent(in) :: fid ! file ID
type(shr_date) ,intent(inout) :: date ! desired model date, file's date?
type(cpl_bundle),intent(inout) :: bun ! bundle to read
Append data in real array data to the alredy-open file with unit number fid. Include in file the name of the data vName and the date date. rcode is 0 if successful and 1 if file is not open.
REMARKS:
This routine is run on root PE only.REVISION HISTORY:
2003-Mar-07 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_appendReal(fid,date,vName,data,rcode)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
integer(IN) ,intent(in) :: fid ! fortan unit number of open data file
type(shr_date),intent(in) :: date ! desired model date
character(*) ,intent(in) :: vName ! name of var to read
real(R8) ,intent(in) :: data(:) ! the data
integer(IN) ,intent(out) :: rcode ! return code
Read data with name vName into real array data from the alredy-open file with unit number fid. Argument date is currently not used. rcode is 0 if successful and 1 if file is not open or variable is not found.
REMARKS:
This routine is run on root PE only.REVISION HISTORY:
2002-Nov-08 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_readReal(fid,date,vName,data,rcode)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
integer(IN) ,intent(in) :: fid ! fortan unit number of open data file
type(shr_date),intent(in) :: date ! desired data date
character(*) ,intent(in) :: vName ! name of var to read
real(R8) ,intent(out) :: data(:) ! array to put data into
integer(IN) ,intent(out) :: rcode ! return code
Search the already open file with unit number fid and find the date string in the header. If found, return date information in output arguments cDate and sec. rcode is 0 if successful and 1 if file is not open. This routine will abort if the date string is not found. Date is read on node 0 and broadcast to all processors calling this routine.
REMARKS:
Assumes the date for all data is the same, hence returns 1st date found.REVISION HISTORY:
2002-Dec-13 - B. Kauffman, initial versionINTERFACE:
subroutine cpl_iobin_readDate(fid,cDate,sec,rcode)USES:
implicit none
INPUT/OUTPUT PARAMETERS:
integer(IN),intent(in) :: fid ! fortan unit number of open data file
integer(IN),intent(out) :: cDate ! coded date of data in file
integer(IN),intent(out) :: sec ! seconds corresponding to cDate
integer(IN),intent(out) :: rcode ! return code