READ3() and read3c()

Fortran version:

    LOGICAL FUNCTION READ3( FNAME, VNAME, LAYER, JDATE, JTIME, BUFFER)
        CHARACTER*(*), INTENT(IN   ) :: FNAME     !  file name for query
        CHARACTER*(*), INTENT(IN   ) :: VNAME     !  vble  name   (or ALLVAR3 (='ALL'))
        INTEGER      , INTENT(IN   ) :: LAYER     !  layer number (or ALLAYS3 (=-1))
        INTEGER      , INTENT(IN   ) :: JDATE     !  date, formatted YYYYDDD
        INTEGER      , INTENT(IN   ) :: JTIME     !  time, formatted HHMMSS
        <type>       , INTENT(  OUT) :: BUFFER(*) !  array to hold input

C version:

read3c() is a C wrapper calling the Fortran READ3()

    int read3c( const char * fname ,
                const char * vname ,
                int          layer ,
                int          jdate ,
                int          jtime ,
                void       * buffer )

Summary:

Reads data from Models-3 data file with logical name FNAME for the variable with name VNAME and layer LAYER, for the date and time JDATE (coded YYYYDDD) and time JTIME (HHMMSS). For time independent files , JDATE:JTIME are ignored. If VNAME is the "magic value" ALLVAR3 (= 'ALL', defined in PARMS3.EXT ), reads all variables; if LAYER is the "magic number " ALLAYS3 (= -1, also defined in PARMS3.EXT), reads all layers. If FNAME is a dictionary file, READ3() treats VNAME as a dictionary index (and ignores JDATE:JTIME).

Only the all-layer all-variable mode is supported for files of type IDDATA3 , PROFIL3 , and GRNEST3 ; selectivity by layer and variable is supported for files of types CUSTOM3 , GRDDED3 , BNDARY3 , and SMATRX3 .

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.

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.

See also

DDTVAR3,
INTERP3 and INTERPX,
READ4D,
WRITE3,
XTRACT3,

Preconditions:

USE M3UTILIO or INCLUDE 'IODECL3.EXT' and INCLUDE 'FDESC3.EXT' for Fortran, or #include "iodecl3.h" and #include "fdesc3.h" for C.

I/O API must already be initialized by a call to INIT3().

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

FNAME must already have been opened by OPEN3() or open3c() .

JDATE and JTIME must be expressed in terms of Models-3 date and time conventions (and must be an exact positive integer multiple of the time step from the file's starting date and time).

Dimensionality of the BUFFER argument should agree with dimensionality of the data requested.

Fortran Usage:

(See sample programs PRESZ for additional usage examples.)

    ...
    USE M3UTILIO
    ...
    INTEGER NCOLS, NROWS, NLAYS, NMETS
    PARAMETER ( NCOLS = ??, NROWS = ??, NLAYS = ??, NMETS = ?? )
    ...
    REAL  HNO3( NCOLS, NROWS, NLAYS )
    REAL  SO4 ( NCOLS, NROWS, NLAYS )
    REAL  METS( NCOLS, NROWS, NLAYS, NVARS )
C            NOTE:  It isn't required that the name of the Fortran
C            variable match the name of the file-variable, but it
C            can often help the maintainability of the code if it does.
    ...
    IF ( READ3( 'MYFILE', 'HNO3', 3, 1988021, 123000,
 &              HNO3( 1,1,3 ) ) THEN
C            Layer 3 of variable 'HNO3' for 12:30:00 Jan 21, 1988
C            read from MYFILE into layer 3 of array HNO3.
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...
    IF ( READ3( 'AFILE', 'SO4', ALLAYS3, 1988021, 123000, SO4 ) ) THEN
C            All layers of SO4 for 12:30:00 Jan 21, 1988 read from AFILE
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...
    IF ( READ3( 'BFILE', ALLVAR3, ALLAYS3, 1988021, 123000, METS ) ) THEN
C            All BFILE-variables (all layers) for 12:30:00 Jan 21, 1988
C            read into array METS.
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...

C Usage:

    ...
    #include "iodecl3.h"
    ...
    float  mets[ NVARS ][ NLAYS ][ NROWS ][ NCOLS ] ;
    ...
    if ( read3c( "BFILE", "ALL", ALLAYS3, 1988021, 123000, mets ) )
        {
            /*  All BFILE-variables for 12:30:00 Jan 21, 1988
                read into array METS.                         */
        ...
        }
    else
        {
            /*  Error:  see program log for further info.  */
        ...
        }
    ...

Previous: OPEN3

Next: READ4D

Up: I/O API: Public Routines

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