TIME1.

A brief history of OpenVMS Timekeeping, please?

The modified Julian date adopted by the Smithsonian Astrophysical Observatory (SAO) for satellite tracking is Julian Day 2400000.5, which turns out to be midnight on November 17, 1858.

SAO started tracking satellites with an 8K (nonvirtual) 36-bit IBM 704 in 1957 when Sputnik went into orbit. The Julian day was 2435839 on January 1, 1957. This is 11225377 octal, which was too big to fit into an 18-bit field. With only 8K of memory, the 14 bits left over by keeping the Julian date in its own 36-bit word would have been wasted. SAO also needed the fraction of the current day (for which 18 bits gave enough accuracy), so it was decided to keep the number of days in the left 18 bits and the fraction of a day in the right 18 bits of one word.

Eighteen bits allows the truncated Julian day (the SAO day) to grow as large as 262143, which from November 17, 1858, allowed for 7 centuries. Possibly, the date could only grow as large as 131071 (using 17 bits), but this still covers 3 centuries and leaves the possibility of representing negative time. The 1858 date preceded the oldest star catalogue in use at SAO, which also avoided having to use negative time in any of the satellite tracking calculations.

The original Julian Day (JD) is used by astronomers and expressed in days since noon January 1, 4713 B.C. This measure of time was introduced by Joseph Scaliger in the 16th century. It is named in honor of his father, Julius Caesar Scaliger (note that this Julian Day is different from the Julian calendar that is named for the Roman Emperor Julius Caesar!).

Why 4713 BC? Scaliger traced three time cycles and found that they were all in the first year of their cyle in 4713 B.C. The three cycles are 15, 19, and 28 years long. By multiplying these three numbers (15 * 19 * 28 = 7980), he was able to represent any date from 4713 B.C. through 3267 A.D.

The starting year was before any historical event known to him. In fact, the Jewish calendar marks the start of the world as 3761 B.C. Today his numbering scheme is still used by astronomers to avoid the difficulties of converting the months of different calendars in use during different eras.

The following web sites:

    http://www.openvms.compaq.com/openvms/products/year-2000/leap.html

    http://www.eecis.udel.edu/~ntp/
    http://www.nist.gov/
    http://www.bldrdoc.gov/timefreq/faq/faq.htm
    http://www.boulder.nist.gov/timefreq/
    http://www.tondering.dk/claus/calendar.html

					[Stephen Hoffman, Dale Dellutri]

How does OpenVMS VAX maintain system time?

The VAX hardware clock is called the TOY ("Time Of Year") clock. The register associated with the clock is called the TODR ("Time Of Day Register").

The TOY clock - as used - stores time relative to January first of the current year, starting at at 00:00:00.00. It is a 100 Hz, 32-bit counter, incremented every 10ms, and thus has a capacity of circa 497 days.

OpenVMS (on the VAX platform) stores system date information - and in particular, the current year - in the system image, SYS$SYSTEM:SYS.EXE.

The TOY is used, in conjunction with the base date that is stored and retrieved from the system image, to initialize the interval clock value that is stored in EXE$GQ_SYSTIME.

Once the interval clock is loaded, the system does not typically reference the TOY again, unless a SET TIME (with no parameters) is issued. The interval clock value is updated by a periodic IPL22 or IPL24 (depending on the specific implementation) interrupt. (When these interrupts are blocked as a result of the activity of higher-IPL code - such as extensive driver interrupt activity or a hardware error or a correctable (soft) memory error - the clock will "lose" time, and the time value reported to the user with appear to have slowed down.)

On most (all?) VAX systems, the battery that is associated with the TOY clock can be disconnected and replaced if (when) it fails - TOY clock problems in VAX systems do regularly get tracked back to a failed nicad or lithium battery pack.

					[Stephen Hoffman]

Why does my system time drift?

When clock interrupts are blocked as a result of the activity of high-IPL code - such as extensive driver interrupt activity or a hardware error or a correctable (soft) memory error - the clock will "lose" time, and the time value reported to the user with appear to have slowed down. Correctable memory errors can be a common cause of system time loss, in other words.

Clock drift can also be (deliberately) caused by the activity of the DTSS or NTP packages.

Also see ALPHA17, VAX8, and TIME8.

Managing Timezones, Timekeeping, UTC, and Daylight Savings?

    SYS$MANAGER:UTC$TIME_SETUP.COM 

Please do NOT directly invoke the following command procedures:

    SYS$MANAGER:UTC$CONFIGURE_TDF.COM   ! do not directly use
    SYS$MANAGER:UTC$TIMEZONE_SETUP.COM  ! do not directly use

DECnet-Plus in V7.3 and later uses the OpenVMS TDF, UTC, and timezone support. Earlier versions use a TDF TDF mechanism, timezone database, and automatic switch-over that is internal to the DECnet-Plus package. Also on earlier versions, the TDF must be configured within the DECnet-Plus DECdtss package, in addition to the OpenVMS configuration of the TDF.

Application code using Compaq C (formerly DEC C) will use the OpenVMS UTC and TDF mechanisms when the C code is compiled on OpenVMS V7.0 and later (and when the macro _VMS_V6_SOURCE is NOT defined). Compaq C does NOT use the OpenVMS UTC and TDF mechanisms when the C code is compiled on OpenVMS releases prior to V7.0, or when the preprocessor declaration _VMS_V6_SOURCE is declared.

DCE DTSS TDF details TDB.

In OpenVMS Alpha V6.1, V6.2, and V6.2-1Hx, the TDF value is written to SYS$BASE_IMAGE.EXE. With OpenVMS Alpha V7.0 and later and with OpenVMS VAX V6.0 and later, SYS$SYSTEM:SYS$TIMEZONE.DAT contains the TDF. This means that OpenVMS Alpha systems will need to have the TDF value reset manually on reboots prior to V7.0.

During OpenVMS Bootstrap, the SYSINIT module reads SYS$TIMEZONE.DAT to acquire the TDF for use in the system global cell EXE$GQ_TDF. This is done to ensure that the system boots with a valid TDF. The UTC system services get the TDF from this cell. These services, as well as the Compaq C RTL, must have a valid TDF. (Prior to OpenVMS V7.3, if either DECnet-Plus or DECnet/VAX Extensions is configured and run, the image DTSS$SET_TIMEZONE.EXE is invoked and can override the TDF and timezone rule settings from SYSINIT or from UTC$TIME_SETUP.COM - this image runs even if DTSS is disabled. If the settings do not match, DTSS will reset the values to match its definitions.)

Prior to OpenVMS V7.3, daylight savings time switchover is handled automatically only when DCE DTSS or DECnet-Plus DTSS is in use. In V7.3, OpenVMS can be configured to automatically switch over to daylight savings time, and also generates an event that interested applications can use to detect the switch-over between standard time and daylight time.

The manual switchover between daylight savings time and standard time is correctly accomplished via the SYS$EXAMPLES:DAYLIGHT_SAVINGS.COM command procedure procedure.

If you switch the TDF or daylight savings time setting, you will also want to restart or reconfigure any time-sensitive applications (those not using the time change event in V7.3 and later). Examples of these applications include the need to restart the NFS client and (yes) NTP. (NTP will want to try to "drift" the time (see TIME6), and will find the daylight savings time switch-over to be far too large to "drift". Hence the NTP restart.) You can also use the (undocumented) TCP/IP Services (prior to V5.0) commands:

    SET TIME/DIFF=[positive or negative TDF integer]
    GENERATE TIME 

Prior to V7.3, the command:

    MCR DTSS$SET_TIMEZONE MODIFY

For information on ZIC and related tools used to manage the OpenVMS Timezone database, please see the DEC C Run-time Library Utilities Reference Manual - though the title would imply otherwise, this particular manual is part of the OpenVMS documentation set, and not part of the Compaq C (formerly DEC C) documentation set.

How to troubleshoot TDF problems on OpenVMS?

   SYS$MANAGER:UTC$TIME_SETUP.COM

The version of the application does not use the OpenVMS TDF. This includes TCP/IP Services prior to V5.0, applications using Compaq C built on or targeting OpenVMS prior to V7.0, and systems using the DECnet-Plus DTSS mechanisms prior to the release associated with OpenVMS V7.3. (DCE TDF TBD.)

If you should find either of the following two timezone-related database files located in SYS$SPECIFIC:[SYSEXE]:

     SYS$SPECIFIC:[SYSEXE]SYS$TIMEZONE.DAT
     SYS$SPECIFIC:[SYSEXE]SYS$TIMEZONE_SRC.DAT

    SYS$COMMON:[SYSEXE].

    DIRECTORY SYS$SYSTEM:SYS$TIMEZONE*.DAT

On OpenVMS versions prior to V7.3, if the file:

    SYS$STARTUP:DTSS$UTC_STARTUP.COM

    SYS$UPDATE:DTSS$INSTALL_TIMEZONE_RULE.COM

If SYS$UPDATE:DTSS$INSTALL_TIMEZONE_RULE.COM is not present on your system, then you may need to execute the following commands:

    DELETE SYS$STARTUP:DTSS$UTC_STARTUP.COM
    DEASSIGN/SYSTEM/EXEC SYS$TIMEZONE_RULE.

How can I keep the OpenVMS system time synchronized?

There exists code around that processes the digital (ie: binary) format time that is available via a modem call into the NIST clock (the Automated Computer Telephone Service (ACTS)), and code that grabs the time off a GPS receiver digital link, or a receiver (effectively a radio and a codec) that processes the time signals from radio station WWV, WWVH, WWVB, or similar. (Processing these time protocols often involves little more than reading from an EIA232 (RS232) serial line from the receiver, something that is possible from most any language as well as directly from DCL.)

One example of acquring a time-base involves the IRIG time format (IRIG-A, -B, -G), a binary signal containing the current time in hours, minutes, seconds and days since the start of the current year. IRIG can also contain the time of day as the number of seconds since midnight. Compaq Custom Systems and third-party vendors offer various IRIG-based reader/generator modules for OpenVMS systems.

Differing time servers (DECnet-Plus DTSS, DCE DTSS, NTP, etc) do not coexist particularly well, particularly if you try to use all these together on the same node. Please pick and use just one. (If needed, you can sometimes configure one package to acquire its timebase from another protocol, but one and only one time server package should have direct control over the management of and drifting of the local OpenVMS system time.)

Useful URLs:

    http://www.boulder.nist.gov/timefreq/service/nts.htm
    http://www.boulder.nist.gov/timefreq/service/acts.htm
    http://www.boulder.nist.gov/timefreq/
    http://www.time.gov/

How can I configure TCP/IP Services NTP as a time provider?

NTP has a heirarchy of layers, called strata. The further away from the actual NTP time source (Internet time servers are at stratum 1), the lower the strata (and the larger the number assigned the statum).

NTP explicity configured at stratum one provides time to NTP operating at lower strata, and the provided time is acquired based on the local system time or via some locally-accessable external time source.

NTP at other (lower) strata both receive time from higher strata and can provide time to lower strata, and automatically adjust the local stratum. The highest stratum is one, and the lowest available stratum is fifteen.

The TCP/IP Services NTP package can operate at any stratum, and can be configured as a peer, as a client, or as a broadcast server.

With TCP/IP Services V5.0 and later, the only supported reference clock is the LCL (local system clock). If your system has an excellent clock or if the system time is being controlled by some other time service (such as DTSS or GPS), you can configure NTP to use the system clock as its reference source. This will mimic the master-clock functionality, and will configre NTP as a stratum 1 time server. To do this, enter the following commands in TCPIP$NTP.CONF:

    server 127.127.1.0 prefer
    fudge 127.127.1.0 stratum 0

    server 127.127.1.0
    fudge 127.127.1.0 stratum 8

With the TCP/IP Services versions prior to V5.0, the NTP management is rather more primitive. To configure the local OpenVMS system from an NTP client to an NTP server (on TCP/IP Services versions prior to V5.0), add the following line to the SYS$SPECIFIC:[UCX$NTP]UCX$NTP.CONF file:

    master-clock 1

    SYS$SPECIFIC:[UCX$NTP]UCX$NTP.TEMPLATE

How can I drift the OpenVMS system time?

An example of the technique used (on OpenVMS VAX) to drift the system time is the SETCLOCK tool on the OpenVMS Freeware.

For information on the use of the EXE$GL_TIMEADJUST and EXE$GL_TICKLENGTH cells on OpenVMS Alpha, see OpenVMS AXP Internal and Data Structures, located on page 348.

Why does VAX need a SET TIME at least once a year?

The SET TIME command is automatically issued during various standard OpenVMS procedures such as SHUTDOWN, and it can also obviously be issued directly by a suitably privileged user. Issuing the SET TIME command resets the value stored in the TOY, and (if necessary) also updates the portion of the time (the current year) saved in the SYS.EXE system image. This VAX TOY limit is the reason why OpenVMS VAX installation kits and standalone BACKUP explicitly prompt for the time during bootstrap, and why the time value can "get weird" if the system crashes outside the 497 day window (if no SET TIME was issued to update the saved values), and why the time value can "get weird" if a different SYS$SYSTEM:SYS.EXE is used (alternate system disk, standalone BACKUP, etc).

Why can't I do a SET TIME command? Help managing DTSS.

%SET-E-NOTSET, error modifying time
-SYSTEM-F-IVSSRQ, invalid system service request

%SET-E-NOTSET, error modifying time
-SYSTEM-E-TIMENOTSET, time service enabled; enter a time service command to
update the time

The first message is displayed on systems running DECnet/OSI V6.1 and earlier. On systems with newer DECnet/OSI (DECnet-Plus) software, the second (and more informative) message is given.

You shouldn't have to change the time manually - you should be doing this through the time server - but if you insist...
you'll have to shutdown DTSS:

$ MCR NCL
NCL> DISABLE DTSS
NCL> DELETE DTSS

@SYS$STARTUP:DTSS$STARTUP

                                        [bol@adv.magwien.gv.at]

If DTSS is running and no time servers are configured, you can (and will) see the following messages at regular intervals:

%%%%%%%%%%%  OPCOM   2-SEP-1999 19:41:20.29  %%%%%%%%%%%
Message from user SYSTEM on UNHEDI
Event: Too Few Servers Detected from: Node LOCAL:.mynode DTSS,
        at: 1999-09-02-19:41:20.296-04:00Iinf
        Number Detected=0,
        Number Required=1
        eventUid   5FA70F4F-616E-11D3-A80E-08002BBEDB0F
        entityUid  DE9E97DE-6135-11D3-8004-AA000400BD1B
        streamUid  D6513A46-6135-11D3-8003-AA000400BD1B

You can also simply disable the display of these messages:

$ mcr ncl block event dispatcher outbound stream local_stream global filter -
    ((Node, DTSS), Too Few Servers Detected)

                                                  [Wayne Sewell]

  NCL> set dtss automatic TDF change = false

Details of the VAX and Alpha system time-keeping?

VAX hardware time-keeping details...

TOY clock

This is battery backed up hardware timing circuitry used to keep the correct time of year during rebooting, power failures, and system shutdown. This clock only keeps track of months, days, and time. The time is kept relative to January 1st, at 00:00:00.00 of the year the clock was initiailized.

EXE$GQ_SYSTIME

This is the OpenVMS VAX system time cell. This cell contains the number of 100ns intervals since a known reference. This cell is incremented by 100000 every 10ms by an hardware interval timer.

EXE$GQ_TODCBASE

This cell contains the time and date the system time was last adjusted by EXE$SETTIME. It uses the same format as EXE$GQ_SYSTIME. On adjustment of the system time a copy of EXE$GQ_SYSTIME is stored in this cell in both memory and on disk. This cell is used to get the year for the system time.

EXE$GL_TODR

This cell contains the time and date the system time was last adjusted by EXE$SETTIME. It uses the same format as the time of year clock. On adjustment of the system time this cell gets saved back to both memory and disk. The contents of this cell are used to test the validity of the TOY clock.

The system parameters SETTIME and TIMEPROMPTWAIT determine how the system time will be set.

  IF SETTIME = 0
  THEN the contents of the TOY clock are compared to those of EXE$GL_TODR.

        IF the TOY clock is more than a day behind EXE$GL_TODR
        THEN the TOY clock is presumed invalid.

        IF the TOY clock is within a day of EXE$GL_TODR
        THEN the system time is calculated as follows:

        EXE$GQ_SYSTIME = EXE$GQ_TODCBASE + ((TOY_CLOCK - EXE$GL_TODR) * 100000)

  IF SETTIME = 1 or the TOY clock is invalid
  THEN the value of TIMEPROMPTWAIT determines how to reset the time of year.

        IF TIMEPROMPTWAIT > 0
        THEN the user is prompted for the time and date, for a length of time
        equal to TIMEPROMPTWAIT microfortnights.

        IF TIMEPROMPTWAIT = 0
        THEN the time of year is the value of EXE$GL_TODR + 10ms.

        IF TIMEPROMPTWAIT < 0
        THEN the user is prompted for the time and date and unable to proceed
        until they enter time and date.

If either TIMEPROMPTWAIT or SETTIME are set to zero, OpenVMS VAX will use the TOY clock to get the time of year, and the year will be fetched from the CD-ROM. The value of the year on the CD-ROM media (saved in the SYS.EXE image) will most likely be that of when the CD-ROM was made, and cannot be changed. Unless the current year happens to be the same year as that on the CD-ROM, most likely the year will be off. (Further, with the calculation of Leap Year also being dependent on the current year, there is a possibility that the date could be off too.)

Alpha hardware time-keeping details...

Battery-Backed Watch (BB_WATCH) Chip

This is battery backed up hardware timing circuitry used to keep the correct time of year during rebooting, power failures, and system shutdown. This clock keeps track of date and time in 24 hour binary format.

EXE$GQ_SYSTIME

This is the OpenVMS Alpha system time cell. This cell contains the number of 100ns intervals since November 17, 1858 00:00:00.00. This cell is incremented by 100000 every 10ms by an hardware interval timer.

EXE$GQ_SAVED_HWCLOCK

This cell is used by OpenVMS Alpha to keep track of the last time and date that EXE$GQ_SYSTIME was adjusted. It keeps the same time format as EXE$GQ_SYSTIME. The value in this cell gets updated in memory and on disk, every time EXE$GQ_SYSTIME gets adjusted.

The system parameters SETTIME and TIMEPROMPTWAIT determine how the system time will be set.

  - If SETTIME = 0 then EXE$INIT_HWCLOCK reads the hardware clock to set 
    the system time.

        - IF TIMEPROMPTWAIT > 0
          THEN the value of TIMEPROMPTWAIT determines how long the user is
          prompted to enter the time and date.  If time expires and no time 
          has been entered the system acts as if TIMEPROMPTWAIT = 0.

        - IF TIMEPROMPTWAIT = 0
          THEN the system time is calculated from the contents of
          EXE$GQ_SAVED_HWCLOCK + 1.

        - IF TIMEPROMPTWAIT < 0
          THEN the user is prompted for the time and date and unable to
          continue until the information is entered.