Calling the I/O API 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 the relevant Fortran compiler (f90?) to do the final
linking/loading step:
cc -c foo.c ... # produces foo.o, etc.
f90 -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 issue that comes up is the relationship between C strings and
Fortran strings. For the most part, the wrappers take care of this for
you; the notable exception is when dealing with file descriptions.
Fortran strings in the file description data structures have an
allocated-length field and a contents field; the contents field is
padded on the right with blanks up to the allocated size (and
string-comparison and assignment "do the right thing" while
preventing buffer overflow). C strings are pointers to string-contents
terminated by the ASCII zero (NULL
character. C
programmers needing to deal with these data structures should use
fstr2cstr(), name2cstr(), and
cstr2fstr() to convert back and forth between these two
string types.
Another 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); F77 and F90
- Sun SunOS4 (Solaris 4.x)
- Sun SunOS5 (Solaris 2.x); F77 and F90
- IBM AIX
- gcc/g++/g77/g95
- Linux/x86 Portland Group (C and) Fortran (note that
gcc/pgf90 is different from pgcc/pgf90)
- Linux/x86 Intel icc/ifc
- Linux/x86 Lahey-Fujitsu Fortran/gcc
- Linux/x86[-64] Absoft C and Fortran
- Linux/x86-64 PathScale
- Linux/ia64 Intel icc/ifc
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>
-
dscgridc():
get description of <named grid>
-
dt2strc():
Construct string "HH:MM:SS Month DD, YYYY" for
<jdate-&-time>
-
filchk3c():
check a file for consistency with user-supplied
set of file type and dimensions
-
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
-
inqatt3c():
Inquire the names, types, and sizes of netCDF attributes
for <variable> in <file>.
- 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>
-
rdatt3c():
Read value of <attribute> of
<variable> in <file>.
- 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.
-
sync3c():
Synchronize <file> with disk: flush
output; re-read header from disk.
("Volatile"
files auto-synch themselves...)
- 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.
-
wratt3c():
write value of <attribute> for
<variable> in <file>.
- 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