DataFile Class

1. Description

2. Module Interface

3. Subroutines and Functions

4. Examples

Description

The DataFile class provides an abstract interface for accessing data files. This interface does not dependent on the format of the file.

Module Interface

MODULE DataFile_Class

TYPE DataFile
TYPE FieldInfo
    CHARACTER(len=*) :: name
    INTEGER          :: grid_dimensions
    LOGICAL          :: time_dependent
END TYPE FieldInfo

INTERFACE isValid
INTERFACE initialize
INTERFACE finalize
INTERFACE get
INTERFACE print
INTERFACE contains
INTERFACE getFieldInfo
INTERFACE getName
INTERFACE getPrecision
INTERFACE getType
INTERFACE isWriteable
INTERFACE OPERATOR (.contains.)

INTEGER, PARAMETER :: NetCDFFile

INTEGER, PARAMETER :: SinglePrecision
INTEGER, PARAMETER :: DoublePrecision

INTEGER, PARAMETER :: DataFile_InvalidFile
INTEGER, PARAMEGER :: DataFile_FileExists
INTEGER, PARAMETER :: DataFile_InvalidType
INTEGER, PARAMETER :: DataFile_NotCOARDS
INTEGER, PARAMETER :: DataFile_FieldNotFound

END MODULE DataFile_Class

Functions and Subroutines

FUNCTION isValid(this) RESULT(result)
    LOGICAL :: result
    TYPE(DataFile), INTENT(in) :: this

This function checks whether the parameter this contains a valid DataFile object. It may be applied to any DataFile object at any time. A valid DataFile object can be used for reading and/or writing coordinates, grids, time series and fields.

SUBROUTINE initialize(this,name,history,type,precision,overwrite,readwrite,err)
    TYPE(DataFile),   INTENT(inout)           :: this
    CHARACTER(len=*), INTENT(in)              :: name
    CHARACTER(len=*), INTENT(in),    OPTIONAL :: history
    INTEGER,          INTENT(in),    OPTIONAL :: type
    INTEGER,          INTENT(in),    OPTIONAL :: precision
    LOGICAL,          INTENT(in),    OPTIONAL :: overwrite
    LOGICAL,          INTENT(in),    OPTIONAL :: readwrite
    TYPE(Error),      INTENT(inout), OPTIONAL :: err

This subroutine initializes an (invalid) DataFile object. This subroutine should be invoked on an object before any other function or subroutine except isValid is applied to it. After initialization, the parameter this contains a valid DataFile object that can be used to read and/or write fields, time series, grids and coordinates.
The parameter, name, gives the name of the file to be created or opened. The optional parameter type gives the data format of the file. The default file type is NetCDFFile. The parameter history gives a description of how the file was created. It is only stored (as a global NetCDF attribute) in writeable files.
The precision parameter controls whether real valued numerical data is stored in single or double precision. The default is single precision.
By default, existing files are opened for reading only and new files for writing. When the parameter, overwrite, is set to .TRUE. and the file already exists, the existing file will be removed and a new file is opened for writing. In order to read and write data to a (possibly existing) file you should assign the value .TRUE. to the parameter readwrite.
The optional parameter, err, is used to pass information on run-time errors that occur while trying to initialize the DataFile object. Without this parameter, the occurance of any of these error conditions will end execution of the program.
The following error codes can be set:

DataFile_InvalidFile
The file does not contain data in the expected format. Therefore, the file could not be opened.
DataFile_Exists
The file already exists.
DataFile_InvalidType
The data format type specified on the object is not supported by this version of the DataFile class. In normal situations this error should not occur.
DataFile_NotCOARDS
After opening an (existing) NetCDF file, it appears that this file is not structured according to the COARDS conventions. As a result, the contents of the file cannot be read.

(See also the Error class.)

SUBROUTINE finalize(this,err)
    TYPE(DataFile), INTENT(inout)           :: this
    TYPE(Error),    INTENT(inout), OPTIONAL :: err

This subroutine finalizes the (valid) DataFile object, this. This object should have been initialized earlier in the program. During finalization, the file is closed. Hereafter, the object is invalid and should not be used anymore. The optional parameter, err, is used to pass information on run-time errors that occur while trying to initialize the DataFile object. Without this parameter, the occurance of any of these error conditions will end the program.
The following error codes can be set:

DataFile_InvalidType
The data format type specified on the object is not supported by this version of the DataFile class. In normal situations this error should not occur.

Note that it is necessary to finalize a data file to ensure that all data written before are flushed to disk!

(See also the Error class.)

SUBROUTINE get(this,name,type)
    TYPE(DataFile),   INTENT(in)            :: this
    CHARACTER(len=*), INTENT(out), OPTIONAL :: name
    INTEGER,          INTENT(out), OPTIONAL :: type

This subroutine retrieves information from the DataFile object, this. The object itself is not modified. The two optional parameters determine which information will be retrieved. This subroutine can be invoked without any parameters. In this case, the subroutine is as a no-op.

SUBROUTINE print(this)
    TYPE(DataFile), INTENT(in) :: this

This subroutine is the equivalent of the Fortran PRINT statement. It prints the DataFile object, this, to the standard output unit in standardized format. The object is not modified.

SUBROUTINE print(this)
    TYPE(FieldInfo), INTENT(in) :: this

This subroutine is the equivalent of the Fortran PRINT statement. It prints the FieldInfo record, this, to the standard output unit in standardized format. The record is not modified.

FUNCTION contains(this,variable) RESULT(result)
    LOGICAL :: result
    TYPE(DataFile),   INTENT(inout)         :: this
    CHARACTER(len=*), INTENT(out), OPTIONAL :: name

This function checks whether the data file contains a field which has the name, variable.
This function can also be invoked via the binary operator .contains..

FUNCTION getFieldInfo(this) RESULT(result)
    TYPE(FieldInfo), DIMENSION(:), POINTER :: result
    TYPE(DataFile),  INTENT(in) :: this

FUNCTION getFieldInfo(this,name) RESULT(result)
    TYPE(FieldInfo) :: result
    TYPE(DataFile),   INTENT(in)              :: this
    CHARACTER(len=*), INTENT(in)              :: name
    TYPE(Error),      INTENT(inout), OPTIONAL :: err

In the first form, this function retrieves some information on all the fields in the data file. The object it self is not modified. The function allocates a one-dimensional array of FieldInfo records. Each record contains the name of the field, the number of spatial dimensions, and whether the field depends on time. Note that it is the responsibility of the user of this function to deallocate the storage when it is not needed any longer.

In the second form this function retrieves some information on one field in the data file. The object it self is not modified. The FieldInfo record returned contains the name of the field (which is identical to the value of the name parameter), the number of spatial dimensions, and whether the field depends on time. In the case that the data file does not contain a field with the given name and an Error object is passed to this function, the Error object is set to the value DataFile_FieldNotFound. In case that an Error object is not provided, execution of the running process is aborted.

(See also the Error class.)

FUNCTION getName(this) RESULT(result)
    CHARACTER(len=*) :: result
    TYPE(DataFile), INTENT(in) :: this

This function retrieves the name of the data file.

FUNCTION getPrecision(this) RESULT(result)
    INTEGER :: result
    TYPE(DataFile), INTENT(in) :: this

This function retrieves the precision with which real values are written to file.

FUNCTION getType(this) RESULT(result)
    INTEGER :: result
    TYPE(DataFile), INTENT(in) :: this

This function retrieves the file type of this DataFile object.

FUNCTION isWriteable(this) RESULT(result)
    LOGICAL :: result
    TYPE(Error), INTENT(in) :: this

This function checks whether data can be written to this DataFile object and returns the result.

OPERATOR (.contains.)    <left> .contains. <right>

This operator checks whether the DataFile object at the left contains the Field object which name is given at the right. This operator is an alias for the function contains.

Examples

The following program shows how a DataFile object can be used to obtain a list of all fields in a file and print this list to the standard output file.

PROGRAM DataFile_Class_Example
  USE DataFile_Class
  USE Error_Class
  IMPLICIT NONE

  CHARACTER(len=*), PARAMETER :: filename = "data.nc"

  TYPE(DataFile) :: file
  TYPE(Error)    :: err
  TYPE(FieldInfo), DIMENSION(:), POINTER :: info
  INTEGER        :: i

  CALL initialize(err)
  CALL initialize(file,name=filename,type=NetCDFFile,err=err)
  IF (isSet(err)) THEN
    CALL print(err)
    STOP "initialize"
  END IF

  info => getFieldInfo(file)
  IF (Size(info,1) == 0) THEN
    PRINT*,filename," contains no fields"
  ELSE
    PRINT*,filename," contains the following fields:"
    DO i=LBound(info,1),UBound(info,1)
      CALL print(info(i))
    END DO
  END IF

  CALL finalize(file,err=err)
  IF (isSet(err)) THEN
    CALL print(err)
    STOP "finalize"
  END IF

  CALL finalize(err)
END PROGRAM DataFile_Class_Example