Table of contents
CSPICE_TIMDEF sets or returns the current settings for the
time subsystem calendar string processing.
Given:
action a word that specifies whether cspice_timdef sets the value
associated with `item' or retrieves the value associated with
`item'.
help, action
STRING = Scalar
The allowed values for `action' are 'SET' and 'GET'. The
routine is not sensitive to the case of the letters in `action'.
item the default items whose value should be set or retrieved.
help, item
STRING = Scalar
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'.
help, value
STRING = Scalar
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.
the call:
cspice_timdef, action, item, value
returns:
value if the action is 'GET' then `value' will be the value associated
with the requested `item'.
help, value
STRING = Scalar
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.
Any numerical results shown for these examples may differ between
platforms as the results depend on the SPICE kernels used as input
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.
PRO timdef_ex1
ITEMS = [ 'CALENDAR', 'SYSTEM', 'ZONE' ]
;;
;; As value is a read/write Icy variable, it requires
;; definition prior to the call regardless of whether
;; use is input or output.
;;
value = ''
for i = 0, 2 do begin
cspice_timdef, 'GET', ITEMS[i], value
print, ITEMS[i] + ' -> ' + value
endfor
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
CALENDAR -> GREGORIAN
SYSTEM -> UTC
ZONE ->
2) Set the calendar parameter of the time system calendar string
processing to 'MIXED' mode.
Example code begins here.
PRO timdef_ex2
;;
;; Local constants.
;;
ITEM = 'CALENDAR'
;;
;; Retrieve the current value for the calendar parameter.
;;
current = ''
cspice_timdef, 'GET', ITEM, current
print, 'Initial value:'
print, ' ', ITEM + ' -> ' + current
;;
;; Set the calendar to 'MIXED'
;;
VALUE = 'MIXED'
cspice_timdef, 'SET', ITEM, VALUE
;;
;; Verify that the calendar parameter is currently set
;; to 'MIXED'
;;
final = ''
cspice_timdef, 'GET', ITEM, final
print, 'Final value:'
print, ' ', ITEM + ' -> ' + final
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Initial value:
CALENDAR -> GREGORIAN
Final value:
CALENDAR -> MIXED
This routine exists to allow SPICE toolkit users to alter
the default interpretation of time strings made by the
routine cspice_str2et.
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 cspice_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.
cspice_timdef, 'SET', 'CALENDAR', 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.
cspice_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
cspice_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.
1) If the `action' specified is not 'SET' or 'GET', the error
SPICE(BADACTION) is signaled by a routine in the call tree of
this routine.
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 input arguments, `action', `item' or `value', is
undefined, an error is signaled by the IDL error handling
system.
5) If any of the input arguments, `action', `item' or `value', is
not of the expected type, or it does not have the expected
dimensions and size, an error is signaled by the Icy
interface.
None.
None.
ICY.REQ
TIME.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.1.0, 10-AUG-2021 (JDR)
Added time system name 'TT' (Terrestrial Time) as alternate
assignment of 'TDT' (Terrestrial Dynamical Time).
Edited the header to comply with NAIF standard. Added example's
problem statement and reformatted example's output.
Added additional information to the argument descriptions in the
-I/O section.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections, and
completed -Particulars section.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
Change time software defaults.
Time Zones
Gregorian and Julian Calendars
|