STCKSYNC — Store clock synchronous service

Description

The STCKSYNC macro obtains the time-of-day (TOD) clock contents and indicates whether the TOD clock is synchronized with an external time reference (ETR1) or with Server Time Protocol (STP).

STCKSYNC is for use by programs that are dependent upon synchronized TOD clocks in a multisystem environment. STCKSYNC also provides an optional parameter, ETRID, that returns the network ID of the ETR source with which the TOD clock is synchronized, and, if applicable, CTNID, that returns the timing mode and the Coordinated Timing Network ID (CTN-ID) of the timing network to which the current processor is synchronized.

The time-of-day clock specified can be either the basic time-of-day clock format (TOD) or the extended time-of-day clock format (ETOD).
  • TOD — Unsigned 64-bit binary number
  • ETOD — Unsigned 128=bit binary number

See z/OS MVS Programming: Assembler Services Guide or z/Architecture® Principles of Operation for information comparing the formats of the TOD and ETOD.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key
Dispatchable unit mode: Task or SRB
Cross memory mode: PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE: 31-bit
ASC mode: Primary or access register (AR)
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: Any locks may be held, no locks required
Control parameters: Must be in the primary address space or be in an address/data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

Programming requirements

If the program is in AR mode, issue the SYSSTATE ASCENV=AR macro before STCKSYNC. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.

Restrictions

None.

Input register information

For primary ASC mode callers, GPR 13 must contain the address of a 72-byte save area. For AR mode callers, AR/GPR 13 must contain the address of a 72-byte save area.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14
Used as a work register by the system
15
Return code
When control returns to the caller, the ARs contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14-15
Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The STCKSYNC macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede STCKSYNC.
   
STCKSYNC  
   
␢ One or more blanks must follow STCKSYNC.
   
TOD =TOD clock addr TOD clock addr: RX-type address
ETOD=ETOD clock addr ETOD clock addr: RX-type address
   
    ,ETRID=ETR-id addr ETR-id addr: RX-type address
    ,CTNID=CTN-id addr CTN-id addr: RX-type address: RX-type address
   

Parameters

The parameters are explained as follows:

TOD=TOD clock addr
Specifies the address of a doubleword that receives the TOD clock value.
ETOD=ETOD clock addr
Specifies the address of a 16-byte area, aligned on a double-word boundary, that receives the extended TOD clock value (ETOD).

Only one of either TOD or ETOD can be specified.

,ETRID=ETR-id addr
Specifies the address of a byte that receives the ETR network ID of the ETR with which the TOD clock is synchronized. No ETRID value is returned if the TOD clock is not synchronized with an ETR.
,CTNID=CTN-id addr
Specifies the address of a 16–byte area that contains the timing mode and the CTN-ID of the timing network to which the current CEC is synchronized. The CTN-ID is the first 12 bytes and the timing mode is the last byte (15) of this area. If the clock is synchronized to a CTN, the timing mode is either in ETR timing mode (X'80') or STP timing mode (X'40'). If the clock is not synchronized to a CTN, the mode is local (X'00'). The CTN-ID consists of two parts, the STP-ID which is 8 characters in bytes 0 - 7 and the ETR-ID which is a hexadecimal integer value in byte 11 of the returned area. A value of X'FF' in byte 11 should be ignored. Bytes 12 to 14 are not used and will be zeros.

Only one of either TOD or ETOD can be specified.

ABEND codes

None.

Return codes

Return codes from the STCKSYNC macro are returned as hexadecimal values in register 15, as follows:

Table 1. Return Codes for the STCKSYNC Macro
Hexadecimal Return Code Meaning and Action
0 Meaning: The TOD clock is synchronized with an ETR or a CTN, or a simulated ETR was requested (through SYS1.PARMLIB member CLOCKxx). If ETRID was specified, the ID of the ETR is returned at id addr.

Action: None.
4 Meaning: The TOD clock is not synchronized with an ETR or a CTN.

Action: None required. However, you might take some action based upon your application.
8 Meaning: System error. The TOD clock is unusable.

Action: Reissue the request until it succeeds.
C Meaning: System error. Timer in the middle of a timing Mode Switch. No data is returned.

Action: Reissue the request.

Example 1

Obtain the TOD clock contents and an indication of whether the TOD clock is synchronized with an ETR. 
          STCKSYNC TOD=TODAREA
TODAREA   DS XL8                    TOD CLOCK CONTENTS

Example 2

For a caller in AR mode, obtain the TOD clock contents, an indication of whether the TOD clock is synchronized with an ETR, and the network ID of the ETR source with which the TOD clock is synchronized. 
          SYSSTATE ASCENV=AR
          .
          .
          .
          STCKSYNC TOD=TODAREA,ETRID=IDAREA
TODAREA   DS XL8            TOD CLOCK CONTENTS
IDAREA    DS XL1            ETR NET ID
1 External time reference (ETR) is the MVS™ generic name for the IBM® Sysplex Timer.