Index Page
timdef
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

      TIMDEF ( Time Software Defaults )
 
      SUBROUTINE TIMDEF ( ACTION, ITEM, VALUE )
 

Abstract

     Set and retrieve the defaults associated with calendar
     input strings.

Required_Reading

      None.

Keywords

      TIME

Declarations

 
 
      IMPLICIT NONE
      CHARACTER*(*)         ACTION
      CHARACTER*(*)         ITEM
      CHARACTER*(*)         VALUE
 
 

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     ACTION     I   is the kind of action to take 'SET' or 'GET'.
     ITEM       I   is the default item of interest.
     VALUE     I/O  is the value associated with the default item.

Detailed_Input

     ACTION     is a word that specifies whether TIMDEF sets the
                value associated with ITEM or retrieves the value
                associated with ITEM.  The allowed values for
                ACTION are 'SET' and 'GET'.  The routine is not
                sensitive to the case of the letters in ACTION.

     ITEM       is the default items whose value should be set or
                retrieved.  The items that may be requested are:

                ITEM        Allowed Values
                ---------   --------------
                CALENDAR    GREGORIAN
                            JULIAN
                            MIXED

                SYSTEM      TDB
                            TDT
                            UTC

                ZONE        EST, EDT, CST, CDT, MST, MDT, PST, PDT
                            UTC+HR
                            UTC-HR       ( 0 <= HR < 13 )
                            UTC+HR:MN    ( 0 <= MN < 60 )
                            UTC-HR:MN

                The case of ITEM is not significant.


     VALUE      if the action is 'SET' then VALUE is an input and
                is the value to be associated with ITEM.  Note that
                VALUE is checked to ensure it is within the range
                of allowed values for ITEM.  If it is not within
                the expected range and appropriate error message
                is signalled.  The case of VALUE is not significant.

Detailed_Output

     VALUE      if the action is 'GET' then VALUE will be the
                value associated with the requested ITEM.  Note that
                when time zones are set, they are translated to the
                UTC offset form ( UTC(+/-)HR[:MN] ).  When VALUE is
                an output it will be in upper case.

Parameters

     None.

Exceptions

     1) If the ACTION specified is not SET or GET the error
        'SPICE(BADACTION)' is signalled.

     2) If the ITEM specified is not one the recognized items
        the error 'SPICE(BADTIMEITEM)' is signalled.

     3) If the value associated with a 'SET', item input
        is not one of the recognized items, the error
        'SPICE(BADDEFAULTVALUE)' is signalled.

Files

     None.

Particulars

     This routine exists to allow SPICE toolkit users to alter
     the default interpretation of time strings made by the
     routine STR2ET.

     Normally, unlabelled time strings are assumed to belong to
     the Gregorian Calendar and are UTC times.  However, you
     may alter the default behavior by calling TIMDEF.

     Calendar
     --------

     You may set the calendar to be one of the following

     Gregorian   --- This is the calendar used daily the
                     Western Hemisphere.  Leap years occur in this
                     calendar every 4 years except on centuries
                     such as 1900 that are not divisible by 400.

     Julian      --- This is the calendar that was in use prior
                     to October 15, 1582.  Leap years occur every
                     4 years on the Julian Calendar (including all
                     centuries.)  October 5, 1582 on the Julian
                     calendar corresponds to October 15, 1582 of the
                     Gregorian Calendar.

     Mixed       --- This calendar uses the Julian calendar
                     for days prior to October 15, 1582 and
                     the Gregorian calendar for days on or after
                     October 15, 1582.

     To set the default calendar, select on of the above for VALUE
     and make the following call.

        CALL TIMDEF ( 'SET', 'CALENDAR', VALUE )


     System
     -------

     You may set the system used for keeping time to be UTC (default)
     TDB (barycentric dynamical time) or TDT (terrestrial dynamical
     time).  Both TDB and TDT have no leapseconds.  As such the time
     elapsed between any two epochs on these calendars does not depend
     upon when leapseconds occur.

     To set the default time system, select TDT, TDB or UTC for VALUE
     and make the following call.

        CALL TIMDEF ( 'SET', 'SYSTEM', VALUE )

     Note that such a call has the side effect of setting the value
     associated with ZONE to a blank.

     Zone
     -----

     You may alter the UTC system by specifying a time zone (UTC
     offset).  For example you may specify that epochs are referred
     to Pacific Standard Time (PST --- UTC-7).  The standard
     abbreviations for U.S. time zones are recognized:

        EST   UTC-5
        EDT   UTC-4
        CST   UTC-6
        CDT   UTC-5
        MST   UTC-7
        MDT   UTC-6
        PST   UTC-8
        PDT   UTC-7

     In addition you may specify any commercial time zone by using
     "offset" notation.  This notation starts with the letters 'UTC'
     followed by a + for time zones east of Greenwich and - for
     time zones west of Greenwich.  This is followed by the number
     of hours to add or subtract from UTC.  This is optionally followed
     by a colon ':' and the number of minutes to add or subtract (based
     on the sign that follows 'UTC') to get the
     local time zone.  Thus to specify the time zone of Calcutta you
     would specify the time zone to be UTC+5:30.  To specify the
     time zone of Newfoundland use the time zone UTC-3:30.

     To set a default time zone, select one of the "built-in" U.S.
     zones or construct an offset as discussed above.  Then make the
     call

        CALL TIMDEF ( 'SET', 'ZONE', VALUE )

     If you 'GET' a 'ZONE' it will either be blank, or have the
     form 'UTC+/-HR[:MN]'

     Note that such a call has the side effect of setting the value
     associated with SYSTEM to a blank.

Examples

     Suppose you wish to modify the behavior of STR2ET so that
     it interprets unlabeled time strings as being times in
     Pacific Daylight Time and that you want the calendar to use
     to be the "Mixed" calendar.  The following two calls will
     make the desired changes to the behavior of STR2ET

         CALL TIMDEF ( 'SET', 'CALENDAR', 'MIXED' )
         CALL TIMDEF ( 'SET', 'ZONE',     'PDT'   )

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     W.L. Taber      (JPL)

Version

    SPICELIB Version 1.2.0, 26-MAY-1998 (WLT)

        The previous version did not check out and return
        when an error was detected in the if block that 
        begins with

           ELSE IF ( MYITEM .EQ. 'ZONE' ) THEN

        The routine did eventually check out and return so
        that the trace stack was maintained correctly, but
        the default time zone would be modified which was not
        the desired behavior.

    SPICELIB Version 1.1.0, 27-JUN-1997 (WLT)

        The previous version failed to check out when 
        the default value was set.

    SPICELIB Version 1.0.0, 13-NOV-1996 (WLT)
Wed Apr  5 17:47:38 2017