Index of Functions: A B C D E F G H I J K L M N O P Q R S T U V W X
Index Page timdef_c
Table of contents
Procedure Abstract Required_Reading Keywords Brief_I/O Detailed_Input | Detailed_Output Parameters Exceptions Files Particulars Examples | Restrictions Literature_References Author_and_Institution Version Index_Entries
#### Procedure
       timdef_c ( Time Software Defaults )

       void timdef_c ( ConstSpiceChar * action,
                       ConstSpiceChar * item,
                       SpiceInt         vallen,
                       SpiceChar      * value )
#### Abstract
       Set and retrieve the defaults associated with calendar
       input strings.
#### Required_Reading
       None.
#### Keywords
       TIME
#### 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.
       vallen     I   Length of list for output.
       value     I-O  is the value associated with the default item.
#### Detailed_Input
       action      is a word that specifies whether timdef_c 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
                                  TT
                                  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 signaled. 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 signaled.

       2)  If the `item' specified is not one the recognized items, the error
           SPICE(BADTIMEITEM) is signaled by a routine in the call tree of this
           routine.

       3)  If the value associated with a "SET" item input is not one of the
           recognized items, the error SPICE(BADDEFAULTVALUE) is signaled by a
           routine in the call tree of this routine.

       4)  If any of the `action' or `item' input string pointers are null, the
           error SPICE(NULLPOINTER) is signaled.

       5)  If any of the `action' or `item' input strings have zero length, the
           error SPICE(EMPTYSTRING) is signaled, since the input string cannot be
           converted to a Fortran-style string in this case.

       6)  If the `value' string pointer is null, the error SPICE(NULLPOINTER)
           is signaled.

       7)  If `action' is "SET" and the `value' input string has zero length, the
           error SPICE(EMPTYSTRING) is signaled, since the input string cannot be
           converted to a Fortran-style string in this case.

       8)  If `action' is "GET" and the `value' output string has length less than
           two characters, the error SPICE(STRINGTOOSHORT) is signaled, since the
           output string is too short to contain one character of output data plus
           a null terminator, and therefore it cannot be passed to the underlying
           Fortran routine.
#### Files
       None.
#### Particulars
       This routine exists to allow SPICE toolkit users to alter
       the default interpretation of time strings made by the
       routine str2et_c.

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

       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.

          timdef_c ( "SET", "CALENDAR", lenval, value );

       System
       ------

       You may set the system used for keeping time to be UTC (default)
       TDB (barycentric Dynamical Time), TDT (Terrestrial Dynamical
       Time), or TT (Terrestrial Time). TDT and TT represent the same
       time system. Both TDB and TT (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, TT, TDB or UTC for
       `value' and make the following call.

          timdef_c ( "SET", "SYSTEM", lenval, 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

          timdef_c ( "SET", "ZONE", lenval, 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
       The numerical results shown for these examples 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) Retrieve the current settings for calendar, system and zone
          parameters of the time subsystem calendar string processing.

          Example code begins here.

          /.
             Program timdef_ex1
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local constants.
             ./
             #define        MAXLEN        40

             ConstSpiceChar        * item   [ 3 ] = { "CALENDAR",
                                                      "SYSTEM",
                                                      "ZONE"    };

             /.
             Local variables.
             ./
             SpiceChar               value  [ MAXLEN ];
             SpiceInt                i;

             for ( i = 0;  i < 3;  i++ )
             {

                /.
                Get the value for the current `item'
                ./
                timdef_c( "GET", item[i], MAXLEN, value );
                printf ( "%s -> %s\n", item[i], value    );

             }

             return ( 0 );
          }

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

          CALENDAR -> GREGORIAN
          SYSTEM -> UTC
          ZONE ->

       2) Suppose you wish to modify the behavior of str2et_c 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.

          Example code begins here.

          /.
             Program timdef_ex2
          ./
          #include <stdio.h>
          #include "SpiceUsr.h"

          int main( )
          {

             /.
             Local constants.
             ./
             #define        MAXLEN        40

             ConstSpiceChar        * item   [ 3 ] = { "CALENDAR",
                                                      "SYSTEM",
                                                      "ZONE"    };

             /.
             Local variables.
             ./
             SpiceChar               value  [ MAXLEN ];
             SpiceInt                i;

             /.
             Retrieve the initial values.
             ./
             printf ( "Initial values:\n" );
             for ( i = 0;  i < 3;  i++ )
             {

                /.
                Get the value for the current `item'
                ./
                timdef_c( "GET", item[i], MAXLEN, value );
                printf ( "   %s -> %s\n", item[i], value    );

             }

             /.
             Apply the required changes.
             ./
             timdef_c ( "SET", "CALENDAR", MAXLEN, "MIXED" );
             timdef_c ( "SET", "ZONE"    , MAXLEN, "PDT"   );

             /.
             Retrieve the final values.
             ./
             printf ( "Final values:\n" );
             for ( i = 0;  i < 3;  i++ )
             {

                /.
                Get the value for the current `item'
                ./
                timdef_c( "GET", item[i], MAXLEN, value );
                printf ( "   %s -> %s\n", item[i], value    );

             }

             return ( 0 );
          }

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

          Initial values:
             CALENDAR -> GREGORIAN
             SYSTEM -> UTC
             ZONE ->
          Final values:
             CALENDAR -> MIXED
             SYSTEM ->
             ZONE -> UTC-7
#### Restrictions
       None.
#### Literature_References
       None.
#### Author_and_Institution
       N.J. Bachman        (JPL)
       J. Diaz del Rio     (ODC Space)
       E.D. Wright         (JPL)
#### Version
       -CSPICE Version 1.1.0, 05-JUL-2021 (EDW) (JDR)

           Changed the input argument name "lenout" to "vallen" for consistency
           with other routines.

           Fixed bug: Added missing "else" block to signal the corresponding error
           when the input action is not "GET" or "SET".

           Added time system name "TT" (Terrestrial Time) as alternate
           assignment of "TDT" (Terrestrial Dynamical Time).

           Edited the header to comply with NAIF standard. Added complete code
           examples. Added entries #4 to #8 in -Exceptions section.

       -CSPICE Version 1.0.1, 13-APR-2000 (NJB)

           Made some minor updates and corrections in the header comments.

       -CSPICE Version 1.0.0, 04-FEB-1998 (EDW)
#### Index_Entries
       Change time software defaults.
       Time Zones
       Gregorian and Julian Calendars
#### Link to routine timdef_c source file timdef_c.c

    Fri Dec 31 18:41:14 2021