Calling the I/O API and Utility Functions from C
There are a set of C-callable wrappers and/or native-C implementations
for all of the public I/O API and most of the utility routines.
ANSI-style function prototypes for these routines can be found in the
include-file "iodecl3.h".
There are four relevant archive libraries
(".a" files) of compiled object files for your use.
Since most of these C-callable routines are wrappers around Fortran
routines which then use the Fortran run-time libraries, you need to
use "f77" to do the final linking/loading step:
cc -c foo.c ... # produces foo.o, etc.
f77 -o foo foo.o ... -lm3io -lnetcdf
Generally, the public I/O API routines are int functions
which return <nonzero> (generally 1) for success and
0 for failure; utility routines are more varied. Names are generally
of the form *c(), so that they won't be confused with Fortran
routines; a few routines -- generally those named in ALLCAPS --have one
single implementation directly callable from both languages.
One particular point which may come up is the relationship between
Fortran REAL
and C types. Under most conditions, these
are the same; however, on Cray T3D and T3E platforms, Fortran
REAL
is C double
. This is also true when the
Fortran source is compiled with a -r8
flag (for those
compilers which support it). The C include-file parms3.h
defines type FREAL
appropriately for these cases (you can
activate it by the flag -DREAL8
for the custom
-r8
compiles). C wrappers (e.g., interp3c()
,
ddtvar3c
, or sortirc()
) expect variables of
type FREAL
rather than necessarily variables of C type
float
.
Since calling Fortran from C or vice versa is machine-specific, the
wrappers tend to have conditionally-compiled code appropriate for
various architectures. It should be easy to extend the list
of supported architectures to IBM AIX, HP HPUX, and Data General DG/UX
by adding the appropriate symbols to the "#ifdef" in
"iodecl3.h" and at the beginning of the wrappers (since
all these machines still use Feldman-f77-style string passing
conventions the biggest obstacle to mixed C-Fortran programming);
the difficulty lies in getting hold of the manuals and finding out
what symbol to use for each. The list of currently supported
architectures is given below:
- Cray Y-MP/C90/T90 - UNICOS
- DEC Alpha/OSF1
- DEC Ultrix
- SGI IRIX (4, 5, 6)
- Sun SunOS4 (Solaris 4.x)
- Sun SunOS5 (Solaris 2.x)
- IBM AIX
- gcc/g++/g77
The list of the public C-callable I/O API routines is:
- check3c() --
is <timestep> available for
<variable> from <file>
- close3c() --
close <file>
- currstepc3c() --
truncate <jdate,jtime> to an exact time step
in the time step sequence defined by
<sdate,stime,tstep>
- daymonc() --
find month and day-of-month for <jdate>
- ddtvar3c() --
compute time derivative of <variable>
from <file>
- desc3c() --
get description for <file>
-
find1c(), find2c(),
find3c(), find4c(),
findr1c(), findr2c(),
findr3c(), findr4c() --
find INTEGER or FREAL <key-tuple> in sorted
<keytuple-table>
- getdfilec() --
open direct access Fortran file with specified
<logical name>
and <record length>,
<formatting> and <read-write
status>
- getefilec() --
open sequential Fortran file with specified
<logical name>
<formatting> and <read-write
status>
- hhmmssc() --
construct string "HH:MM:SS" for
<time>
- init3c() --
start up I/O API; return log-file unit
- interp3c() --
interpolate <variable> from <file>
to <time>
- julianc() --
find Julian day number (1...365,366) for
<month> <day> <year>
-
locat1c(), locat2c(),
locat3c(), locat4c(),
locatr1c(), locatr2c(),
locatr3c(), locatr4c() --
find insertion-point for INTEGER or
FREAL <key-tuple> into sorted
<keytuple-table>, or -1 if the
key is already present
- m3errc() --
<warning or error message>;
with SHUT3() and EXIT(2) if fatal error;
deprecated: superseded by
m3exitc() and m3warnc()
- m3exitc() --
<exit message> with
<date and time>,
SHUT3() and EXIT(<status>)
- m3mesgc() and
m3msg2c() --
Write 1-line <message> to Fortran-program log
(and
stdout
as well, for m3msg2c()
.
- m3warnc() --
<warning message> with
<date and time>
- mmddyyc() --
construct string "Month DD, YYYY" for
<jdate>
- nextimec() --
update <jdate-&-time> by
<timestep>
- open3c() --
open <file> for <status>
- read3c() --
read <timestep> of <layer>
of <variable> from <file>
- read4dc() --
read <timestep sequence > of
<layer> of <variable>
from <file>
- sec2timec() --
get I/O API
HHMMSS
time representation
for <seconds>
- secsdiffc() --
find time difference (seconds) between two I/O API
<jdate-&-time> pairs
- sec2timec() --
shut down I/O API; flush files to disk
-
sorti1c(), sorti2c(),
sorti3c(), sorti4c(),
sortr1c(), sortr2c(),
sortr3c(), sortr4c() --
sort <index table> acording to a
<keytuple-table> of INTEGERs or REALs.
- time2secc() --
get number of seconds for <time> given in
I/O API
HHMMSS
time representation.
- wkdayc() --
get day-of-week (1...7) for <jdate> given in
I/O API
YYYYDDD
Julian-date representation.
- write3c() --
write <timestep> of
<variable> to <file>
- write4dcc() --
write <timestep sequence> of
<variable> to <file>
- xtract3c() --
read <window> of <timestep>
of <variable> from <file>
The list of (easily) C-callable date-and-time
routines is:
- currstepc() --
find start of <timestep> containing
<time>
- daymonc() --
find month and day-of-month for <jdate>
- dt2strc() --
Construct string for <jdate> and
<time>
- getdttimec() --
get current wall-clock date and time
- hhmmssc() --
construct string "HHMMSS" for <time>
- julianc() --
find Julian day number (1,...,365,366) for
<month> <day> <year>
- mmddyyc() --
construct string "Month DD, YYYY"
for <jdate>
- nextimec() --
update <jdate>, <time>
by <timestep>
- sec2timec() --
get Models-3 time representation for
<seconds>
- secsdiffc() --
find time difference (seconds) between two
<jdate-&-time>s
- time2secc() --
get number of seconds for <time>
The list of (easily) C-callable utility routines is:
- dscoordc() --
get description for <coordinate system>
- dscgridc() --
get description for <grid>
- envdblec(): --
get double value of logical name from
the environment
- envintc():
get int value of logical name from the environment
- envrealc: --
get float value of logical name from the environment
- envstrc(): --
get char * value of logical name from
the environment
- envync(): --
get logical (int) value of logical name from the
environment
-
find1c(), find2c(), find3c(), find4c():
find integer key-tuple in sorted
keytuple-table
- GCD() --
greatest common divisor function
- getdfilec() --
Open file as Fortran direct access file with specified
logical name
- getefilec() --
Open file as Fortran sequential file with specified
logical name
- m3errc() --
warning message; or error message
with SHUT3() and EXIT( 2 );
superseded by m3exitc() and m3warnc().
- m3exitc() --
exit message with SHUT3() and
exit( <status> )
- m3mesgc(): --
Write 1-line message to Fortran-program log.
- m3warnc(): --
Write <warning message> with
<date and time> to Fortran-program log.
- POLY() --
degree-d polynomial interpolation function
-
SORTI1(), SORTI2(), SORTI3(), SORTI4():
sort <index table> acording to a
<keytuple-table>
Previous Section: Calling from Fortran
Next Section: Variables and Layers and Time Steps
Up: Conventions
To: Models-3/EDSS I/O API: The Help Pages