DelftIO Par./Loc./Time (PLT),   Fortran 77 / DLL Interface

Functions

The following functions are available for PLT datasets (the functions for 'MAP' datasets can be used when writing Delwaq Map files; in these cases their are no locations names, just the number of locations):

General
DiofGetVersion Get DelftIO version string
DiofGetMaxParLen Get max. length of Parameter name string
DiofGetMaxLocLen Get max. length of Location ID string
DiofGetMaxDescrLen Get max. length of Description ID string
DiofGetHisRunIdSize Get string length (40 char.s) of the four RunID strings in a HIS or MAP file
Define a PLT Dataset All functions return an integer handle to a PLT dataset.
DiofPltDefine_1 Define a Par./Loc./Time dataset (name, varType, parameters and locations).
DiofPltDefine_2[a] Define a Par./Loc./Time dataset (name, varType, parameters, locations, Julian start time [,Julian end time] )
DiofPltDefine_3 Define a Par./Loc./Time dataset (name, HIS RunID strings, varType, parameters, locations)
DiofPltDefine_4[a] Define a Par./Loc./Time dataset (name, HIS RunID strings, varType, parameters, locations, Julian start time [,Julian end time] )
DiofPltDefine_5[a] Define a Par./Loc./Time dataset (name, HIS RunID strings, varType, parameters, integerLocIDs, locations, Julian start time [,Julian end time] )
Define a MAP Dataset All functions return an integer handle to a PLT dataset.
DiofPltDefine_11 Define a Par./#Locs./Time dataset (name, varType, parameters, numberOfLocations).
DiofPltDefine_12[a] Define a Par./#Locs/Time dataset (name, varType, parameters, numberOfLocations, Julian start time [,Julian end time] )
DiofPltDefine_13 Define a Par./#Locs/Time dataset (name, HIS RunID strings, varType, parameters, numberOfLocations)
DiofPltDefine_14[a] Define a Par./#Locs/Time dataset (name, HIS RunID strings, varType, parameters, numberOfLocations, Julian start time [,Julian end time] )
Add parameter or location descriptions
DiofPltAddDescriptions Add parameter or location descriptions
Write values
DiofPltPutFloats Put floats (=reals) for a certain Julian time stamp.
DiofPltPutNextFloats Put floats (=reals) for next time step. Used for on line communication.
Get Dataset from a file .
DiofPltGetDataset Get a Par./Loc./Time dataset.
The function returns a handle to the PLT dataset
DiofPltGetHeaderLine Get one of the HIS RunID header lines (1-4)
DiofPltGetNPars Get number of parameters in the PLT dataset
DiofPltGetNLocs Get number of locations in the PLT dataset
DiofPltGetNTimes Get number of time steps in the PLT dataset
DiofPltGetPars Get the parameter names in the PLT dataset
DiofPltGetLocs Get the location names in the PLT dataset
DiofPltGetDescriptions Get the location descriptions or the parameter descriptions in a PLT dataset
DiofPltGetIntIds Get the integer location indentifications in a PLT dataset (HIS files only)
DiofPltGetTimes Get the time steps in the PLT dataset (Julian time stamps)
Read values
DiofPltGetNextFloats Get floats (=reals) for the next time step.
DiofPltGetSelection Get floats (=reals) for a selection of parameters, locations and time steps.
Cleanup
DiofPltClose Close and destroy the PLT dataset

 

Include files

dio-plt.inc

(includes: dio-streams.inc)

Defines the following enumerations:

integer Dio_PLT_Unknown = 0
integer Dio_PLT_Integer = 1
integer Dio_PLT_Real    = 2
integer Dio_PLT_Double  = 3
integer Dio_PLT_Logical = 4

integer Dio_PLT_Pars = 1
integer Dio_PLT_Locs = 2
 

General functions

subroutine DiofGetVersion()

arguments   I/O  
character(Len=*)   O Version string (at least 20 bytes)

integer function DiofGetMaxParLen()

return value   I/O  
integer   (O) Max. length of Parameter name string

integer function DiofGetMaxLocLen()

return value   I/O  
integer   (O) Max. length of Location ID string

integer function DiofGetMaxDescrLen()

return value   I/O  
integer   (O) Max. length of Description string

integer function DiofGetHisRunIdSize()

return value   I/O  
integer   (O) String length (40 char.s) of the four RunID strings in a HIS or MAP file

Put a dataset on a stream

step 1: define the dataset

integer function DiofPltDefine_1(name, varType, nPar, pars, nLoc, locs)

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
character(Len=DioMaxLocLen)
dimension(nLoc)		 locs I array with names of the locations in the dataset

integer function DiofPltDefine_2[a] (name, varType, nPar, pars, nLoc, locs, julianStartTime [,julianEndTime])

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
character(Len=DioMaxLocLen)
dimension(nLoc)		 locs I array with names of the locations in the dataset
double precision julianStartTime I startTime as Julian
double precision julianEndTime I [a: endTime as Julian]

integer function DiofPltDefine_3(name, runId, varType, nPar, pars, nLoc, locs)

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
character(Len=HisRunIdSize)
dimension(4)		 runId I HIS RunID strings
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
character(Len=DioMaxLocLen)
dimension(nLoc)		 locs I array with names of the locations in the dataset

integer function DiofPltDefine_4[a] (name, runId, varType, nPar, pars, nLoc, locs, julianStartTime [,julianEndTime])

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
character(Len=HisRunIdSize)
dimension(4)		 runId I HIS RunID strings
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
character(Len=DioMaxLocLen)
dimension(nLoc)		 locs I array with names of the locations in the dataset
double precision julianStartTime I startTime as Julian
double precision julianEndTime I [a: endTime as Julian]

integer function DiofPltDefine_5[a] (name, runId, varType, nPar, pars, nLoc, intLocIds, locs, julianStartTime [,julianEndTime])

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
character(Len=HisRunIdSize)
dimension(4)		 runId I HIS RunID strings
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
integer
dimension(nLoc)		 intLocIds I array with integer locations Ids, as stored in HIS files
character(Len=DioMaxLocLen)
dimension(nLoc)		 locs I array with names of the locations in the dataset
double precision julianStartTime I startTime as Julian
double precision julianEndTime I endTime as Julian

integer function DiofPltDefine_11(name, varType, nPar, pars, nLoc)

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
character(Len=DioMaxLocLen)
dimension(nLoc)		 locs I array with names of the locations in the dataset

integer function DiofPltDefine_12[a](name, varType, nPar, pars, nLoc, julianStartTime [,julianEndTime])

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
double precision julianStartTime I startTime as Julian
double precision julianEndTime I [a: endTime as Julian]

integer function DiofPltDefine_13(name, runId, varType, nPar, pars, nLoc)

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
character(Len=HisRunIdSize)
dimension(4)		 runId I HIS RunID strings
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations

integer function DiofPltDefine_14[a](name, runId, varType, nPar, pars, nLoc, julianStartTime [,julianEndTime])

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname
character(Len=HisRunIdSize)
dimension(4)		 runId I HIS RunID strings
integer varType I type of variable to be stored in dataset
integer nPar I number of parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars I array with names of the parameter in the dataset
integer nLoc I number of locations
double precision julianStartTime I startTime as Julian
double precision julianEndTime I [a: endTime as Julian]

step 1a: add descriptions to the dataset

logical function DiofPltAddDescriptions(pltHandle, descr_type, nDescr, descriptions)

return value   I/O  
logical   (O) .True.: Descriptions defined (non-blank elements in the the output array <descriptions>).
.False.: No descriptions defined.
arguments      
integer pltHandle I handle todataset
integer descr_type I description type:
- dio_plt_pars (=1) for parameter descriptions
- dio_plt_locs (=2) for location descriptions
integer nDescr I number of descriptions, i.e. the number of parameters (descr_type==dio_plt_pars) or locations (descr_type==dio_plt_locs) in the PLT dataset
character(Len=DioMaxLocLen),
dimension(nDescr)		 descriptions O array with location or parameter descriptions in the dataset.

step 2: write the data

subroutine DiofPltPutFloats(pltHandle, timestamp, nPar, nLoc, values)

arguments   I/O  
integer pltHandle I handle todataset
double precision timestamp I time stamp as Julian
integer nPar I number of parameters
integer nLoc I number of locations
real
dimension(nPar,nLoc)		 values I 2D-array with real values to be put.

subroutine DiofPltPutNextFloats(pltHandle, nPar, nLoc, values)

arguments   I/O  
integer pltHandle I handle todataset
integer nPar I number of parameters
integer nLoc I number of locations
real
dimension(nPar,nLoc)		 values I 2D-array with real values to be put.

Get a dataset from a stream

step 1: get the dataset information

integer function DiofPltGetDataset(name)

return value   I/O  
integer   (O) Handle to Parameter/Location/Time dataset.
0: Error occured
>0: Valid handle
arguments      
character(Len=*) name I datasetname

step 2: get (number of) parameters / locations / times, etc., from the dataset

function DiofPltGetHeaderLine(pltHandle, lineNr, line)

return value   I/O  
logical   (O) True: OK
False: error
arguments      
integer pltHandle I handle todataset
integer lineNr I Required HIS RunID header lines (1-4)
character(Len=HisRunIdSize) line O Content of header line HISRunID(lineNr)

integer function DiofPltGetNPars(pltHandle)

return value   I/O  
integer   (O) Number of parameters in PLT dataset
>0: OK.
0: Call GetLastError to Check if indeed there are 0 parameters, or if an error has occured
arguments      
integer pltHandle I handle todataset

integer function DiofPltGetNLocs(pltHandle)

return value   I/O  
integer   (O) number of locations in PLT dataset
>0: OK.
0: Call GetLastError to Check if indeed there are 0 locations, or if an error has occured
arguments      
integer pltHandle I handle todataset

integer function DiofPltGetNTimes(pltHandle)

return value   I/O  
integer   (O) number of timesteps in PLT dataset
>0: OK.
0: Call GetLastError to Check if indeed there are 0 time steps, or if an error has occured
arguments      
integer pltHandle I handle todataset

logical function DiofPltGetPars(pltHandle, nPar, pars)

return value   I/O  
logical   (O) True: OK
False: error
arguments      
integer pltHandle I handle todataset
integer nPar I number of expected parameters
character(Len=DioMaxParLen)
dimension(nPar)		 pars O array with names of the parameters in the dataset

logical function DiofPltGetLocs(pltHandle, nLoc, locs)

return value   I/O  
logical   (O) True: OK
False: error
arguments      
integer pltHandle I handle todataset
integer nLoc I number of expected locations
character(Len=DioMaxLocLen)
dimension(nLoc)		 locs O array with names of the locations in the dataset;
for MAP files, an array containing "Segment<locNr>" (locNr = <1..nLoc>) is returned.

logical function DiofPltGetDescriptions(pltHandle, descr_type, nDescr, descriptions)

return value   I/O  
logical   (O) .True.: Descriptions defined (non-blank elements in the the output array <descriptions>).
.False.: No descriptions defined.
arguments      
integer pltHandle I handle todataset
integer descr_type I description type:
- dio_plt_pars (=1) for parameter descriptions
- dio_plt_locs (=2) for location descriptions
integer nDescr I number of expected descriptions, i.e. the number of parameters (descr_type==dio_plt_pars) or locations (descr_type==dio_plt_locs) in the PLT dataset
character(Len=DioMaxLocLen)
dimension(nDescr)		 descriptions O array with location or parameter descriptions in the dataset.

logical function DiofPltGetIntIds(pltHandle, nLoc, intIds)

return value   I/O  
logical   (O) True: OK
False: error
arguments      
integer pltHandle I handle todataset
integer nLoc I number of expected location IDs
integer
dimension(nLoc)		 intIds O array with integer location identifications (HIS files only;
for MAP files a series 1,2,3,..<nLoc> is returned).

logical function DiofPltGetTimes(pltHandle, nTime, times)

return value   I/O  
integer   (O) True: OK
False: error
arguments      
integer pltHandle I handle todataset
integer nTime I number of expected time stamps
double precision times O array with julian time stamps

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

logical function DiofPltGetNextFloats(pltHandle, nPar, nLoc, timestamp, values)

return value   I/O  
logical   (O) True: OK
False: error
arguments   I/O  
integer pltHandle I handle todataset
integer nPar I number of parameters
integer nLoc I number of locations
double precision timestamp O Juliantime stamp of retrieved next values as
real
dimension(nPar,nLoc)		 values O 2D-array with retrieved real values

step 3b: get a selection of the data

logical function DiofPltGetSelection(pltHandle, nPar, parIndx, nLoc, locIndx, nTim, timIndx, values)

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      
integer pltHandle I handle todataset
type(DioPltType) plt I handle to Parameter/Location/Time dataset
integer nPar I Number of requested parameters
integer
dimension(nPar)		 parIndx I 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 | integer),
dimension(nPar, nLoc, nTim)		 values O 3D-array for resulting values

Cleanup

subroutine DiofPltClose(pltHandle)

arguments   I/O  
integer pltHandle I handle todataset