=== +-======-+ 
===  Copyright (c) 2003-2007 United States Government as represented by 
===  the Admistrator of the National Aeronautics and Space Administration.  
===  All Rights Reserved.
===  
===  THIS OPEN  SOURCE  AGREEMENT  ("AGREEMENT") DEFINES  THE  RIGHTS  OF USE,
===  REPRODUCTION,  DISTRIBUTION,  MODIFICATION AND REDISTRIBUTION OF CERTAIN 
===  COMPUTER SOFTWARE ORIGINALLY RELEASED BY THE UNITED STATES GOVERNMENT AS 
===  REPRESENTED BY THE GOVERNMENT AGENCY LISTED BELOW ("GOVERNMENT AGENCY").  
===  THE UNITED STATES GOVERNMENT, AS REPRESENTED BY GOVERNMENT AGENCY, IS AN 
===  INTENDED  THIRD-PARTY  BENEFICIARY  OF  ALL  SUBSEQUENT DISTRIBUTIONS OR 
===  REDISTRIBUTIONS  OF THE  SUBJECT  SOFTWARE.  ANYONE WHO USES, REPRODUCES, 
===  DISTRIBUTES, MODIFIES  OR REDISTRIBUTES THE SUBJECT SOFTWARE, AS DEFINED 
===  HEREIN, OR ANY PART THEREOF,  IS,  BY THAT ACTION, ACCEPTING IN FULL THE 
===  RESPONSIBILITIES AND OBLIGATIONS CONTAINED IN THIS AGREEMENT.
===  
===  Government Agency: National Aeronautics and Space Administration
===  Government Agency Original Software Designation: GSC-15354-1
===  Government Agency Original Software Title:  GEOS-5 GCM Modeling Software
===  User Registration Requested.  Please Visit http://opensource.gsfc.nasa.gov
===  Government Agency Point of Contact for Original Software:  
===  			Dale Hithon, SRA Assistant, (301) 286-2691
===  
=== +-======-+ 
zeit software instructions and information

The program structure is as follows:

zeit_ci.x [-r fname] [-v] [name]
   |
  zeit_usage

zeit_co.x [-r fname] [-v] [name]
   |
  zeit_usage

zeit_pr.x [fname] out_fname | -s suminfile [sumoutfile]
   | |
   | zeit_usage
   |
   zeit_read
      |
     zeit_jday
  

To compile run the following commands at the command prompt:

make all

For ci/co
-r          Option to generate a registry file of timings.
fname       Name of registry input file; .zeit is the default fname if fname 
            is not specified
-v          Prints the current wallclock time to standard out
name        The name of the program to be timed

For zeit_pr
-i          Indicate use of a users registry file.
fname       Name of registry input file; .zeit is 
            the default fname.
-o          Indicate name of an outputfile.
out_fname   Output file name of current timings
            report.  If none is specified the report
            prints to standard output.
-d          An option to remove the registry file.
-h          An option to print usage information.

When zeit_ci and zeit_co run, they create and append to a registry using that
looks like this:

zeit_ci main             Date 20020104 Time 19 46 48 630
zeit_ci ztest            Date 20020104 Time 19 46 48 680
zeit_co ztest            Date 20020104 Time 19 47 04 925
zeit_ci ptest            Date 20020104 Time 19 47 04 988
zeit_co ptest            Date 20020104 Time 19 47 20 648
zeit_ci testjunk         Date 20020104 Time 19 47 20 706
zeit_co testjunk         Date 20020104 Time 19 47 32 449
zeit_co main             Date 20020104 Time 19 47 32 534

zeit_pr is then run to create a report using the m_zeit module.  The user may, 
in fact, concatenate many registry file to generate a single summary report.

[MWTIME]     counts period    NET    m:s      %    SCOPE    m:s      %
------------------------------------------------------------------------
.zeit.        1s  0/   2      0.0   00:00   0.0+    48.1   00:48 100.0+
main             1    0.2     0.2   00:00   0.5%    48.1   00:48 100.0%
ztest            1   16.2    16.2   00:16  33.8%    16.2   00:16  33.8%
ptest            1   15.7    15.7   00:16  32.5%    15.7   00:16  32.5%
testjunk         1   16.0    16.0   00:16  33.2%    16.0   00:16  33.2%
------------------------------------------------------------------------

Because zeit_ci and zeit_co can only create or append to the registry file,
the user must be careful to make sure that ci/co calls are balanced, that the
correct registry file is being written to, and that the registry is properly
edited in the event of a false start during the timing of a script.  Also, if
registry files are concatenated to generate a longer-term summary report, the
user must be careful to only concatenate registries for the same script 
timing.  Otherwise, time data for different programs and different scripts
will be analyzed together and timing statistics might not be meaningful,
especially for the main programs/scripts.  To avoid confusion it is suggested 
that the user do the following:

(1) Use different names for each registry file generated.  Perhaps include the
name of the script being timed and the date/time in the registry name.  

There is also an option (-d) that can be given to zeit_pr.x to remove the 
registry when the report generation has completed.  

(2) Even if the user does not want to generate a report immediately.  The user 
should always run zeit_pr.x to insure that the ci/co calls are balanced.


Tom King 06/05/2002