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.
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.
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'.
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
MacroReturn 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
|