DDTVAR3() and ddtvar3c()

Fortran version:

    LOGICAL FUNCTION DDTVAR3( FNAME, VNAME, CALLER,
 &                        JDATE, JTIME, BSIZE, BUFFER )
        CHARACTER*(*), INTENT(IN   ) :: FNAME     !  file name for query
        CHARACTER*(*), INTENT(IN   ) :: VNAME     !  vble  name   (or ALLVAR3 (='ALL'))
        CHARACTER*(*), INTENT(IN   ) :: CALLER    !  name of caller for logging
        INTEGER      , INTENT(IN   ) :: JDATE     !  date, formatted YYYYDDD
        INTEGER      , INTENT(IN   ) :: JTIME     !  time, formatted HHMMSS
        INTEGER      , INTENT(IN   ) :: BSIZE     !  data volume (words) being read
        <type> , INTENT(  OUT) :: BUFFER( BSIZE ) !  array to hold input

C version:

ddtvar3c() is a C wrapper calling the Fortran DDTVAR3()

    int ddtvar3c( const char * fname ,
                  const char * vname ,
                  const char * caller,
                  int          jdate ,
                  int          jtime ,
                  int          bsize ,
                  void       * buffer )

Summary:

    USE M3UTILIO
    

Does linear approximation for time-derivatives of the variable VNAME from the Models-3 data file with logical name FNAME for the date and time JDATE (coded YYYYDDD), JTIME (HHMMSS), with optimized disk access, memory allocation, etc., handled behind the scenes. Checks size BSIZE of the buffer to hold the data against the size calculated from values in the file header (and insists that they match).

For time independent files, JDATE:JTIME are ignored and the derivative is of course identically zero, so the routine doesn't need to do any work, and can be lazy. If VNAME is ALLVAR3 (= 'ALL', defined in INCLUDE-file PARMS3.EXT ),, calculates derivatives of all variables in the file.

At timestep-boundaries, calculates the FORWARD-differencing approximate derivative

For I/O API 3.2 or later: If snoop mode is configured in the Makefile when you build libioapi.a, then environment variables SNOOPTRY3, SNOOPSECS3 control the number of re-tries and the delay between re-tries (secs) for reading data under end-of-file conditions.

Returns .TRUE. (or 1) if the operation succeeds, .FALSE. (or 0) if it fails. For failure, writes a log message indicating the nature of the failure.

Calls INIT3() and also OPEN3() if necessary (opening the file for read-only if it does so).

For Fortran-90 declarations and interface checking:

    USE M3UTILIO
    

See also

INTERP3 and INTERPX,
READ3,
WRITE3,
XTRACT3,

Preconditions:

FNAME and VNAME must have length at most 16, exclusive of trailng blanks.

Valid BSIZE for INTERP3() or COL0, COL1, ROW0, ROW1, LAY0, LAY1 for INTERPX().

INTERPX() not supported yet for virtual files (netCDF only).

JDATE and JTIME must be expressed in terms of Models-3 date and time conventions.

basic data type VTYPE3D for the variable must be M3REAL for releases prior to the May 3, 2002 Version 2.2-beta, or M3REAL or M3DBLE for subsequent releases.

    DATEs are   YYYYDDD = YEAR*1000  +  DAY
    TIMEs are   HHMMSS  = HOUR*10000 +  MINS*100  +  SECS

Fortran Usage:

    ...
    USE M3UTILIO
    ...
    INTEGER     NCOLS,      NROWS,      NLAYS
    PARAMETER ( NCOLS = ??, NROWS = ??, NLAYS = ?? )
    ...
    REAL  DSO4DT( NCOLS, NROWS, NLAYS )
    ...
    IF ( DDTVAR3( 'MYFILE', 'HNO3', 1988021, 123730,
 &              NCOLS*NROWS*NLAYS, DSO4DT ) ) THEN
        !!  Derivative of variable calculated for 12:37:30 Jan 21, 1988
        !!  from MYFILE and put into array DSO4DT.
        ...
    ELSE
        !!  Error:  see program log for further info.
        ...
    END IF
    ...
    

C Usage:

    ...
    #include "iodecl3.h"
    ...
    float  dhno3dt[ NLAYS ][ NROWS ][ NCOLS ] ;
    ...
    if ( ddtvar3c( "MYFILE", "HNO3", 1988021, 123000,
                   NCOLS*NROWS*NLAYS, dhno3dt ) )
        {
            /*  Derivative of variable 'HNO3' calculated for date
                and time  12:37:30  Jan 21, 1988 from MYFILE and
                put into array dhno3dt
            */
        ...
        }
    else
        {
            /*  Error:  see program log for further info.  */
        ...
        }
    ...

Next: DESC3

Up: Public I/O Routines

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