Procedure

     TCHECK ( Time Check )

     SUBROUTINE TCHECK ( TVEC, TYPE, MODS, MODIFY, OK, ERROR )

Abstract

     Determine whether the components of a time vector are in the
     "usual" range for the components, if component checking is
     enabled.

     If component checking is not enabled, this routine simply
     returns after setting the outputs.

Required_Reading

     None.

Keywords

     TIME

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION      TVEC   ( * )
     CHARACTER*(*)         TYPE
     LOGICAL               MODS
     CHARACTER*(*)         MODIFY ( * )
     LOGICAL               OK
     CHARACTER*(*)         ERROR

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     TVEC       I   A vector of time components
     TYPE       I   The type of time vector.
     MODS       I   A logical indicating the presence of modifiers
     MODIFY     I   The values of the modifiers
     OK         O   Indicates success or failure of component checks.
     ERROR      O   Diagnostic message if .NOT. OK.

Detailed_Input

     TVEC     is an array of double precision numbers that
              represent the components of some calendar epoch.

     TYPE     is kind of calendar epoch represented by TVEC
              legitimate values are 'YMD' and 'YD'

     MODS     is a logical flag indicating whether any of the
              items in MODIFY are non-blank. If some item
              in MODIFY is non-blank, MODS will be .TRUE. If
              all items in MODIFY are blank, MODS will be .FALSE.

     MODIFY   is an array of strings indicating how the
              interpretation of the various components of TVEC
              should be modified. Blank values indicate that
              the default interpretation should be applied.
              Non-blank components will have the following values
              and meanings.


               Component   Meaning   Possible Non-blank Modifier Values
               ---------   -------   ----------------------------------
               1           ERA       'A.D.', 'B.C.'
               2           Weekday   'SUN',  'MON', ... etc.
               3           AM/PM     'A.M.', 'P.M.'
               4           System    'UTC',  'TDB', 'TDT'
               5           Time Zone 'UTC+i:i', 'UTC-i:i'

Detailed_Output

     OK       is returned .TRUE. if all components of TVEC are within
              the normal range of values. If some problem arises,
              OK will be returned with the value .FALSE. Note that
              component checking has not been enabled by a call
              to TPARCH, the value of OK is automatically set to
              .TRUE.

     ERROR    if OK is returned with the value .TRUE., ERROR will be
              returned as a blank. However, if OK is .FALSE., ERROR
              will contain a diagnostic indicating what was wrong
              with the components of TVEC. Note that
              component checking has not been enabled by a call
              to TPARCH, the value of ERROR is automatically set to
              a blank.

Parameters

     None.

Exceptions

     Error free.

     1)  All problems with TVEC are reported via the logical OK
         and the message ERROR.

Files

     None.

Particulars

     This routine works in conjunction with the entry point TPARCH.
     If TPARCH has not been called with the input value 'YES' this
     routine simply sets the outputs as indicated above and returns.

     Usually strings such as February 32, 1997 are regarded as
     erroneous. However, the SPICE time subsystem is capable
     of attaching meaning to such strings. The routines TPARCH and
     TCHECK allow you to treat such strings as erroneous throughout
     the SPICE time sub-system.

     This routine examines the components of a time vector and
     determines whether or not all of the values in the vector
     are within the normal bounds.

     To pass inspection:

        Years must be integers.

        Months must be in the range from 1 to 12 and must be integers.

        Days of the month must be in the normal ranges. For example
             if the month specified is January, the day of the month
             must be greater than or equal to 1.0D0 and strictly less
             than 32.0D0 (The normal range for February is a function
             of whether the year specified is a leap year. The
             Gregorian calendar is used to determine leap years.)

        Day of the year must be greater than or equal to 1.0D0
             and strictly less than 366.0D0  (367.0D0 in a leap year.
             The Gregorian calendar is used to determine leap years.)

        Hours must be greater than or equal to 0.0D0 and strictly
             less than 24.0D0. If the AMPM modifier is included
             hours must be greater than or equal to 1.0D0 and strictly
             less than 13.0D0.

        Minutes must be greater than or equal to 0.0D0 and must
             be strictly less than 60.0D0

        Seconds must be greater than or equal to 0.0D0 and strictly
             less than 60.0D0 (61.0D0 during the last minute of the
             30th of June and the 31st of December).

        If some component other than the seconds component is
        not an integer, all components of lesser significance must
        be zero.

     This routine  is designed to work in conjunction
     with the SPICE routine TPARTV and it is anticipated that
     it will be called in the following fashion

        CALL TPARTV ( STRING, TVEC, NTVEC,  TYPE,
       .              MODIFY, MODS, YABBRV, SUCCES, ERROR )

        IF ( .NOT. SUCCES ) THEN

           communicate the diagnostic message and
           take other actions as appropriate

           RETURN

        END IF

        IF ( SUCCES .AND. CHECK ) THEN
            CALL TCHECK ( TVEC, TYPE, MODS, MODIFY, OK, ERROR )
        END IF

        IF ( .NOT. OK ) THEN

           communicate the diagnostic message and
           take other actions as appropriate

           RETURN

        END IF

Examples

     Suppose that you have parsed a string (via TPARTV) and want
     to enforce normal ranges of the components. The following
     sequence of calls will perform the checks on components.

        get the current checking setting

        CALL TCHCKD ( CURNT )

        turn on component checking.

        CALL TPARCH ( 'YES' )

        Check the components.

        CALL TCHECK ( TVEC, TYPE, MODS, MODIFY, OK, ERROR )

        Reset the checking setting to the original value.

        CALL TPARCH ( CURNT )


        Now handle any problems that were diagnosed by TCHECK

        IF ( .NOT. OK ) THEN

           do something

        END IF

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 1.2.0, 01-NOV-2021 (JDR) (EDW)

        Added logic to prevent evaluation of MODIFY when MODS false.

        Added text listing routines affected and not affected by
        explicit assignments to TPARCH.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.1.0, 31-JAN-2017 (NJB)

        Bug fix: updated logic so that B.C. leap years are recognized.

    SPICELIB Version 1.0.1, 10-FEB-2014 (BVS)

        Fixed typo in the $Declarations section in the TPARCH header:
        STRING -> TYPE.

    SPICELIB Version 1.0.0, 26-JUL-1996 (WLT)