DEFINITION MODULE GridDataSets;
(*******************************************************************
Module GridDataSets (Version 1.0)
Copyright (c) 1997-2006 by Dimitrios Gyalistras and ETH Zurich.
Purpose Manage gridded data sets and their attributes,
get or set gridpoint data.
Remarks For input/output of gridded data sets see
module GridDSIO.
For auxiliary procedures and operations on
gridded data sets see module GridDSOp.
Programming
o Design
Dimitrios Gyalistras 23/05/1997
o Implementation
Dimitrios Gyalistras 23/05/1997
ETH Zurich
Systems Ecology
CHN E 35.1
Universitaetstrasse 16
8092 Zurich
SWITZERLAND
URLs:
<mailto:RAMSES@env.ethz.ch>
<http://www.sysecol.ethz.ch>
<http://www.sysecol.ethz.ch/SimSoftware/RAMSES>
Last revision of definition: 05/06/2002 AF
*******************************************************************)
FROM SYSTEM IMPORT BYTE;
FROM DMFiles IMPORT TextFile;
IMPORT Errors;
CONST
notDone = Errors.onlyAnInsert;
(*
All procedures exported below return errCode = Errors.allOk if the
call to the procedure was succesfull, and resCode = notDone if not.
*)
TYPE
GridDataSet;
DataMatrix;
TYPE
GridDataSetChange = (gdsDefined, gdsReplaced, gdsRemoved);
AtGridDataSetChangeP = PROCEDURE( GridDataSetChange, (* type of change *)
GridDataSet ); (* the data set affected *)
VAR
undefGridDataSet : GridDataSet; (* read only *)
undefDataMatrix : DataMatrix; (* read only *)
(*************************************************************)
(*##### Definition and removal of gridded data sets #####*)
(*************************************************************)
PROCEDURE InstallAtGridDataSetChangedHandler( gch: AtGridDataSetChangeP );
(*
This procedure allows to install a handler "gch" which is called
each time a change in the GridDataSets occurs.
*)
PROCEDURE DefineGridDataSet( VAR gds : GridDataSet;
dataID : LONGINT; (* identifier of data *)
dataDescr : ARRAY OF CHAR; (* description of data *)
sectorID : LONGINT; (* identifier of sector *)
sectorDescr : ARRAY OF CHAR; (* description of sector *)
nRows : INTEGER; (* Number of points in y-direction *)
nCols : INTEGER; (* Number of points in x-direction *)
inDegrees : BOOLEAN; (* Specify as TRUE if minLon/minLat/cellSize
are degrees.
Specify as FALSE if the meta-information
refers to an arbitrary X/Y coordinate system. *)
minLon : REAL; (* longitude of lower left corner *)
minLat : REAL; (* latitude of lower left corner *)
cellSize : REAL; (* cell size *)
nDataMats : INTEGER; (* number of data matrices *)
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(*
Defines a new gridded data set. If data set "gds"
already exists, it is redefined.
*)
PROCEDURE RemoveGridDataSet( VAR gds: GridDataSet );
PROCEDURE RemoveAllGridDataSets;
(*********************************************************************)
(*##### Retrieval of gridded data sets and their attributes #####*)
(*********************************************************************)
PROCEDURE NGridDataSets():INTEGER;
(* IF VERSION_STONYBROOK *) (*.
PROCEDURE GetGridDataSets( VAR gds : ARRAY OF BYTE;
VAR nGridDataSets : INTEGER);
.*) (* ENDIF VERSION_STONYBROOK *)
(* IF VERSION_MacMETH *)
PROCEDURE GetGridDataSets( VAR gds : ARRAY OF GridDataSet;
VAR nGridDataSets : INTEGER);
(* ENDIF VERSION_MacMETH *)
(* IF VERSION_EPC *) (*.
PROCEDURE GetGridDataSets( VAR gds : ARRAY OF GridDataSet;
VAR nGridDataSets : INTEGER);
.*) (* ENDIF VERSION_EPC *)
PROCEDURE GridDataSetExists( gds: GridDataSet ): BOOLEAN;
PROCEDURE GetGridDataSetAttrs( gds : GridDataSet;
VAR dataID : LONGINT;
VAR dataDescr : ARRAY OF CHAR;
VAR sectorID : LONGINT;
VAR sectorDescr : ARRAY OF CHAR;
VAR nRows : INTEGER;
VAR nCols : INTEGER;
VAR inDegrees : BOOLEAN;
VAR minLon : REAL;
VAR maxLon : REAL;
VAR minLat : REAL;
VAR maxLat : REAL;
VAR cellSize : REAL;
VAR nDataMats : INTEGER );
(* NOTE: minLon/maxLon and minLat/maxLat returned according to the GDS convention,
i.e. they denote the coordinates of the most westerly/easterly, respectively
southerly/northerly gridpoints. *)
PROCEDURE GetGridDataSetDim( gds: GridDataSet; VAR nRows, nCols, nDataMats: INTEGER );
PROCEDURE GridDataSetDataID( gds: GridDataSet ): LONGINT;
PROCEDURE GetGridDataSetDataDescr( gds: GridDataSet; VAR dataDescr: ARRAY OF CHAR );
PROCEDURE GridDataSetSectorID( gds: GridDataSet ): LONGINT;
PROCEDURE GetGridDataSetSectorDescr( gds: GridDataSet; VAR sectorDescr: ARRAY OF CHAR );
PROCEDURE GridDataSetNumRows( gds: GridDataSet ): INTEGER;
PROCEDURE GridDataSetNumCols( gds: GridDataSet ): INTEGER;
PROCEDURE GridDataSetIsInDegrees( gds: GridDataSet ): BOOLEAN;
PROCEDURE GridDataSetMinLon( gds: GridDataSet ): REAL;
PROCEDURE GridDataSetMaxLon( gds: GridDataSet ): REAL;
PROCEDURE GridDataSetMinLat( gds: GridDataSet ): REAL;
PROCEDURE GridDataSetMaxLat( gds: GridDataSet ): REAL;
PROCEDURE GridDataSetCellSize( gds: GridDataSet ): REAL;
PROCEDURE GridDataSetNumDataMats( gds: GridDataSet ): INTEGER;
(********************************************************)
(*##### Setting of gridded data set attributes #####*)
(********************************************************)
PROCEDURE SetGridDataSetDataID( gds: GridDataSet; dataID: LONGINT );
PROCEDURE SetGridDataSetDataDescr( gds: GridDataSet; dataDescr: ARRAY OF CHAR );
PROCEDURE SetGridDataSetSectorID( gds: GridDataSet; sectorID: LONGINT );
PROCEDURE SetGridDataSetSectorDescr( gds: GridDataSet; sectorDescr: ARRAY OF CHAR );
(************************************************************)
(*##### Testing of gridded datasets and attributes #####*)
(************************************************************)
PROCEDURE SetGridpointCoordRelTol( relTol: REAL );
PROCEDURE GridpointCoordRelTol(): REAL;
(*
Set or get the relative tolerance for the coordinates of a gridpoint.
A gridpoint is accepted as being consistent with the definition of a
given grid if it is located within a rectangular region with height =
width = 2*relTol*cellSize surrounding a gridpoint of the grid. The
default value for relTol is 0.01 (i.e., 1%).
The relative tolerance is considered when testing the corectness of a
given coordinate in procedures XCoordOK/YCoordOK, when using one of the
procedures Get/SetGridpointValue (see below), or when reading the
coordinates for a GridDataSet given in listFormat with the aid of
procedure ReadGridDataSet from module GridDSIO.
*)
PROCEDURE GridDataSetOK( gds : GridDataSet;
VAR errTxt : ARRAY OF CHAR ): BOOLEAN;
PROCEDURE GridDataMatOK( gds : GridDataSet;
dataMatNr : INTEGER;
VAR errTxt : ARRAY OF CHAR ): BOOLEAN;
PROCEDURE XCoordOK( gds : GridDataSet;
xCoord : REAL;
mustBeOnGrid : BOOLEAN;
VAR isInSector : BOOLEAN;
VAR isOnGrid : BOOLEAN;
VAR closestCol : INTEGER;
VAR errTxt : ARRAY OF CHAR ): BOOLEAN;
PROCEDURE YCoordOK( gds : GridDataSet;
yCoord : REAL;
mustBeOnGrid : BOOLEAN;
VAR isInSector : BOOLEAN;
VAR isOnGrid : BOOLEAN;
VAR closestRow : INTEGER;
VAR errTxt : ARRAY OF CHAR ): BOOLEAN;
PROCEDURE GridPointOK( gds : GridDataSet;
xCoord : REAL;
yCoord : REAL;
mustBeOnGrid : BOOLEAN;
VAR pointIsInSector : BOOLEAN;
VAR pointIsOnGrid : BOOLEAN;
VAR closestRow : INTEGER;
VAR closestCol : INTEGER;
VAR errTxt : ARRAY OF CHAR ): BOOLEAN;
(******************************************)
(*##### Get/set gridpoint values #####*)
(******************************************)
PROCEDURE GetGridpointValue( gds : GridDataSet;
dataMatNr : INTEGER;
xCoord : REAL;
yCoord : REAL;
VAR value : REAL;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
PROCEDURE SetGridpointValue( gds : GridDataSet;
dataMatNr : INTEGER;
xCoord : REAL;
yCoord : REAL;
value : REAL;
VAR resCode : INTEGER;
VAR errTxt : ARRAY OF CHAR );
(* Access to of gridpoint values using direct access to data matrices *)
PROCEDURE GetDataMatrix( gds: GridDataSet; dataMatNr: INTEGER ): DataMatrix;
PROCEDURE GetMatEle( mat: DataMatrix; row, col: INTEGER; VAR r: REAL );
(* does not check inputs! *)
PROCEDURE SetMatEle( mat: DataMatrix; row, col: INTEGER; r: REAL );
(* does not check inputs! *)
END GridDataSets.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib