Index Page
tcheck
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Procedure
Abstract
Required_Reading
Keywords
Declarations
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version

Procedure

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

Abstract

    If component checking is enabled, this routine
    determines whether the components of a time vector are in
    the "usual" range for the components.  If component checking
    is not enabled, this routine simply returns after setting
    the outputs.

Required_Reading

     None.

Keywords

     TIME

Declarations

      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 diagnosed 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

     W.L. Taber      (JPL)

Version

    SPICELIB Version 1.0.0, 26-JUL-1996 (WLT)
Wed Jun  9 12:59:29 2010