 |
 |
 |
 |
 |
 |
Appendix
A: The Fortran Interface
Registration:
=============
There are 2 phases of registration, one to provide top-level information
on each model and variables it will produce, and a second to provide
the
details on each produce and consume request.
The first phase:
Meta Registration:
===================================
The _designated host_ for each model must perform Meta registration
to inform the other models of the variables it will produce. Only
general information on each model (eg, global tick information)
is required at this stage .
Function 'StartMetaRegistration()' must be called first;
'MetaRegister()' must be called for each variable to be produced;
and finally 'EndMetaRegistration()' terminates the procedure.MCLStartMetaRegistration:
=========================
Called by a single processor (the designated host) to start the Meta-Registration
process.
Returns 1 on success, 0 on failure.
Arguments:
tid
== array of PVM tids for all processes that will participate
in the exchange of data using the data broker. It is of
length 'numTasks'
numTasks
== length of array 'tid'
f77modelName
== Name of the model. Must be of length 128 (CHARACTER*128)
numLon
== Number of longitude points. Length of array 'lonTicks'.
numLat
== Number of latitude points. Length of array 'latTicks'.
numVert
== Number of longitude points. Length of array 'vertTicks'.
lonTicks
== Longitude tick points, of length 'numLon'.
latTicks
== Latitude tick points, of length 'numLat'.
vertTicks
== Vertical tick points, of length 'numVert'.int MCLStartMetaRegistration(
INTEGER tid,
INTEGER numTasks,
CHARACTER
f77modelName,
INTEGER numLon,
INTEGER numLat,
INTEGER numVert,
REAL*8 lonTicks,
REAL*8 latTicks,
REAL*8 vertTicks
)
MCLMetaRegister:
================
Called for each variable to be produced.
Returns 1 on success, 0 on failure.
Arguments:
f77VarName
== Name of the variable. Of length at least 'nameLen'
nameLen
== Length (in characters) of the name of this variable
coordType
== Coordinate type; for now must be 0 (sigma coordinates)
dataType
== Type of the data. The value to data type mapping follows:
0 == SignedCharType
1 == SignedShortType
2 == SignedIntType
3 == SignedLongType
4 == UnsignedCharType
5 == UnsignedShortType
6 == UnsignedIntType
7 == UnsignedLongType
8 == FloatType
9 == DoubleType
varType
== Type of the variable. 1 == Temporary, 0 == persistent.
Always use 0 for now
numDims
== Number of dimensions. 1 for 1D, etc.
frequency
== Number of simulated seconds between each production of
this variable.
int MCLMetaRegister(
CHARACTER f77VarName,
INTEGER nameLen,
INTEGER coordType,
INTEGER dataType,
INTEGER varType,
INTEGER numDims,
REAL*8 frequency
)
MCLEndMetaRegistration:
=======================
Terminates the meta registration process. Returns 1 on success, 0 on
failure.
No arguments.int MCLEndMetaRegistration()The second registration phase:
==============================
In the next phase, _each process_ that will produce or
consume data must full details on its requirements. Exact
grids are supplied in each request.
This 'data' registration must be initiated by a call to
'StartDataRegistration()', followed by calls to 'RegisterDataProduce()'
and/or 'RegisterDataConsume()' for each variable produced or
consumed, and terminated by a call to 'EndDataRegistration()'.
All of the LIL calls are made in the second phase of registration,
by each member process.
As before, the 'data' registration must be initiated by a call to
'StartDataRegistration()', followed by calls to 'RegisterDataProduce()',
'RegisterDataConsume()' for each variable produced or consumed.
If the process wishes to make use of interpolated data, then it
must make a call to 'LILRegisterCoordinates()', followed by calls to
'LILRequestInterpolatedData()'.MCLStartRegistration:
=======================
Initiates the second registration phase. Returns 1 on success, 0 on
failure.
No arguments.int MCLStartRegistration()
MCLRegisterProduce:
===================
Called to inform the data broker that the calling process will produce
the
given data on the given grid.
On success, returns a non-negative integer id used to uniquely identify
this data request. (This value will be used in subsequent calls to 'MCLSendData'.)
Any other value implies failure.
Arguments:
f77VarName
== Name of the variable. Of length at least 'nameLen'
nameLen
== Length (in characters) of the name of this variable
coordType
== Coordinate type; for now must be 0 (sigma coordinates)
dataType
== Type of the data. The value to data type mapping follows:
0 == SignedCharType
1 == SignedShortType
2 == SignedIntType
3 == SignedLongType
4 == UnsignedCharType
5 == UnsignedShortType
6 == UnsignedIntType
7 == UnsignedLongType
8 == FloatType
9 == DoubleType
varType
== Type of the variable. 0 == Temporary, 1 == persistent.
Always use 1 for now
numDims
== Number of dimensions. 1 for 1D, etc.
frequency
== Number of simulated seconds between each production of
this variable.
int MCLRegisterProduce(
CHARACTER f77VarName,
INTEGER nameLen,
INTEGER coordType,
INTEGER dataType,
INTEGER varType,
INTEGER numDims,
INTEGER lon0,
INTEGER numLon,
INTEGER lat0,
INTEGER numLat,
INTEGER numVert,
REAL*8 vert,
REAL*8 frequency
)
MCLRegisterConsume:
===================
Called to inform the data broker that the calling process will consume
the
given data on the given grid.
On success, returns a non-negative integer id used to uniquely identify
this data request. (This value will be used in subsequent calls to 'MCLGetData'.)
Any other value implies failure.
Arguments:
f77VarName
== Name of the variable. Of length at least 'nameLen'
nameLen
== Length (in characters) of the name of this variable
coordType
== Coordinate type; for now must be 0 (sigma coordinates)
dataType
== Type of the data. The value to data type mapping follows:
0 == SignedCharType
1 == SignedShortType
2 == SignedIntType
3 == SignedLongType
4 == UnsignedCharType
5 == UnsignedShortType
6 == UnsignedIntType
7 == UnsignedLongType
8 == FloatType
9 == DoubleType
varType
== Type of the variable. 0 == Temporary, 1 == persistent.
Always use 1 for now
numDims
== Number of dimensions. 1 for 1D, etc.
frequency
== Number of simulated seconds between each production of
this variable.
int MCLRegisterConsume(
CHARACTER f77VarName,
INTEGER nameLen,
INTEGER coordType,
INTEGER dataType,
INTEGER varType,
INTEGER numDims,
INTEGER lon0,
INTEGER numLon,
INTEGER lat0,
INTEGER numLat,
INTEGER numVert,
REAL*8 vert,
REAL*8 frequency
)
MCLEndRegistration:
===================
Ends the data registration phase.
Returns 1 on success, 0 on failure.
No arguments.int MCLEndRegistration()
MCLGetData:
===========
Called by a consumer to get data. Note that this is a blocking
call and will only return when the data is available.
Arguments:
id
== Integer id returned from the call to
'MCLRegisterConsume'
for this item of data
buf
== Buffer/Array containing the data
timeStamp
== Time-stamp associated with this dataint MCLGetData(
INTEGER id,
REAL*8 buf,
/* Can be of other types as well */
REAL*8 timeStamp
)
MCLSendData:
============
Called by a producer to make data available to consumers.
Returns 1 on success, 0 on failure.
Arguments:
id
== Integer id returned from the call to
'MCLRegisterProduce'
for this item of data
buf
== Buffer/Array containing the data
timeStamp
== Time-stamp associated with this dataint MCLSendData(
INTEGER id,
REAL*8 buf, /*
Can be of other types as well */
REAL*8 timeStamp
)
MCLSetTracelevel:
=================
Sets the MCL debugging and tracing level, for diagnostic output.
No return value.
Arguments:
level == Level of tracing.
Please choose one of:
0 == Critical errors only (always on)
1 == Warnings
2 == More warnings
3 == Flow; function entry and exit is shown
4 == Maximum level
void MCLSetTracelevel(
INTEGER level
)MCLPoll:
========
MCLPoll checks for and handles pending PVM messages destined for the
data broker.
It should be called intermittently to aviod the data broker messages
from piling up...
Returns the number of messages processesed.
No arguments.
int MCLPoll()
MCLIAmRegistrationBroker:
=========================
Only called by the process designated as the data broker!
Returns 1 on success, 0 on failure.
Arguments:
runName
== Name of this run, eg "Configuration A"
startTime
== Start time for the models in the run
endTime
== End time for the models in the run (estimated if not known)
numModels
== Number of models taking part in this runint MCLIAmRegistrationBroker(
CHARACTER runName,
REAL*8 startTime,
REAL*8 endTime,
INTEGER numModels
)
LILRegisterCoordinates:
======================
Called to inform the interpolation library that the process will
be requesting data in terms of the supplied coordinate system.
A process may request data in multiple coordinate systems, if
desired.
On success, returns a (typically small) non-negative integer token for
use in subsequent calls to LILRequestInterpolatedData
on success, or negative on failure.
It is assumed that all participants will use the same scaling for
the ticks (radians, degrees, etc.); the TickModulus vector is
used to indicate which, if any, of the coordinates wrap, and
what the modulus factor is in the same scale as the ticks.
So, if wrapping is desired in the East-west direction and
the Ticks are given in degrees, the TickModulus vector would
be (360, 0, 0). If wrapping over the poles was desired also,
and the Ticks were given in radians, then the TickModulus Vector would
be (6.328431853*, 3.1415926*, 0)
* to however many digits for real*8.Arguments:
f77coordName
== Name of the coordinate system. Must be of length 128 (CHARACTER*128)
numLon
== Number of longitude points. Length of array 'lonTicks'.
numLat
== Number of latitude points. Length of array 'latTicks'.
numVert
== Number of longitude points. Length of array 'vertTicks'.
lonTicks
== Longitude tick points, of length 'numLon'.
latTicks
== Latitude tick points, of length 'numLat'.
vertTicks
== Vertical tick points, of length 'numVert'.
int LILRegisterCoordinates(
CHARACTER f77coordName,
INTEGER numLon,
INTEGER numLat,
INTEGER numVert,
REAL*8 lonTicks,
REAL*8 latTicks,
REAL*8 vertTicks
)
LILRequestInterpolatedData:
===================
Called to inform the data broker that the calling process will consume
the
given data on the given grid.
On success, returns a non-negative integer id used to uniquely identify
this data request. (This value will be used in subsequent calls to 'MCLGetData'.)
Any other value implies failure.
Arguments:
f77VarName
== Name of the variable. Of length at least 'nameLen'
nameLen
== Length (in characters) of the name of this variable
coordToken
== from LILRegisterCoordinates, above
dataType
== Type of the data. The value to data type mapping follows:
0 == SignedCharType
1 == SignedShortType
2 == SignedIntType
3 == SignedLongType
4 == UnsignedCharType
5 == UnsignedShortType
6 == UnsignedIntType
7 == UnsignedLongType
8 == FloatType
9 == DoubleType
varType
== Type of the variable. 0 == Temporary, 1 == persistent.
Always use 1 for now
numDims
== Number of dimensions. 1 for 1D, etc.
lon0
== starting index (1-based) relative to the
lonTicks array registered above
numLon
== number of array elements in this dimension
lat0
== starting index (1-based) relative to the
latTicks array registered above
numLat
== number of array elements in this dimension
vert0
== starting index (1-based) relative to the
vertTicks array registered above
numVert
== number of array elements in this dimension
TickModulii
== value for moduli if wrapping is desired,
frequency
== Number of simulated seconds between each production of
this variable.
int LILRequestInterpolatedData(
CHARACTER f77VarName,
INTEGER nameLen,
INTEGER coordToken,
INTEGER dataType,
INTEGER varType,
INTEGER numDims,
INTEGER lon0,
INTEGER numLon,
INTEGER lat0,
INTEGER numLat,
INTEGER vert0,
INTEGER numVert,
REAL*8 TickModulii
REAL*8 frequency
)
LILSetMissingDefault:
=====================
Called after requesting an interpolation to be done to specify a sentinal
value to be supplied for any data that cannot be interpolated or to
be
filled in prior to the receipt of any data (as a background value for
missing data).
Returns 0 when successful, negative if the supplied ID is not known
or is for a field of data type other than Float or Double.
Arguments:
id
(as returned from LILRequestInterpolatedData)
value
either a float or a double being the default
LILSetMissingDefault(
INT
ID
REAL
value);
(in C, it's declared as void
* and casted to the apropriate type).