XTRACT3() and xtract3c()

Fortran version:

    LOGICAL FUNCTION XTRACT3( FNAME, VNAME, 
 &                        LAY0, LAY1, ROW0, ROW1, COL0, COL1,
 &                        JDATE, JTIME, BUFFER )
 &                            
        CHARACTER*(*), INTENT(IN   ) :: FNAME     !  file name for query
        CHARACTER*(*), INTENT(IN   ) :: VNAME     !  vble  name   (or ALLVAR3 (='ALL'))
        INTEGER      , INTENT(IN   ) :: LAY0      !  lower layer bound
        INTEGER      , INTENT(IN   ) :: LAY1      !  upper layer bound
        INTEGER      , INTENT(IN   ) :: ROW0      !  lower row bound
        INTEGER      , INTENT(IN   ) :: ROW1      !  upper row bound
        INTEGER      , INTENT(IN   ) :: COL0      !  lower col bound
        INTEGER      , INTENT(IN   ) :: COL1      !  upper col bound
        INTEGER      , INTENT(IN   ) :: JDATE     !  date, formatted YYYYDDD
        INTEGER      , INTENT(IN   ) :: JTIME     !  time, formatted HHMMSS
        <type>       , INTENT(  OUT) :: BUFFER(*) !  array to hold input

C version:

xtract3c() is a C wrapper calling the Fortran XTRACT3()

    int xtract3c( const char * fname , const char * vname ,
                  int          lolay , int          hilay ,
                  int          lorow , int          hirow ,
                  int          locol , int          hicol ,
                  int          jdate , int          jtime ,
                  void       * buffer )

Summary:

              LAY0 <= LAY <= LAY1
              ROW0 <= ROW <= ROW1
              COL0 <= COL <= COL1

For time independent files, JDATE:JTIME are ignored. If VNAME is ALLVAR3 (= 'ALL', defined in PARMS3.EXT ), reads all variables.

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.

For Fortran-90 declaration:

    USE M3UTILIO
    

See also

DDTVAR3,
INTERP3 and INTERPX,
READ3,
WRITE3,

Preconditions:

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

FNAME and VNAME must have effective length at most 16.

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 match the dimensionality of the window into the grid.

Dimensionality of the data window should be consistent with (should be a subwindow of) with dimensionality of the data in the file.

Fortran Usage:

    ...
    USE M3UTILIO
    ...
    REAL  WNDWHNO3( 10, 10, 1 )
    REAL  CELLSO4
    ...
    IF ( XTRACT3( 'MYFILE', 'HNO3', 3, 3, 15, 24, 11, 20,
 &                1988021, 123000,  WNDWHNO3 ) ) THEN
C            Window specified by layer 3, rows 15-24, and columns 11-20
C            of variable 'HNO3' for 12:30:00 Jan 21, 1988
C            read from MYFILE into array WNDWHNO3.
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...
    IF ( XTRACT3( 'MYFILE', 'SO4', 5, 5, 7, 7, 9, 9,
 &                1988021, 123000,  CELLSO4 ) ) THEN
C            Individual cell value at layer 5, row 7, and column 9
C            of variable 'SO4' for 12:30:00 Jan 21, 1988
C            read from MYFILE into variable CELLSO4
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...

C Usage:

    ...
    #include "iodecl3.h"
    ...
    float  wndwhno3[ 2 ][ 10 ][ 10 ] ;
    ...
    if ( xtract3c( "BFILE", "HNO3", 3, 4, 15, 24, 11, 20,
                   1988021, 123000, mets ) )
        {
            /*  Data-window specified by layers 3-4, rows 15-24, and
                columns 11-20 of variable 'HNO3' for 12:30:00 
                Jan 21, 1988 read from MYFILE into array wndwhno3
            */
        ...
        }
    else
        {
            /*  Error:  see program log for further info.  */
        ...
        }
    ...

Next: KFINDX

Up: I/O API: Public Routines

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