Description

Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

The CONVTOD macro accepts a time and date value in several different formats and converts it to time-of-day (TOD) clock format. The clock format can be either the basic time-of-day (TOD) or the extended time-of-day (ETOD).

TOD — Unsigned 64-bit binary number
ETOD — Unsigned 128-bit binary number

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 input time and date formats are compatible with those returned by the STCKCONV and TIME macros.

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:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary or access register (AR)
Interrupt status:	Enabled or disabled for I/O and external interrupts
Locks:	The caller may hold locks, but is not required to hold any.
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 CONVTOD. SYSSTATE ASCENV=AR tells the system to generate code appropriate for AR mode.

Restrictions

None.

Input register information

Before issuing the CONVTOD macro, 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 access registers (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 CONVTOD macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CONVTOD.

CONVTOD

␢	One or more blanks must follow CONVTOD.

CONVVAL=`convval`	`convval`: RX-type address or register (2) - (12).

,TODVAL=`todval`	`todval`: RX-type address or register (2) - (12).
,ETODVAL=`etodval`	`etodval`: RX-type address or register (2) - (12).

,TIMETYPE=DEC	Default: TIMETYPE=DEC.
,TIMETYPE=BIN
,TIMETYPE=MIC

,DATETYPE=YYDDD
,DATETYPE=YYYYDDD	Default: DATETYPE=YYYYDDD.
,DATETYPE=DDMMYYYY
,DATETYPE=MMDDYYYY
,DATETYPE=YYYYMMDD

,OFFSET=`offset value`	`offset value`: RX-type address or register (2) - (12).
	Default: OFFSET=X'0000000F'.

Parameters

The parameters are explained as follows:

CONVVAL=convval

Specifies a 16-byte storage area in which you will enter the time and date values to be converted. The storage area must begin on a word boundary. The first two words contain the time of day and the third word contains the date in the formats specified by the TIMETYPE and DATETYPE parameters. Set the fourth word to 0 before issuing CONVTOD.

The earliest valid date is January 1, 1900, and the latest valid date is June 4, 2185, which corresponds to the end of the second epoch (the corresponding ETOD value would have a value less than x'02' in the first byte).

,TODVAL=todval

Specifies an 8-byte storage area where the TOD-clock-formatted value is to be returned. The storage area must begin on a word boundary.

,ETODVAL=etodval

Specifies a 16-byte storage area where the ETOD-clock-formatted value is to be returned. The storage area must begin on a word boundary.

Only one of either TODVAL or ETODVAL can be specified.

,TIMETYPE=DEC

,TIMETYPE=BIN

,TIMETYPE=MIC

Specifies the format of the input time value:

DEC

Unsigned packed decimal digits representing a time value in 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.
Note: HHMMSSth must be in the first word with the remainder left-justified in the second word. Set the unused part of the second word to zeros.

BIN

Unsigned 32-bit binary number representing a time value as an unsigned binary number in which the low-order bit represents 0.01 of a second. Obtain but do not use the second word.

MIC

Unsigned 64-bit binary number representing a time value in microseconds. Bit 51 represents 1 microsecond.

,DATETYPE=YYDDD

,DATETYPE=YYYYDDD

,DATETYPE=DDMMYYYY

,DATETYPE=MMDDYYYY

,DATETYPE=YYYYMMDD

Specifies the format of the input date value:

Parameter: Format of input date
YYDDD: 0CYYDDDF
YYYYDDD: 0YYYYDDD
DDMMYYYY: DDMMYYYY
MMDDYYYY: MMDDYYYY
YYYYMMDD: YYYYMMDD

Where:

0C: is the century - 00 represents 19YY, 01 represents 20YY
F: is a sign to enable the date to be unpacked
YY: is the last two digits of the year
YYYY: is the year
DDD: is the day of the year (Julian date)
DD: is the day of the month
MM: is the month of the year

,OFFSET=offset value

Specifies a 4-byte storage area containing a packed decimal number of the form 000HHMMX, where X is the sign (D for a negative number, F for a positive number). The offset value is added to the input time. The offset value is generally the difference between Greenwich Mean Time and local time but it can be any desired value. The default value is X'0000000F'.

ABEND codes

None.

Return and reason codes

The following table describes CONVTOD's return codes, their meanings, and any recommended actions you should take. Return codes are listed in hexadecimal with their decimal value shown in parentheses.

Table 1. Return Codes for the CONVTOD Macro
Return Code	Meaning and Action
00 (00)	Meaning: Successful completion. Action: None.
0C (12)	Meaning: Unsuccessful completion. CONVTOD encountered an unexpected error. Action: Record the return code and supply it to the appropriate IBM® support personnel.
10 (16)	Meaning: Unsuccessful completion. The caller's parameter list was not addressable. Action: Verify that the pointer to the parameter list contains a valid address and that CONVTOD is being invoked in a valid addressing mode.
14 (20)	Meaning: Unsuccessful completion. The time, date, or offset parameter value was not valid. Action: Verify that the input parameters have been initialized correctly. 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 time expressed as microseconds and a date expressed as month-day-year to TOD clock format using the specified offset value:

         CONVTOD CONVVAL=INAREA,TODVAL=OUTAREA,TIMETYPE=MIC,           *
              DATETYPE=MMDDYYYY,OFFSET=PLUS1
INAREA   DS  0F
         DC  X'00009047F3070000'       INPUT TIME IN MIC FORMAT
         DC  X'05171990'               INPUT DATE IN MMDDYYYY FORMAT
         DS  F'0'                      UNUSED FOURTH WORD
PLUS1    DC  X'0000100F'               +1 HOUR OFFSET VALUE
OUTAREA  DS  2F                        AREA FOR OUTPUT TOD CLOCK VALUE

Example 2

Convert a time expressed as a decimal value and a date expressed as the Julian date to TOD clock format using the specified offset value:

         CONVTOD CONVVAL=INAREA,TODVAL=OUTAREA,TIMETYPE=DEC,           *
              DATETYPE=YYDDD,OFFSET=MINUSFIV
INAREA   DS  0F
         DC  X'1045301535120000'       INPUT TIME IN DEC FORMAT
         DC  X'0090137F'               INPUT DATE IN YYDDD FORMAT
         DS  F'0'                      UNUSED FOURTH WORD
MINUSFIV DC  X'0000500D'               -5 HOUR OFFSET VALUE
OUTAREA  DS  2F                        AREA FOR OUTPUT TOD CLOCK VALUE

Example 3

Convert a time expressed as a binary value and a date expressed as year-month-day to TOD clock format using the default offset value:

         LA    3,INAREA                STORE INPUT AREA ADDRESS
         LA   11,OUTAREA               STORE OUTPUT AREA ADDRESS
         LA    6,PLIST                 STORE PARAMETER LIST ADDRESS
         CONVTOD CONVVAL=(3),TODVAL=(11),TIMETYPE=BIN,DATETYPE=YYYYMMDD*
               ,MF=(E,(6))


PLIST    CONVTOD MF=L                  GENERATE PARAMETER LIST STORAGE
INAREA   DS    0F
         DC    X'003B18F700000000'     INPUT TIME IN BIN FORMAT
         DC    X'19900517'             INPUT DATE IN YYYYMMDD FORMAT
         DS    F'0'                    UNUSED FOURTH WORD
OUTAREA  DS    2F                      AREA FOR OUTPUT TOD CLOCK VALUE