Procedure

     TPARCH ( Parse check---check format of strings )

     ENTRY TPARCH ( TYPE )

Abstract

     Restrict the set of strings that are recognized by SPICE time
     parsing routines to those that have standard values for all time
     components.

Required_Reading

     TIME

Keywords

     PARSING
     TIME

Declarations

    CHARACTER*(*)         TYPE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     TYPE       I   String: Use 'YES' to restrict time inputs.

Detailed_Input

     TYPE     is a character string that is used to adjust the set of
              strings that will be regarded as valid time strings by
              SPICE time parsing routines.

              The default behavior of SPICE time software is to allow
              an extended range of values for the various components
              (tokens) of a time string. For example, using its default
              behavior, TPARSE would regard 1993 JAN 367 as a valid
              time string and return the UTC seconds past the J2000
              epoch value that corresponds to Jan 2, 1994.

              While this is a "reasonable" interpretation of such a
              string, there may be occasions when such a string should
              be regarded as an error.

              By calling TPARCH with a value of 'YES', the action of
              the time software will be modified. Strings that have
              components that are out of the range of values used in
              most English discourse will be regarded as errors. Thus
              the numeric values of MONTH, DAY, HOUR, MINUTE, and
              SECOND must satisfy the following conditions to be
              regarded as legitimate calendar time strings.

                 ITEM     Valid Range
                 ------   -----------------------------------------
                 MONTH    1 to 13
                 DAY      1 to 365 (366 for leap years) when
                          DAY is interpreted as the day of year
                          i.e. the month token is empty.
                          1 to 31  if month is January
                          1 to 28  (29 in leap years) if month is
                                   February
                          1 to 31  if month is March
                          1 to 30  if month is April
                          1 to 31  if month is May
                          1 to 31  if month is June
                          1 to 30  if month is July
                          1 to 31  if month is August
                          1 to 30  if month is September
                          1 to 31  if month is October
                          1 to 30  if month is November
                          1 to 31  if month is December
                 HOUR     0 to 23
                 MINUTE   0 to 59
                 SECOND   0 up to but not including 60 on days that
                          can not have a leapsecond.
                          0 up to but not including 61 for times
                          that are the last second of June or
                          December. In other words,
                               JUN 30, 23:59:60.xxxxxx...x
                          and  DEC 31, 23:59:60.xxxxxx...x

              To reset the action of time software to the default
              action, set TYPE to a value that is not equivalent to
              'YES' when case and spaces are ignored.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     Error free.

Files

     None.

Particulars

     This routine is used to alter the collections of strings
     that SPICE software regards as legitimate calendar strings. The
     default behavior of SPICE software is to accept strings such
     as FEB 34, 1993 and to interpret these in a "natural way"
     (FEB 34, 1993 is regarded as MARCH 6, 1993.) This behavior
     is sometimes useful for "private" programs that you write.
     However, such a string may be a typo (a finger accidentally hit
     two keys for the day instead of one). Given that this string
     does not appear in common usage, you may want to consider
     that it is more likely the result of erroneous input. You
     can alter the behavior of SPICE software so that it will
     treat such a string as an error. To do this call this entry
     point with TYPE having the value 'YES'.

        CALL TPARCH ( 'YES' )

     Until the behavior is reset by calling TPARCH with a value
     other than 'YES' (such as 'NO'), SPICE software will treat all
     out-of-bound components of time strings as errors.

     If you are happy with the SPICE default interpretation of
     strings, you do not need to make any calls to TPARCH.

     All time parsing routines --including the top-level APIs TPARSE
     and UTC2ET-- respect the setting assigned by TPARCH, except the
     SPICELIB routine STR2ET.

Examples

     The numerical results shown for this example may differ across
     platforms. The results depend on the SPICE kernels used as
     input, the compiler and supporting libraries, and the machine
     specific arithmetic implementation.

     1) When accepting times as input interactively, you usually
        read a string typed at a keyboard and then pass that string
        to the SPICE time system to convert it to an ephemeris time.
        The default behavior of SPICE software is to accept strings
        such as FEB 34, 1993 and to interpret these in a "natural way"
        (FEB 34, 1993 is regarded as MARCH 6, 1993.) The following
        example code demonstrates how to modify this behavior.


        Example code begins here.


              PROGRAM TPARCH_EX1
              IMPLICIT NONE

        C
        C     Local parameters.
        C
              CHARACTER*(*)         TIMSTR
              PARAMETER           ( TIMSTR = 'FEB 34, 1993' )

              INTEGER               ERRMLN
              PARAMETER           ( ERRMLN = 1000 )

        C
        C     Local variables.
        C
              CHARACTER*(ERRMLN)    ERRMSG

              DOUBLE PRECISION      SP2000

        C
        C     First, demonstrate the default behavior of SPICE.
        C     Let's get the number of UTC seconds past J2000 epoch.
        C
              CALL TPARSE ( TIMSTR, SP2000, ERRMSG )

              IF ( ERRMSG .EQ. ' ' ) THEN

                 WRITE(*,'(A,F18.6)') 'UTC (s): ', SP2000

              ELSE

                 WRITE(*,'(2A)') 'Error  : ', ERRMSG

              END IF

        C
        C     Now, turn error checking on and parse the time string
        C     again.
        C
              CALL TPARCH ( 'YES' )
              CALL TPARSE ( TIMSTR, SP2000, ERRMSG )

              IF ( ERRMSG .EQ. ' ' ) THEN

                 WRITE(*,'(A,F18.6)') 'UTC (s): ', SP2000

              ELSE

                 WRITE(*,'(2A)') 'Error  : ', ERRMSG

              END IF

              END


        When this program was executed on a Mac/Intel/gfortran/64-bit
        platform, the output was:


        UTC (s):  -215352000.000000
        Error  : The day of the month specified for the month of Feb***


        Warning: incomplete output. 1 line extended past the right
        margin of the header and has been truncated. This line is
        marked by "***" at the end of the line.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

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

Version

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

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

        Edited the header to comply with NAIF standard. Added complete
        code example.

        Added TIME to $Required_Reading list.

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

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

    SPICELIB Version 1.0.0, 07-APR-1996 (WLT)

        The entry point TPARCH was moved from TPARSE to the routine
        TCHECK so that all time parsing actions could be centralized.