---------------------------
MADIS Library Time Routines
---------------------------

The MADIS library's native time zone and format is Universal Coordinated Time, 
using a Julian date, in the form of "YYJJJHHMM", where:

  YY  = 2-digit year (good from 1980 - 2179)
  JJJ = Julian date of the year (001-366)
  HH  = Hour (00-23)
  MM  = Minute (00-59)

MADIS also provides support for a "Month/Day" date format, using "YYYYMMDD_HHMM", 
where:

  YYYY = 4-digit year (still only good from 1980 - 2179)
  MMDD = Month/Day 
  HHMM = Hour/Minute 

The MADIS library includes this basic set of routines for time manipulation:

  MCHGTIM:  Add and subtract time in the native format.

  MCHRTIM:  Translate integers representing year, month, day, hour and minute into 
            the native format.  

  MINTTIM:  Translate the native format to integers representing year, month, day, 
            hour, and minute.  

  MTRNTIM:  Translate between Julian and Month/Day formats.

----------------------------------------------------
Add and Subtract Time in the Native Format (MCHGTIM)
----------------------------------------------------

The MCHGTIM subroutine is used to determine a new time in 'YYJJJHHMM' format
from an old time plus additional seconds.


USAGE:    CALL MCHGTIM (OLDTIM,TIMINC,NEWTIM,STATUS)

  INPUT ARGUMENT LIST:

    OLDTIM   - Character*9  Old time in 'YYJJJHHMM'

    TIMING   - Integer      Delta time (in seconds).  may be positive or
                            negative

  OUTPUT ARGUMENT LIST:

    NEWTIM   - Character*9  New time in 'YYJJJHHMM'

    STATUS   - Integer      0 - Success, or error code


ERRORS:

  Error code       Error message
  -----------      -------------

       4           Invalid time                   


NOTES:

1.  An invalid time error is returned if OLDTIM is less than 9 characters,
    or contains a syntactically-incorrect string (019991200, 011232575, etc.).

---------------------------------------------------------------------------
Translate Integer Year, Month, Day, Hour, Minute to Native Format (MCHRTIM)
---------------------------------------------------------------------------

The MCHRTIM subroutine is used to convert integers for year month, day, hour 
and minute to 'YYJJJHHMM' time.


USAGE:    CALL MCHRTIM (NYEAR,NMONTH,NDAY,NHOUR,NMINUTE,CHRTIME,STATUS)

  INPUT ARGUMENT LIST:

    NYEAR    - Integer      Year since 1900 (e.g., 1999 --> 99, 2001 --> 101)

    NMONTH   - Integer      Month of year (1-12)

    NDAY     - Integer      Day of month (1-31)

    NHOUR    - Integer      Hour of day (0-23)

    NMINUTE  - Integer      Minute of hour (0-59)
    
  OUTPUT ARGUMENT LIST:

    CHRTIM   - Character*9  'YYJJJHHMM' time

    STATUS   - Integer      0 - Success, or error code


ERRORS:

  Error code       Error message
  -----------      -------------

       4           Invalid time                   


NOTES:

1.  An invalid time error is returned if out-of-range values are in the
    integer inputs (e.g., NHOUR = 25).

---------------------------------------------------------------------------
Translate Native Format to Integer Year, Month, Day, Hour, Minute (MINTTIM)
---------------------------------------------------------------------------

The MINTTIM subroutine is used to convert 'YYJJJHHMM' time into integers for
year, month, day, hour and minute.       


USAGE:    CALL MINTTIM (CHRTIME,NYEAR,NMONTH,NDAY,NHOUR,NMINUTE,STATUS)

  INPUT ARGUMENT LIST:

    CHRTIM   - Character*9  'YYJJJHHMM' to be converted

  OUTPUT ARGUMENT LIST:

    NYEAR    - Integer      Year since 1900 (e.g., 1999 --> 99, 2001 --> 101)

    NMONTH   - Integer      Month of year (1-12)

    NDAY     - Integer      Day of month (1-31)

    NHOUR    - Integer      Hour of day (0-23)

    NMINUTE  - Integer      Minute of hour (0-59)
    
    STATUS   - Integer      0 - Success, or error code


ERRORS:

  Error code       Error message
  -----------      -------------

       4           Invalid time                   


NOTES:

1.  An invalid time error is returned if CHRTIM is less than 9 characters,
    or contains a syntactically-incorrect string (019991200, 011232575, etc.).

-------------------------------------------------------------
Translate between Julian and Month/Day Time Formats (MTRNTIM)
-------------------------------------------------------------

The MTRNTIM subroutine is used to convert the two MADIS time formats ("native",
or "Julian", or 'YYJJJHHMM') and "Month/Day".


USAGE:    CALL MTRNTIM (TIM1,TRAN,TIM2,STATUS)

  INPUT ARGUMENT LIST:

    TIM1     - Character*(*)  Input time string (in whichever format)

    NYEAR    - Integer        1 - Translate Month/Day to Julian
                              2 - Tranlate Julian to Month/Day

  OUTPUT ARGUMENT LIST:

    TIM2     - Character*(*)  If TRAN = 1 TIM2 is Julian format:

                              'YYJJJHHMM' where,
                              'YY'  = 2-digit year (80-79, for 1980-2079)
                              'JJJ' = Julian date within year (1-366)
                              'HH'  = Hour
                              'MM'  = Minute
 
                              If TRAN = 2 TIM2 is Month/Day format:
 
                              'YYYYMMDD_HHMM' where,
                              'YYYY' = 4-digit year (still 1980-2079)
                              'MMDD' = Month/year (e.g. July 20 - 0720)
                              'HHMM' = Hour/minute

    STATUS   - Integer        0 - Success, or error code


ERRORS:

  Error code       Error message
  -----------      -------------

       4           Invalid time                   
      12           Invalid time translation format

NOTES:

1.  An invalid time error is returned if out-of-range values are in the
    character input time (e.g., 2001_07011200 when you meant 20010701_1200).

2.  An invalid time translation format error is returned if TRAN isn't 1 or 2.