1. AtacamaLargeMillimeterArray ACS Training Time System

2. Socorro, July 2004ACS Training2 Overview Based on code from the TICS timeService module Most functionality is available from standard ACS components Used to: –Obtain the current array time –Convert array time to various other representations including but not limited to ISO-8601, Universal Coordinated Time, etc. –The ability to set “timeouts” which asynchronously invoke developer code at a specific time and/or frequency –Convert native language time representations to and from OMG array time. Available natively without the use of CORBA to be fast ACS Time System does not include support for the 48ms clock based in the antennas’ hardware

3. Socorro, July 2004ACS Training3 General Terms 1.OMG Time The format of time used by the Object Management Group is based on the beginning of the Gregorian calendar. This is strictly defined as the number of one-hundred nanosecond units that have occurred since October 15, 1582 at precisely 00:00:00. For reference, the last representable date using this format is March 11, 60038. 2.Array Time The synchronized time according to all ALMA antennas??? 3.TAI TAI is short for International Atomic Time. Based on the second unit and derived from a large number of clocks all over the world. 4.UTC UTC is short for Coordinated Universal Time. Based on the second unit but unlike TAI, UTC keeps track of so-called leap seconds. Offset from TAI is always an integer number of seconds. 5.Epoch A unique instance in time. 6.Duration The difference between two epochs. 7.Clock An IDL interface designed to give users the current time. 8.Timer An IDL interface designed to execute developer code at a given time. 9.TimeoutHandler The “developer code” mentioned in 4.

4. Socorro, July 2004ACS Training4 acstime.idl An IDL file provided by ACS which contains time-related constants, data type declarations, and IDL interfaces. This IDL file can be found $ACSROOT/idl/acstime.idl on a PC where ACS has been installed (or in ACS/LGPL/CommonSoftware/acstime/ws/idl/acstime.idl from the ALMA CVS repository).

5. Socorro, July 2004ACS Training5 acstime.idl (miscellaneous) module acstime { // The time systems that have some form of ACS support. enum TimeSystem { TSArray, // array time TSTAI, // International Atomic Time (TAI) TSUTC // Universal Coordinate Time (UTC) };

6. Socorro, July 2004ACS Training6 Epoch A unique instance in (OMG) time An epoch is encoded in units of 100 nanoseconds, i.e.10^-7 seconds, since October 15, 1582 at 00:00:00. October 15, 1582 is the beginning of the Gregorian calendar. It is stored in an unsigned 64-bit integer, giving it a range of more than 58,454 years. The last representable date is around March 11, 60038. This same encoding is used by the CORBA and X/Open DCE Time Services. In IDL, an epoch unit is represented by the typedef ACS::Time (i.e., unsigned long long) embedded within a struct.

7. Socorro, July 2004ACS Training7 Epoch (IDL Definition) module acstime { struct Epoch { ACS::Time value; };

8. Socorro, July 2004ACS Training8 Duration The difference between two epochs. It is not related to any particular instant of time. A duration is encoded in units of 100 nanoseconds, i.e. 10^-7 seconds, and can be positive or negative. A Duration is stored in a signed 64-bit integer, giving it a range of more than +/- 29,227 years. This same representation is used by the CORBA and X/Open DCE Time Services. A signed value and in IDL it’s represented by the ACS::TimeInterval typedef (i.e., long long) embedded inside a struct.

9. Socorro, July 2004ACS Training9 Duration (IDL Definition) module acstime { struct Duration { ACS::TimeInterval value; };

10. Socorro, July 2004ACS Training10 Clock An IDL interface implemented as a standard component which gives users the current OMG array time. Additionally, Clock provides a few time conversion functions along with public access to the variations between array, TAI, and UTC times. Clock is normally only used as a collocated object and will normally be present on all machines (i.e. on both LCUs and general-purpose workstations).

11. Socorro, July 2004ACS Training11 Clock (IDL Definition) module acsnc { interface Clock : ACS::CharacteristicComponent { Duration getTimeInterval(in Epoch prevEpoch); readonly attribute ACS::ROuLongLong now; Epoch fromISO8601(in TimeSystem ts, in string iso) raises (ACSTimeError::ArgErrorEx); string toISO8601(in TimeSystem ts, in Epoch timeValue) raises (ACSTimeError::ArgErrorEx); };

12. Socorro, July 2004ACS Training12 Timer An IDL interface implemented as a standard component which is capable of executing developer code (i.e., timeouts) at a given instance in time. Scheduled timeouts can occur only once or periodically. Timeouts can be cancelled before they occur. The code to be invoked is passed to the Timer component via the implementation of a TimeoutHandler interface.

13. Socorro, July 2004ACS Training13 Timer (IDL Definition) module acsnc { interface Timer : ACS::ACSComponent { long schedule(in TimeoutHandler handler, in Epoch start, in Duration period) raises(ACSTimeError::ArgErrorEx); void cancel(in long id) raises(ACSTimeError::InvalidIDEx); };

14. Socorro, July 2004ACS Training14 TimoutHandler (Offshoot) An IDL interface which must be implemented by the developer to be used. Create an object of this class to receive timeout events (not to be confused with channel events). This interface provides a callback type mechanism and can really be thought of as an alarm. A reference to this CORBA object is passed as an argument to Timer’s schedule method. Other arguments to schedule are when the timeout(s) will occur and how often. TimeoutHandler defines a “handleTimeout” method which shall only be invoked by Timer components.

15. Socorro, July 2004ACS Training15 TimeoutHandler (IDL Definition) module acsnc { interface TimeoutHandler : ACS::OffShoot { void handleTimeout(in Epoch time); };

16. Socorro, July 2004ACS Training16 CORBA-less ACS Time Libraries C++: http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_docs/cpp/classTimeUtil.html http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_docs/cpp/classDurationHelper.html http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_docs/cpp/classEpochHelper.html Python: http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_docs/py/Acspy.Common.TimeHelper.html http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_docs/py/Acspy.Common.EpochHelper.html http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_docs/py/Acspy.Common.DurationHelper.html Java: http://www.eso.org/~almamgr/AlmaAcs/OnlineDocs/ACS_docs/java/classalma_1_1acs_1_1util_1_1UTCUtility.html

17. Socorro, July 2004ACS Training17 TimeoutHandler Implementations In the ALMA CVS repository, take a look at: ACS/LGPL/CommonSoftware/acstime/ws/test/testTimeout.cpp ACS/LGPL/CommonSoftware/acspyexmpl/src/acspyexmplTimeoutHandler.py ACS/LGPL/CommonSoftware/jcontexmpl/src/alma/demo/client/TimeoutHandlerClient.java These examples and tests are well documented and straightforward so unless someone wants to go over them…we’ll skip them.

18. Socorro, July 2004ACS Training18 Questions???

19. Socorro, July 2004ACS Training19 Demo(s)