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:

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