WRITE3() and write3c()

Fortran version:

    LOGICAL FUNCTION WRITE3( FNAME, VNAME, JDATE, JTIME, BUFFER)
        CHARACTER*(*), INTENT(IN   ) :: FNAME     !  file name for query
        CHARACTER*(*), INTENT(IN   ) :: VNAME     !  vble  name   (or ALLVAR3 (='ALL'))
        INTEGER      , INTENT(IN   ) :: JDATE     !  date, formatted YYYYDDD
        INTEGER      , INTENT(IN   ) :: JTIME     !  time, formatted HHMMSS
        <type>       , INTENT(IN   ) :: BUFFER(*) !  array holding output data

C version:

write3c() is a C wrapper calling the Fortran WRITE3()

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

NOTE

The 2002 CMAQ release contains an unauthorized fork of the I/O API, with a new routines INTERPX and WRITEX. This latter routine does not respect I/O API data-integrity checking, and internal and on-disk data structures. It can lead to silent data corruption/data integrity problems unless the hardware and network interconnect work flawlessly, and then only if the model is running "stand-alone", with no other program reading the output while the model is running. This problem is inherent to the conncept of WRITEX, and is the result of the way the 2002 CMAQ release violates the Models-3 architectural analysis.

Carlie J. Coats, Jr., Ph.D.
I/O API Author

Summary:

Writes data for the variable with name VNAME, for the date and time JDATE (coded YYYYDDD), JTIME (HHMMSS) to Models-3 data file with logical name FNAME. For time independent files, JDATE:JTIME are ignored. If VNAME is the "magic name" ALLVAR3 (= 'ALL', defined in PARMS3.EXT ), WRITE3() writes all variables. If FNAME is a dictionary file, WRITE3() treats VNAME as a dictionary index (and ignores JDATE:JTIME).

Single-variable writes (as opposed to all-variable writes) are only supported for file types CUSTOM , GRIDDED , BOUNDARY , and SPARSE-MATRIX ; writes to files of type ID-REFERENCED , PROFILE , or GRID-NEST must be writes of all variables at a time step.

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.

See also

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

Preconditions:

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

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

FNAME and VNAME must have 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 agree with dimensionality of the data being written.

Fortran Usage:

(See sample programs LATLON, PRESZ, or SFCMET for additional usage examples.)

    ...
    USE M3UTILIO
    ...
    PARAMETER ( NCOLS = ??, NROWS = ??, NLAYS = ??, NMETS = ?? )
    ...
    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 ( WRITE3( 'AFILE', 'SO4', 1988021, 123000, SO4 ) ) THEN
C            All layers of SO4 for 12:30:00 Jan 21, 1988 written from AFILE
        ...
    ELSE
C           Error:  see program log for further info.
        ...
    END IF
    ...
    IF ( WRITE3( 'BFILE', ALLVARS3, 1988021, 123000, METS ) ) THEN
C            All BFILE-variables for 12:30:00 Jan 21, 1988 written from
C            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 ( write3c( "BFILE", "ALL", ALLAYS3, 
                  1988021, 123000, mets ) )
        {
            /*  All BFILE-variables for 12:30:00 Jan 21, 1988
                written from array METS.                         */
        ...
        }
    else
        {
            /*  Error:  see program log for further info.  */
        ...
        }
    ...

Previous: SHUT3

Next: XTRACT3

Up: I/O API: Public Routines

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