DelftIO Par./Loc./Time Fortran 90 Interface

Functions

The following functions are available:

Define Dataset  
DioPltDefine Define a Par./Loc./Time dataset, optionally on a Stream.
The function returns a handle to the PLT dataset.
Write values  
DioPltPut Put values for a specific Julian time stamp, for a specific His timestep, or for the next time step (for on line communication)
Get Dataset  
DioPltGetDataset Get a Par./Loc./Time dataset, optionally  from a Stream.
The function returns a handle to the PLT dataset
DioPltOpenedOK Check if a Par./Loc./Time was opened succesfully
DioPltGetNPar Get number of parameters in the PLT dataset
DioPltGetNLoc Get number of locations in the PLT dataset
DioPltGetNTimes Get number of time steps in the PLT dataset
DioPltGetPars Get the parameter names in the PLT dataset
DioPltGetLocs Get the location names in the PLT dataset
DioPltGetIntIds Get the integer location indentifications in a PLT dataset (HIS files only)
DioPltGetTimes Get the time steps in the PLT dataset (Julian time stamps)
DioPltGetHisSteps Get the time steps in the PLT dataset as HIS steps
DioPltGetHisTimeUnit Get PLT's HIS time step unit
DioPltGetHisTimeMult Get PLT's HIS time step multiplier
Read values  
DioPltGet Get floats (=reals) for the next time step.
DioPltGetSelection Get floats (=reals) for a selection of parameters, locations and time steps; or get all parameter/location values for one timestep
Cleanup  
DioPltDestroy Close and destroy the PLT dataset
Miscellaneous  
DioPltRewind Rewind a (serial) file containing a PLT (only for parallel Sobek-CF/RR)
General Functions  
DioGetVersion Get DelftIO version
StringsEqual Compare Strings

 

Module files

use dio_plt_rw

Module defines variable types that can be stored in a PLT:
integer dio_Plt_Real
integer dio_Plt_Double
integer dio_Plt_Integer
integer dio_Plt_Logical
and and implements the Plt-functions below.

Write a dataset

step 1: define the dataset (optionally on a stream)

The following overloaded define functions are available for PLT's:
function DioPltDefine([stream,] name, varType, pars, locs) result(plt)
function DioPltDefine([stream,] name, varType, pars, locs, julianStartTime [,julianEndTime]) result(plt)
function DioPltDefine([stream,] name, hisRunId, varType, pars, locs) result(plt)
function DioPltDefine([stream,] name, hisRunId, varType, pars, locs, julianStartTime [,julianEndTime]) result(plt)
function DioPltDefine([stream,] name, varType, pars, intLocIds, locs) result(plt)
function DioPltDefine([stream,] name, hisRunId, varType, pars, intLocIds, locs) result(plt)
function DioPltDefine([stream,] name, hisRunId, varType, pars, intLocIds, locs, julianStartTime [,julianEndTime]) result(plt)

The following overloaded define functions are available for create MAP files:
function DioPltDefine([stream,] name, varType, pars, nLoc) result(plt)
function DioPltDefine([stream,] name, varType, pars, nLoc, julianStartTime [,julianEndTime]) result(plt)
function DioPltDefine([stream,] name, hisRunId, varType, pars, nLoc) result(plt)
function DioPltDefine([stream,] name, hisRunId, varType, pars, nLoc, julianStartTime [,julianEndTime]) result(plt)

return value   I/O  
type(DioPltType) :: plt (O) handle to Parameter/Location/Time dataset
arguments      
type(DioStreamType) :: stream I Optional: Stream on which dataset must be defined
character(*) :: name I dataset name
character(HisRunIdSize),
    dimension(HisRunIdDim)		 :: hisRunId I HIS runid for this dataset. If it includes a HIS T0-string, this T0-string is used for the start time of the dataset.
HisRunIdSize = 40, HisRunIdDim = 4.
integer :: varType I (dio_Plt_Real | dio_Plt_Double | dio_Plt_Integer | dio_Plt_Logical)
character(len=DioMaxParLen),
    dimension(:)		 :: pars I array with names of the parameter in the PLT dataset
integer , dimension(:)
 :: intLocIds I Integer locations Ids, as stored in HIS files. The dimension must be the same as the one for locs
character(len=DioMaxLocLen),
    dimension(:)		 :: locs I array with names of the locations in the PLT dataset
integer :: nLoc I Number of Locations in PLT, ID's not available (MAP files only).
double precision :: julianStartTime I Julian timestamp for start time of PLT dataset
double precision :: julianEndTime I Optional: Julian timestamp for end time of PLT dataset

step 2: write the data

The following overloaded Put routines are available
subroutine DioPltPut(plt, values)
subroutine DioPltPut(plt, hisTimeStep, values)
subroutine DioPltPut(plt, hisTimeStep, values1D [,allowLarger] )
subroutine DioPltPut(plt, julianTime, values)

arguments   I/O  
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset
double precision :: julianTimeStamp I Julian time stamp for the next time step
integer :: HISTimeStep I HIS time step for the next time step
(real|doubleprecision|integer|logical), dimension(:,:) :: values I 2D-array with real, double precision, integer or logical values to be put. The maximum dimension of this array is (1:number_of_parameters, 1:number_of_locations), but it may be smaller.
(real|doubleprecision|integer|logical), dimension(:) :: values1D I 1D-array with real, double precision, integer or logical values to be put. The dimension of this array must be (number_of_parameters * number_of_locations) in the PLT, unless the largerAllowed flag is set to .true., in which case the array may be larger (but of course only the first (#pars*#locs) values are written.
logical :: allowLarger I Optional: Flag indicating if values1D may be larger then (#pars*#locs).

Get a dataset from a stream

step 1: get the dataset information, optionally from specific stream

function DioPltGetDataset([stream,] name) result(plt)

return value   I/O  
type(DioPltType) :: plt (O) handle to Parameter/Location/Time dataset
arguments      
type(DioStreamType) :: stream I Optional: Stream on which dataset is available
character(*) :: name I dataset name

step 2: Check on succesful opening, get (number of) parameters / locations / times in the dataset

function DioPltOpenedOK(dataset) result(n)

return value   I/O  
logical ::n (O) .true.: PLT opened succesfully; .false.: not opened succesfully
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

function DioPltGetNPar(dataset) result(n)
function DioPltGetNLoc(dataset) result(n)
function DioPltGetNTimes(dataset) result(n)

return value   I/O  
integer ::n (O) Number of Parameter or Locations in dataset
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

function DioPltGetPars(dataset) result(names)
function DioPltGetLocs(dataset) result(names)

return value   I/O  
character(len=DioMax(Par|Loc)Len), &
     pointer, dimension(:)		 :: names (O) pointer to array with parameter/location names;
Note: when the first 'Get' action is performed, the parameter names and location names are cleared from memory, so after this first 'Get' call the pointer returned by DioPltGetLocs and DioPltGetPars is not valid any more.
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

function DioPltGetIntIds(dataset) result(intIds)

return value   I/O  
integer, &
     pointer, dimension(:)		 :: intIds (O) pointer to array with integer location identifications (HIS files only, for Map files a NULL pointer is returned);
Note: when the first 'Get' action is performed, the integer location id's are cleared from memory, so after this first 'Get' call the pointer returned by DioPltGetIntIds is not valid any more.
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

function DioPltGetTimes(dataset) result(julianTimes)

return value   I/O  
double, &
     pointer, dimension(:)		 :: julianTimes (O) array with Julian time stamps
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

function DioPltGetHisSteps(dataset) result(hisSteps)

return value   I/O  
integer, &
     pointer, dimension(:)		 :: hisSteps (O) array with integer HIS time steps
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

function DioPltGetHisTimeUnit(dataset) result(hisTimeUnit)

return value   I/O  
integer :: hisTimeUnit (O) HIS time step unit
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

function DioPltGetHisTimeMult(dataset) result(hisTimeMult)

return value   I/O  
integer :: hisTimeMult (O) HIS time step multiplier
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset

step 3a: get the data for the next time step

The following overloaded Get functions are available
function DioPltGet(plt, values) result(success)
function DioPltGet(plt, julianTimeStamp, values) result(success)
function DioPltGet(plt, HISTimeStep, values) result (success)

return value   I/O  
logical :: success (O) .true. if read was succesfull
.false. if data was not found in te file, or if a TimeOut occured
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset
double precision :: julianTimeStamp O Julian time stamp for the next time step
integer :: HISTimeStep O HIS time step for the next time step
(real | double precision | integer), pointer, dimension(:,:) :: values O pointer to 2D-array, will point to the valus of the currently read timestep
Note: when the next time step is read, the values in the array where 'values' points to will be overwritten by the newly read values. So if one wants to keep using the original values, a copy has to be made.

step 3b: get a selection of the data

The following overloaded GetSelection  functions are available:

function DioPltGetSelection(plt, timIndex, values) result(success)

return value   I/O  
logical :: success (O) .true. if time step was found
.false. if not.
(Caller should fill values array with 'missing values' in advance).
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset
integer :: timIndex I Requested time step index (not the HIS time step?)
(real | double precision),
dimension(:, :)		 :: values O 2D-array for resulting values for requested time step index (dimensions must be equal to nPar * nLoc)

function DioPltGetSelection(plt, nPar, parIndx, nLoc, locIndx, nTim, timIndx, values) result(success)

return value   I/O  
logical :: success (O) .true. if file could be scanned for data
.false. if not.
(Caller should fill values array with 'missing values' in advance).
arguments      
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset
integer :: nPar I Number of requested parameters
integer, dimension(nPar) :: parIndx   Indices of requested parameters
integer :: nLoc I Number of requested locations
integer, dimension(nLoc) :: locIndx I Indices of requested locations
integer :: nTim I Number of requested time steps
integer, dimension(nTim) :: timIndx I Indices of requested time steps
(real | double precision),
dimension(nPar, nLoc, nTim)		 :: values O 3D-array for resulting values

Cleanup

subroutine DioPltDestroy(plt)

arguments   I/O  
type(DioPltType) :: plt I handle to Parameter/Location/Time dataset to be closed and destroyed

Miscellaneous

subroutine DioPltRewind(plt)

arguments   I/O  
type(DioPltType) :: plt I handle to Parameter/Location/Time of which the (serial) file has to be rewinded (only for parallel Sobek-CF/RR)

General support functions

function DioPltGetVersion() result(version)

return value   I/O  
character(len=DioVersionLen) :: version (O) DelftIO version string (e.g.1.6.16)
arguments      
- - - -

function StringsEqual(caseMode, string_1, string_2) result(equal)
Support function for comparing strings. Available when module Dio_Plt_rw is used; if not:
    use Dio_Prop
is enough to make the function-prototype and the caseMode enumeration available.
Example:
   if ( StringsEqual(CaseInsens, myString, someString) ) then
        ! ... action
   endif

return value   I/O  
logical :: equal (O) .true. if strings are equal
.false. if not.
arguments   I/O  
integer :: caseMode I Enumeration: CaseSens or CaseInsens
character(Len=*) :: string_1 I first string
character(Len=*) :: string_2 I second string