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 |