DATAFILE.TXT    Description of GISS datafiles    2002/05/10

Introduction
------------
     Throughout these web pages, the term "DataFile" is used frequently
to refer to a particular kind of file.  DataFiles were written by a
UNIX Fortran program in "unformatted" mode, and consequently need to be
translated before being understood by PC programs.  It is important
that binary mode is used when copying DataFiles from one computer
system to another.  Examples of DataFiles are:

     the Model's surface fractions and topography file: Z72X46N ,
     model generated output fields in directories  A1  or  M10 ,
     observed fields in the directory  OBS ,
     files  ????.CP  which were written by the Color Plot programs.


How to read a DataFile in a UNIX Fortran program
------------------------------------------------
     The following program segment will read the first two
records of the DataFile DATAFILE.XXX into a UNIX Fortran program:

     PARAMETER (IM=72,JM=46, DATMIS=-999999.)
     CHARACTER TITLE1*80, TITLE2*80
     REAL*4 DATA1(IM,JM), DATA2(IM,JM)
     OPEN (1,FILE='DATAFILE.XXX',FORM='UNFORMATTED',STATUS='OLD')
     READ (1) TITLE1,DATA1
     READ (1) TITLE2,DATA2
     CLOSE (1)
     IF(DATA1(1,1).le.DATMIS)  GO TO ???  !  jump for missing data

     Unlike other workstations, DEC Alpha workstations use least
significant byte first for number ordering.  There are two methods that
allow DEC Alpha workstation to read properly our DataFiles:
1. use "-convert big_endian" as a Fortran compiler option;
2. include the option  CONVERT='BIG_ENDIAN'  in the Fortran OPEN
   statement.


Organization of data in a DataFile
----------------------------------
     DataFiles contain one or more records.  Each record contains the
following information:

     a 4 byte integer,
     an ASCII encoded 80 byte character string,
     IMxJM floating point variables of 4 bytes each,
     another 4 byte integer.

The 4 byte integers at the beginning and end of the record should have
the value 13328 (= 80 + 4*72*46).  The floating point variables are
encoded in IEEE format for REAL*4 numbers.  The 4 byte integers and
floating point variables are stored in the record with high order bytes
first.  This is different than the byte ordering used by Intel PC
machines and DEC Alpha workstations, which store integers and floating
point variables with low order bytes first.  The number of bytes of a
DataFile with N records should be 13336*N [= (4 + 80 + 4*72*46 + 4)*N].


Information contained in the record titles
------------------------------------------
     The 80 byte title in each record of a DataFile should contain the
following information:

     name of quantity and physical units of quantity in parentheses
        in columns 1-48, quantities should be all caps except for
        prepositions;
     source of data, Model simulation number starting in column 51 or
        observer's name starting in columns 51 or 41;
     resolution of the data such as 5x4 degrees or 46x9 grid cells;
     year or years when quantity was measured in columns 65-68,
        "1950" means year 1950,
        "199X" mean years 1990 to 1999 inclusive,
        "7294" mean years 1972 to 1994 inclusive;
     month (Jan),  annual average (Ann), seasonal average (DJF), or
        quarter (JFM) in columns 70-72.

For data that has temporal resolution finer than monthly, use the form:
1776/07/04/00 in columns 65-77.


How to list the record titles of a DataFile
-------------------------------------------
     The Fortran source program, QDF.FOR, is available on these web
pages under "MODEL CODE".  Compile QDF.FOR and rename the executable
module as QDF.  At the UNIX prompt, execute:  QDF DataFile .
This will write the first 72 characters of each record title of the
DataFile to standard output.