CURRSTEP() and currstepc()

Fortran version:

    LOGICAL FUNCTION CURRSTEP( JDATE, JTIME,
 &                             SDATE, STIME, TSTEP,
 &                             CDATE, CTIME )
    INTEGER FUNCTION CURREC ( JDATE, JTIME,
 &                            SDATE, STIME, TSTEP,
 &                            CDATE, CTIME )

        INTEGER, INTENT(IN   ) :: JDATE     !  date (encoded DDDYY)
        INTEGER, INTENT(IN   ) :: JTIME     !  time (encoded HHMMSS)
        INTEGER, INTENT(IN   ) :: SDATE, STIME    !  starting d&t for the sequence
        INTEGER, INTENT(IN   ) :: TSTEP           !  time step for the sequence
        INTEGER, INTENT(  OUT) :: CDATE, CTIME    !  d&t for timestep of

C version:

    int currstepc( int  jdate ,  int  jtime ,
                   int  sdate ,  int  stime , int  tstep,
                   int *cdate ,  int *ctime )

Idea:

Useful with READ3() and XTRACT3() -- if a file has time step sequence with SDATE, STIME, TSTEP and you want to read the data relevant to JDATE:JTIME, then you want to use CURRSTEP() to find the CDATE:CTIME, which will be the last time step at or before JDATE:JTIME, to use as the arguments to READ3() (and possibly read the next time step from that file as well, if you're doing interpolation). Returns TRUE if and only if this is possible (and it succeeded in computing CDATE:CTIME.

Summary:

For Fortran-90 declarations and interface checking:

    USE M3UTILIO
    

CURRSTEP computes the date&time CDATE:CTIME and CURREC computes the record-number 1, 2, 3, ... for the time step enclosing JDATE:JTIME in the time step sequence starting at SDATE:STIME and having time step | TSTEP | (absolute values, in order to deal with restart files easily). In particular, CDATE:CTIME is date&time of the largest timestep in the sequence having the property:

        CDATE:CTIME <= JDATE:JTIME

CURRSTEP returns .TRUE., CURRREC returns positive result, and currstepc returns 1 iff JDATE:JTIME is within a time step starting at SDATE:STIME (i.e., if TSTEP is nonzero this means that JDATE:JTIME is later than SDATE:STIME.) Otherwise, these return .FALSE., -1, or 0 respectively.

See also subroutine JSTEP3() that computes (Fortran style 1,2,...) record numbers for JDATE:JTIME within the time step sequence SDATE:STIME:TSTEP.

These routines are carefully coded to avoid INTEGER overflow in the intermediate calculations, and can be used for runs having durations even measured in millenia.

Preconditions:

#include "iodecl3.h" if called from C.

dates and times represented according to Models-3 conventions:

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

Fortran Usage:

    ...
    USE M3UTILIO
    ...
    INTEGER    CDATE, CTIME, IREC
    ...
    IREC = CURRSTEP( 1988101, 123000,
 &                 1988100,      0, 10000,
 &                 CDATE, CTIME )
        !!  ==> CDATE:CTIME is 1988101:120000 since this is the start
        !!  ==> of the (1-hour) time step which encloses 12:30:00.
    ...
    IF ( IREC .LT. 0 ) THEN
        !!  ...error:  request before start of time step sequence
    END IF
    

C Usage:

    ...
    #include "iodecl3.h"
    ...
    int  jdate, jtime, sdate, stime, tstep, cdate, ctime ;
    ...
    /*  get jdate, jtime;
        get sdate, stime, tstep relevant to file "foo" */
    if ( currstepc( jdate,  jtime,
                    sdate,  stime, tstep,
                   &cdate, &ctime ) )
        {
        /*  CAN read3c() the data for cdate:ctime  from "foo"  */
        if read3c( "foo", "bar", ALLAYS3, cdate, ctime, buffer ) ) { ... }
        else{ ... }
        }
    else
        {
        /* CANNOT read3c( "foo", ... ) --
           there is no legal date&time for "foo" just before jdate:jtime */
        }
    ...
    

Up: Date-Time Manipulation Routines

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