PUBLIC INTERFACE ~ PUBLIC ROUTINES ~ ERROR MESSAGES

## Module diag_table_mod

Contact: Seth Underwood
Reviewers:
Change History: WebCVS Log

#### OVERVIEW

`diag_table_mod` is a set of subroutines use to parse out the data from a `diag_table`. This module will also setup the arrays required to store the information by counting the number of input fields, output files, and files.

`diag_table_mod` parses the `diag_table` file, and sets up the required arrays to hold the information needed for the `diag_manager_mod` to correctly write out the model history files.
The diagnostics table allows users to specify sampling rates and the choice of fields at run time. The `diag_table` file consists of comma-separated ASCII values. The `diag_table` essentially has three sections: Global, File, and Field sections. The Global section must be the first two lines of the file, whereas the File and Field sections can be inter mixed to allow the file to be organized as desired. Comments can be added to the `diag_table` file by using the hash symbol (#) as the first character in the line.
All errors in the `diag_table` will throw a `FATAL` error. A simple utility `diag_table_chk`has been added to the FRE tools suite to check a `diag_table` for errors. A brief usage statement can be obtained by running `diag_table_chk --help`, and a man page like description can views by running `perldoc diag_table_chk`.
Below is a description of the three sections.

1. Global Section: The first two lines of the `diag_table` must contain the title and the base date of the experiment respectively. The title must be a Fortran CHARACTER string. The base date is the reference time used for the time units, and must be greater than or equal to the model start time. The base date consists of six space-separated integer in the following format.
   `year month day hour minute second`
2. File Section: File lines contain 6 required and 5 optional fields (optional fields are surrounded with square brackets ([]). File lines can be intermixed with the field lines, but the file must be defined before any fields that are to be written to the file. File lines have the following format:
   `"file_name", output_freq, "output_freq_units", file_format, "time_axis_units", "time_axis_name" [, new_file_freq, "new_file_freq_units"[, "start_time"[, file_duration, "file_duration_units"]]]`
   with the following descriptions.
   `CHARACTER(len=128) :: file_name`
     Output file name without the trailing "`.nc`".
     A single file description can produce multiple files using special time string suffix keywords. This time string will append the time strings to the base file name each time a new file is opened. They syntax for the time string suffix keywords are `%#tt` Where `#` is a mandatory single digit number specifying the width of the field, and `tt` can be as follows:
     1. `yr` – Years
     2. `mo` – Months
     3. `dy` – Days
     4. `hr` – Hours
     5. `mi` – Minutes
     6. `sc` – Seconds
     Thus, a file name of `file2_yr_dy%1yr%3dy` will have a base file name of `file2_yr_dy_1_001` if the file is created on year 1 day 1 of the model run. NOTE: The time suffix keywords must be used if the optional fields `new_file_freq` and `new_file_freq_units` are used, otherwise a `FATAL` error will occur.
   `INTEGER :: output_freq`
     How often to write fields to file.
     1. `> 0` – Output frequency in `output_freq_units`.
     2. `= 0` – Output frequency every time set. (`output_freq_units` is ignored.)
     3. `=-1` – Output at end of run only. (`output_freq_units` is ignored.)
   `CHARACTER(len=10) :: output_freq_units`
     Time units for output. Can be either `years`, `months`, `days`, `minutes`, `hours`, or `seconds`.
   `INTEGER :: file_format`
     Output file format. Currently only the netCDF file format is supported.
     1. `= 1` – netCDF
   `CHARACTER(len=10) :: time_axis_units`
     Time units for the output file time axis. Can be either `years`, `months`, `days`, `minutes`, `hours`, or `seconds`.
   `CHARACTER(len=128) :: time_axis_name`
     Axis name for the output file time axis. The character sting must contain the string 'time'. (mixed upper and lowercase allowed.)
   `INTEGER, OPTIONAL :: new_file_freq`
     Frequency for closing the existing file, and creating a new file in `new_file_freq_units`.
   `CHARACTER(len=10), OPTIONAL :: new_file_freq_units`
     Time units for creating a new file. Can be either `years`, `months`, `days`, `minutes`, `hours`, or `seconds`. NOTE: If the `new_file_freq` field is present, then this field must also be present.
   `CHARACTER(len=25), OPTIONAL :: start_time`
     Time to start the file for the first time. The format of this string is the same as the global date. NOTE: The `new_file_freq` and the `new_file_freq_units` fields must be present to use this field.
   `INTEGER, OPTIONAL :: file_duration`
     How long file should receive data after start time in `file_duration_units`. This optional field can only be used if the `start_time` field is present. If this field is absent, then the file duration will be equal to the frequency for creating new files. NOTE: The `file_duration_units` field must also be present if this field is present.
   `CHARACTER(len=10), OPTIONAL :: file_duration_units`
     File duration units. Can be either `years`, `months`, `days`, `minutes`, `hours`, or `seconds`. NOTE: If the `file_duration` field is present, then this field must also be present.
3. Field Section: Field lines contain 8 fields. Field lines can be intermixed with file lines, but the file must be defined before any fields that are to be written to the file. Fields line can contain fields that are not written to any files. The file name for these fields is `null`.
   Field lines have the following format:

        "module_name", "field_name", "output_name", "file_name", "time_sampling", "reduction_method", "regional_section", packing

   with the following descriptions.
   `CHARACTER(len=128) :: module_name`
     Module that contains the `field_name` variable. (e.g. `atmos_mod`, `land_mod`)
   `CHARACTER(len=128) :: field_name`
     Module variable name that has data to be written to file.
   `CHARACTER(len=128) :: output_name`
     Name of the field as written in `file_name`.
   `CHARACTER(len=128) :: file_name`
     Name of the file where the field is to be written. NOTE: The file `file_name` must be defined first.
   `CHARACTER(len=50) :: time_sampling`
     Currently not used. Please use the string "all".
   `CHARACTER(len=50) :: reduction_method`
     The data reduction method to perform prior to writing data to disk. Valid options are (redundant names are separated with commas):
     `.TRUE.`, average
       Average from the last time written to the current time.
     `.FALSE.`, none
       No reduction performed. Write current time step value only.
     min
       Minimum value from last write to current time.
     max
       Maximum value from last write to current time.
     diurnal##
       ## diurnal averages
   `CHARACTER(len=50) :: regional_section`
     Bounds of the regional section to capture. A value of `none` indicates a global region. The regional section has the following format:
     `lat_min, lat_max, lon_min, lon_max, vert_min, vert_max`
     Use `vert_min = -1` and `vert_max = -1` to get the entire vertical axis. NOTE: Currently, the defined region MUST be confined to a single tile.
   `INTEGER :: packing`
     Fortran number `KIND` of the data written. Valid values:
     1. `= 1` – double precision
     2. `= 2` – float
     3. `= 4` – packed 16-bit integers
     4. `= 8` – packed 1-byte (not tested).

#### Sample `diag_table`

1.      "diag manager test"
        1999 1 1 0 0 0

        #output files
        10_days,               10, "days", 1, "hours", "Time"
        "file1_hr%hr3",         5, "days", 1, "hours", "Time", 15, "days"
        "file2_yr_dy%yr1%dy3",  5, "days", 1, "hours", "Time", 10, "days", "1 1 7 0 0 0"
        "file3_yr_dy%yr1%dy3",  5, "days", 1, "hours", "Time", 20, "days", "1 1 7 0 0 0", 5, "years"

        #output variables
        "ice_mod", "ice", "ice", "10_days", "all", .false., "none", 2

        # temp_local file and fields.
        temp_local, 1, "days", 1, "hours", "Time"
        "ocean_mod", "temp", "temp", "temp_local", "all", .FALSE., "5 259.5 -59.5 59.5 1 1", 2

#### Useful Additional Utility

A simple utility has been created to help discover

#### OTHER MODULES USED

          mpp_io_mod
             fms_mod
    time_manager_mod
       constants_mod
       diag_data_mod
       diag_util_mod

#### PUBLIC INTERFACE

parse_diag_table:
  Parse the `diag_table` in preparation for diagnostic output.

#### PUBLIC ROUTINES

1. #### parse_diag_table

       SUBROUTINE parse_diag_table (diag_subset, istat, err_msg)

   DESCRIPTION
     `parse_diag_table` is the public interface to parse the diag_table, and setup the arrays needed to store the requested diagnostics from the `diag_table`. `parse_diag_table` will return a non-zero `istat` if a problem parsing the `diag_table`.
     NOT YET IMPLEMENTED: `parse_diag_table` will parse through the `diag_table` twice. The first pass, will be to get a good "guess" of array sizes. These arrays, that will hold the requested diagnostic fields and files, will then be allocated to the size of the "guess" plus a slight increase.
   INPUT

     `diag_subset` | Diagnostic sampling subset. [INTEGER, OPTIONAL]

   OUTPUT

     `iunit` | Status of parsing the `diag_table`. A non-zero status indicates a problem parsing the table. [INTEGER, OPTIONAL]
     `err_msg` | Error message corresponding to the `istat` return value. [CHARACTER(len=*), OPTIONAL]

#### ERROR MESSAGES

FATAL in parse_diag_table
  diag_table file does not exist.
FATAL in parse_diag_table
  Error reading the global descriptor from the diagnostic table.
FATAL in parse_diag_table
  Error reading the base date from the diagnostic table.
FATAL in parse_diag_table
  The base_year/month/day can not equal zero
WARNING in parse_diag_table
  Problem reading diag_table, line numbers in errors may be incorrect.
FATAL in parse_diag_table
  Problem reading the diag_table (line: <line_number>)
FATAL in parse_diag_table
  Incorrect file description FORMAT in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Invalid file FORMAT for file description in the diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Invalid time axis units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Invalid output frequency units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Invalid NEW file frequency units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Invalid file duration units in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Invalid start time in the file description in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Field description FORMAT is incorrect in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Packing is out of range for the field description in diag_table. (line: <line_number>)
FATAL in parse_diag_table
  Error in regional output description for field description in diag_table. (line: <line_number>)

top