New!! Fortran-90 MODULE M3UTILIO

Summary

Fortran-90 style MODULE M3UTILIO does the "proper F90 way" of encapsulating the Models-3 I/O API parameter, data structure, and function-declarations, in a way that nested Fortran USE <module> constructs do not interact with older Fortran INCLUDE statements to generate multiple-declaration errors at compile time.

The issue is that when one has two or more Fortran-90 MODULEs, say MODULE A that USEs MODULE B, where both of these need access to facilities provded by the standard I/O API INCLUDE files PARMS3.EXT, FDESC3.EXT, and/or IODECL3.EXT, there is a problem: if MODULE B INCLUDEs these, it introduces an artificial dependency of MODULE A upon MODULE B: where should the INCLUDE statements be placed (if they appear in both MODULEs, the compiler will complain that variables and functions have repeated declarations, which is illegal. The problem is even worse if MODULE A USEs a third MODULE C, independent of B, that also needs I/O API INCLUDE files: one can't necessarily make C USE B, or vice versa.

However, the Fortran-90 USE construct does not have this problem: MODULEs A, B, and C can all have statements USE M3UTILIO without causing multiple-declaration problems: the recognition that these statements provide one common set of declarations is now built into the Fortran-90 (and later) language, in a way not possible at all for Fortran-77 (and that must be managed manually by the programmer with #ifdefs for the corresponding C #include construct).


Contents of MODULE M3UTILIO

MODULE M3UTILIO itself includes, and therefore replaces the INCLUDE of the following Models-3 I/O API INCLUDE files:
PARMS3.EXT
FDESC3.EXT
IODECL3.EXT
It further provides Fortran-90 style INTERFACE blocks for the following list of routines (basically, all of the public routines in the I/O API whose usage does not require "void pointer" arguments -- note that the BUFFER argument for WRITE3() does not have a single specified type; it may be INTEGER, REAL, or DOUBLE PRECISION, and may have an arbitrary number of dimensions, instead of being restricted (as an INTERFACE would require) to one single possibility like a 3-D REAL BUFFER(:,:,:), or requiring over three thousand lines of "wrapper" code to support the implied polymorphism. (IODECL3.EXT is invoked from this MODULE to provide the EXTERNAL declarations for these polymorphic routines, but not full interface blocks.)
BILIN
BMATVEC
CURREC
CURSTEP
DAYMON
DMATVEC
DSCGRID and DSCOORD
DT2STR
ENVDBLE
ENVINT
ENVREAL
ENVSTR
ENVYN
FINDC
FIND1
FIND2
FIND3
FIND4
FINDR1
FINDR2
FINDR3
FINDR4
GCD
GETDATE
GETDBLE
GETDFILE
GETEFILE
GETFFILE
GETMENU
GETNUM
GETREAL
GETSTR
GETYN
GRDCHK3
HHMMSS
INDEX1
INDEXINT1
INTLIST
ISDST
JSTEP3
JULIAN
JUNIT
LAMBERT and related routines
LBLANK
LOCAT1
LOCAT2
LOCAT3
LOCAT4
LOCATC
LOCATR1
LOCATR2
LOCATR3
LOCATR4
LUSTR
M3EXIT
M3FLUSH
M3MESG
M3MSG2
M3PARAG
M3PROMPT
M3WARN
MMDDYY
NEXTIME
PCOEF
PMATVEC
POLY
PROMPTDFILE
PROMPTFFILE
PROMPTMFILE
PROMPTGRID()
REALIST
SCANINT()
SEC2TIME
SECSDIFF
SETENVVAR
SORTIC
SORTI1
SORTI2
SORTI3
SORTI4
SORTR1
SORTR2
SORTR3
SORTR4
STR2DBLE
STR2INT
STR2REAL
STRLIST
TIME2SEC
UNGRIDB
UNGRIDI
UPCASE()
WKDAY
YEAR4
YR2DAY
and more...
It also provides four cleanly-coded public parsing-utility routines that replace various less-well-conceived SMOKE 1.x library-routines,and new utility routines for grid-description checking and for integer unsorted-table lookup:
SUBROUTINE SPLITLINE( LINE, NMAX, N, FIELD, EFLAG )
CHARACTER(LEN=*), INTENT( IN ):: LINE
INTEGER, INTENT( IN ):: NMAX
INTEGER, INTENT( OUT ):: N
CHARACTER(LEN=*), INTENT( OUT ):: FIELD( NMAX )
LOGICAL, INTENT( OUT ):: EFLAG
split a line into fields, ignoring comments

SUBROUTINE FIXFIELD
CHARACTER(LEN=*), INTENT( INOUT ):: FIELD
fixup, replacing blanks and "missing"s in character-string fields by zeros

REAL FUNCTION KEYVAL
CHARACTER(LEN=*), INTENT( IN ) :: KEY
search for REAL key-value in I/O API file descriptive header FDESC3D array.

KEYSTR
search for REAL key-value in I/O API file descriptive header FDESC3D array.

Note that in retro-fitting MODULE M3UTILIO into existing codes, one must not only remove all of the INCLUDE statements associated with the standard I/O API PARMS3.EXT, FDESC3.EXT, and/or IODECL3.EXT, one must also remove any (now extra) declarations of the functions with explicit INTERFACEs from the list given above.


To: Models-3/EDSS I/O API: The Help Pages

Send comments to

Carlie J. Coats, Jr.
cjcoats@email.unc.edu