Materialize Time of Day Clock Attributes (MATTODAT)

Bound program access
Built-in number for MATTODAT is 666. MATTODAT ( materialization_template : address attribute_selection : unsigned binary(4) ) : signed binary(4) /* result */

Description

The time-of-day clock attribute specified by attribute selection for the current system is materialized as specified in the materialization template. Upon successful completion, result is set to binary 0.

The materialization template must be 16-byte aligned. If not, the EFAULT error is returned in result. The materialization template has the following format:

Offset
Dec	Hex	Field Name		Data Type and Length
0	0	Template size		Char(8)
0	0		Number of bytes provided by the user		Bin(4)
4	4		Number of bytes available for materialization		Bin(4)
8	8	Attribute specifications as defined by the attribute selection operand		Char(*)
*	*	--- End ---

The first 4 bytes of the materialization template identify the total number of bytes provided by the user for use by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the ENOSPC error to be returned in result.

The second 4 bytes of the materialization template identify the total number of bytes available for materialization. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested for materialization, then the excess bytes are unchanged. No errors (other than the ENOSPC error described previously) are returned in the event that the receiver contains insufficient area for the materialization.

A summary of the allowable values for attribute selection follows. If an invalid attribute selection value is specified, the EINVAL error number is returned in result.

Table 1. MATTODAT selection values

Selection value	Description	Page
1	Time-of-day clock as Coordinated Universal Time (UTC)	"1 = Time-of-day clock as Coordinated Universal Time (UTC)"
2	Time-of-day clock adjustment	"2 = Time-of-day clock adjustment"

1 = Time-of-day clock as Coordinated Universal Time (UTC)

Offset
Dec	Hex	Field Name	Data Type and Length
8	8	Reserved (binary 0)	Char(8)
16	10	Time of day	Char(8)
24	18	Time zone offset	Bin(4)
28	1C	Year offset	Bin(4)
32	20	--- End ---

Time of day is the time value of the time-of-day clock which is returned as the Coordinated Universal Time (UTC) for the system. The uniqueness bits contain a combination of binary 1s and 0s thereby providing a time value that is unique for the system. See Standard Time Format for a detailed description of the format for a time value.

Time zone offset is a signed integer which is the difference between UTC and the local time for the system, including any adjustment for Daylight Saving Time, as measured in minutes of time westward from Greenwich, England.

Year offset is a signed integer which is the difference, measured in years, between the UTC calendar year and the calendar year of local time for the system when in a non-Gregorian calendar. Year offset is binary 0 when local time for the system is in the Gregorian calendar year. When the local time for the system is in a non-Gregorian calendar year, then year offset is a positive value when the non-Gregorian calendar year is greater than the UTC calendar year.

Unpredictable results occur if the time-of-day clock is materialized before it is set.

See Time-of-Day (TOD) Clock for detailed descriptions of the time-of-day clock, UTC, time zone offset, year offset, and local time.

2 = Time-of-day clock adjustment

Offset

Dec

Hex

Field Name

Data Type and Length

Adjustment options

Char(2)

Adjustment status

Bit 0

0 =	Time-of-day clock adjustment not active
1 =	Time-of-day clock adjustment active

Adjustment direction

Bit 1

0 =	Increase time of day
1 =	Decrease time of day

Reserved (binary 0)

Bits 2-15

Reserved (binary 0)

Char(6)

Time interval

Char(8)

Adjustment duration

Char(8)

--- End ---

Time-of-day clock adjustment is not supported on all hardware levels. If time-of-day clock adjustment is not supported, then the ENOTSUP error is returned in result.

Adjustment status indicates whether or not a time-of-day clock adjustment is active for the system. When the adjustment status is binary 0, then a time-of-day clock adjustment is not active and the adjustment direction, time interval, and adjustment duration fields will be set to binary 0. When the adjustment status is binary 1, then a time-of-day clock adjustment is active and the adjustment direction, time interval, and adjustment duration fields will indicate the status of the active adjustment.

Adjustment direction indicates the direction of the time-of-day clock adjustment for the system. When the adjustment direction is binary 0, the rate at which the time-of-day clock runs is increased until the adjustment is completed. When the adjustment direction is binary 1, the rate at which the time-of-day clock runs is decreased until the adjustment is completed.

Time interval is a time value which specifies the remaining amount of time by which the time-of-day clock will be increased or decreased. See Standard Time Format for a detailed description of the format for a time value.

Adjustment duration is a time value which provides an estimate of the amount of time required in order to complete the time-of-day clock adjustment. See Standard Time Format for a detailed description of the format for a time value.

An active time-of-day clock adjustment results in small adjustments to the time of day such that upon completion of the adjustment the time of day has increased or decreased by the amount specified in the time interval field. If the adjustment is to increase the time of day, the adjustment is made by increasing the rate at which the time-of-day clock is incremented. To decrease the time of day, the time-of-day clock is incremented more slowly than normal. When the adjustment has been completed, the rate at which the time-of-day clock is incremented returns to normal. The time of day continues to be a monotonically increasing value while an adjustment is active.

A time-of-day clock adjustment will remain active until completed unless one of the following occur: