Description

The STCKCONV macro converts an input time-of-day (TOD) clock value to time of day and date, and returns the converted values to the caller in the format requested. The input clock value can be either the basic time-of-day (TOD) format or the extended time-of-day (ETOD) format.

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

The STCKCONV time of day and date formats are compatible with the formats returned by the TIME macro, which returns a time of day and date value or the contents of the TOD clock. The STCKCONV time of day and date formats are also compatible with the input formats accepted by the CONVTOD macro, which converts a time of day and date value to TOD clock format.

Parent topic: STCKCONV — Store clock conversion routine

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: 24-bit or 31-bit addressing mode
ASC mode: Primary or access register (AR)
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No requirement
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 STCKCONV. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.

Restrictions

None.

Input register information

Primary-mode callers must make sure that access register 1 is zero before issuing the execute form of the STCKCONV macro. For other registers, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

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 standard form of the STCKCONV macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede STCKCONV.
   
STCKCONV  
   
␢ One or more blanks must follow STCKCONV.
   
STCKVAL=TOD clock addr TOD clock addr: RX-type address or register (2) - (12).
STCKEVAL=ETOD clock addr ETOD clock addr: RX-type address or register (2) - (12).
   
,CONVVAL=conv addr conv addr: RX-type address or register (2) - (12).
   

    ,TIMETYPE=DEC
    ,TIMETYPE=BIN
    ,TIMETYPE=MIC

 Default: TIMETYPE=DEC
   

    ,DATETYPE=YYYYDDD
    ,DATETYPE=DDMMYYYY
    ,DATETYPE=MMDDYYYY
    ,DATETYPE=YYYYMMDD

 Default: DATETYPE=YYYYDDD
   

Parameters

The parameters are explained as follows:

STCKVAL=TOD clock addr
Specifies the address of an 8-byte storage area containing the 64-bit TOD clock value to be converted.
STCKEVAL=ETOD clock addr
Specifies the address of a 16-byte storage area containing the 128-bit ETOD clock value to be converted. Only values with the first byte less than x'02' (that is, values before the end of the second epoch) can be converted successfully.

Only one of STCLVAL or STCKEVAL can be specified.

,CONVVAL=conv addr
Specifies the address of a 16-byte storage area where the system returns the converted value in the requested format. The first two words contain the time of day and the third word contains the date. Do not use the contents of the fourth word.
,TIMETYPE=DEC
,TIMETYPE=BIN
,TIMETYPE=MIC
Specifies the format in which the converted time of day is returned, as follows:
DEC
Returns the converted time of day as packed decimal digits (without a sign) of the form HHMMSSthmiju0000, where
HH
is hours, based on a 24-hour clock
MM
is minutes
SS
is seconds
t
is tenths of a second
h
is hundredths of a second
m
is milliseconds
i
is ten-thousandths of a second
j
is hundred-thousandths of a second
u
is microseconds
BIN
Returns the converted time of day as an unsigned 32-bit binary number with the low-order bit equivalent to 0.01 second. The second word of the converted time value is zero.
MIC
Returns the converted time of day in microseconds as 8 bytes of information, where bit 51 is equivalent to one microsecond.
,DATETYPE=YYYYDDD
,DATETYPE=DDMMYYYY
,DATETYPE=MMDDYYYY
,DATETYPE=YYYYMMDD
Specifies the format in which the converted date is returned, as follows:
Parameter
Form of returned date
YYYYDDD
0YYYYDDD
DDMMYYYY
DDMMYYYY
MMDDYYYY
MMDDYYYY
YYYYMMDD
YYYYMMDD
The date is returned as 4 bytes of packed decimal digits (without a sign), where:
YYYY
is the year
DDD
is the day of the year
DD
is the day of the month
MM
is the month of the year

ABEND codes

None.

Return codes

When STCKCONV macro returns control to your program, GPR 15 contains a return code.

Table 1. Return Codes for the STCKCONV Macro
Hexadecimal Return Code Meaning and Action
0 Meaning: Successful completion.

Action: None.
C Meaning: System error.

Action: Retry the request.
10 Meaning: Program error. The user's parameter list is not in addressable storage.

Action: Ensure that the parameter list address is valid and the storage is addressable.
14 Meaning: Unsuccessful completion. The ETOD value was not valid.

Action: Avoid specifying a date or time that occurs after the second epoch (the corresponding ETOD value would have a value greater than x'01' in the first byte).

Example 1

Convert a TOD clock value to time of day in decimal digits, and date in month-day-year format. 
         STCKCONV STCKVAL=TODSTAMP,CONVVAL=OUTAREA,TIMETYPE=DEC,        X
               DATETYPE=MMDDYYYY
TODSTAMP DC X'A0569832F1241000'     TOD CLOCK VALUE
OUTAREA  DS CL16                    CONVERTED VALUE

Example 2

Convert a TOD clock value to time of day in hundredths of seconds, and date in year-month-day format. 
         STCK TODCLOCK
         STCKCONV STCKVAL=TODCLOCK,CONVVAL=OUTVAL,TIMETYPE=BIN,         X
               DATETYPE=YYYYMMDD
TODCLOCK DS XL8       TOD CLOCK VALUE
OUTVAL   DS CL16      CONVERTED VALUE