void timdef_c ( ConstSpiceChar * action,
ConstSpiceChar * item,
SpiceInt lenout,
SpiceChar * value )
Set and retrieve the defaults associated with calendar
input strings.
None.
TIME
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
action I is the kind of action to take "SET" or "GET".
item I is the default item of interest.
lenout I Length of list for output.
value I/O is the value associated with the default item.
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
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.
lenout is the allowed length of the string when returning a
value via a "GET". The size described by lenout should
be large enough to hold any possible output plus 1.
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.
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.
None.
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.
None.
This routine exists to allow SPICE toolkit users to alter
the default interpretation of time strings made by the
routine str2et_c.
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_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", lenout, 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.
timdef_c ( "SET", "SYSTEM", lenout, 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", lenout, 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.
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. The following two calls will
make the desired changes to the behavior of str2et_c
timdef_c ( "SET", "CALENDAR", lenout, "MIXED" );
timdef_c ( "SET", "ZONE" , lenout, "PDT" );
None.
None.
W.L. Taber (JPL)
E.D. Wright (JPL)
-CSPICE Version 1.0.1, 13-APR-2000 (NJB)
Made some minor updates and corrections in the header comments.
-CSPICE Version 1.0.0, 4-FEB-1998 (EDW)
Change time software defaults.
Time Zones
Gregorian and Julian Calendars
Link to routine timdef_c source file timdef_c.c
|