Materialize Time of Day Clock Attributes (MATTODAT)

Instruction Syntax

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
8 8 Adjustment options Char(2)

8

8

  • Adjustment status

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

  • Bit 0

8

8

  • Adjustment direction

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

  • Bit 1

8 8
  • Reserved (binary 0)
  • Bits 2-15
10 A Reserved (binary 0) Char(6)
16 10 Time interval Char(8)
24 18 Adjustment duration Char(8)

32

20

--- 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:

  • A new time-of-day clock adjustment is started for the system
  • The time-of-day clock for the system is modified
  • The system is powered off.

Authorization Required

  • None

Lock Enforcement

  • None

Error Conditions

The result will be set to one of the following:

EFAULT
3408 - The address used for an argument was not correct.
The template was not aligned on the required boundary or the storage was inaccessible.
EINVAL
3021 - The value specified for the argument is not correct.
ENOSPC
3404 - No space available.
ENOTSUP
3440 - Operation not supported.
Time-of-day clock adjustment is not supported for all hardware levels.

Exceptions

  • 24 Pointer Specification
    • 2401 Pointer Does Not Exist
    • 2402 Pointer Type Invalid
  • 32 Scalar Specification
    • 3203 Scalar Value Invalid