Setting the z/OS TOD clock

The z/OS® time-of-day (TOD) clock setting is critical to the integrity of the IMS log. The TOD clock is also critical to the proper functioning of IMS restart, data sharing and XRF tracking and takeover.

Recommendations: Use one of the following procedures:

Use an External Time Reference (ETR) device. Be sure to set it to use Universal Coordinated Time (also known as Greenwich Mean Time) with the appropriate offset for your local time zone.
Set the z/OS TOD clock during IPL using Universal Coordinated Time, then set the local time.

Attention: During IPL, do not set the TOD clock to a time and date earlier than the immediate prior shutdown or failure. Setting the TOD clock back has severe IMS database integrity and recovery implications. If you do set the TOD clock back, you must reallocate the OLDSs using a different block size, reinitialize the DBRC RECON data sets, take image copies of all DBDSs, and cold start IMS.

Considerations for setting local time

Set your system's time zone offset (the difference between local time and Universal Coordinated Time (UTC)) to an integer multiple of 15 minutes. This is consistent with world time zone definitions and ensures that the local time reported by IMS matches the local time reported by the operating system.

IMS will function properly even if the time zone offset is not a multiple of 15 minutes. However, due to the way IMS stores time values internally, not following this recommendation might result in IMS reporting a local time that is inconsistent with the local time reported by the operating system.

More about IMS time stamps and setting the time zone offset

IMS stores all date/time stamps internally as 12 bytes in the following packed-decimal format:

YYYYDDDF HHMMSSth mijuAQQ$

The date and time fields (YYYYDDDF and HHMSSthmiju) are in Universal Coordinated Time (UTC). The A field consists of 4 bits of flags used internally by IMS. The QQ$ field contains the signed packed-decimal local time zone offset for when the time stamp was created. To get the local time, IMS adds the time zone offset—stored in quarter hours (fifteen-minute intervals)—to the UTC stamp. For example, the time stamp:

2000353F 06420588 4242032D

represents the UTC date and time of:

06:42:05.884242 on day 353 of 2000 (December 18th)

The QQ$ field of this time stamp is 32D, which represents a local time zone offset of minus 32 quarter hours (or minus 8 hours west of Greenwich). Thus, the local time represented by this time stamp is:

22:42:05.884242 on day 352 of 2000 (December 17th)

This format allows IMS internal time stamps to encode both the UTC time (to provide an always-incrementing time that is not subject to daylight savings time changes), and local time (to determine the “wall-clock” time for when the time stamp was generated). If your time zone offset is set to a multiple of fifteen minutes, IMS can accurately use the offset to convert from the UTC stored in the 12-byte time stamp into the local time.

In this example, the local time will be consistent with the time reported by the operating system. However, if your time zone offset is not set to a multiple of fifteen minutes, the local time derived from this conversion will not be consistent with the time reported by the operating system.

In the following example, the time zone offset is set to +01:55 (one hour and fifty-five minutes east of Greenwich). A time stamp is generated at 15:00:00.000000 UTC time (16:55:00.000000 local time, using the current time zone offset setting). IMS will construct an internal time stamp of:

2001240F 15000000 0000008C

The encoded time zone offset is 8C, or +8 quarter hours (2 hours). Because IMS cannot store a time zone offset with a precision greater than fifteen minutes, it rounds to the nearest fifteen minute boundary.

When this time stamp is converted back into local time, IMS reports a time of 17:00:00.000000, not 16:55:00.000000. This does not cause problems for IMS, which uses the more accurate UTC form of the time stamp internally. However, you will notice this rounding effect when you compare IMS-generated local times to the current operating system time. For example, if you issue an IMS checkpoint command on the system described above, the DFS058I message will indicate two different times, as shown below:

16:55:00 DFS058I 17:00:00 CHECKPOINT COMMAND IN PROGRESS

The first time value (16:55) is returned by the operating system; this value is generated by using the z/OS time zone offset of +01:55. The second time value (17:00) is returned by IMS; this value is generated from an internal IMS time stamp that uses a time zone offset of +08 quarter hours (2 hours).

This behavior may also be encountered by application programs that compare the local time stamp in the I/O PCB with the value returned from the z/OS TIME macro. The I/O PCB local time represents the time when the message was received by IMS. The data in this time field is derived from an internal IMS 12-byte time stamp stored with the message.

In the following example, a message is received by IMS at 12:42 UTC on the system described above. The local time is 14:37, based on the z/OS time zone offset of +01:55. However, the time presented to the application by IMS in the I/O PCB local time field is 14:42, due to the rounding of the time zone offset.

Now, suppose the message is scheduled at 12:43 UTC, one minute after it arrived. If the application program issues a z/OS TIME macro request, it will receive back a local time of 14:38. If the application were to compare this time to the I/O PCB time, it would appear as if the message was being processed before it was enqueued (enqueue time = 14:42; process time = 14:38). This is only a problem for an application program if it compares the I/O PCB time to a time generated from an operating system time service.