On Wed, 26 Dec 2018 09:00:47 -0500, Peter Relson wrote:
>
>>I believe a programmer might reasonably expect that STCKCONV usefully return
>>whatever TIME would have returned at the instant of the STCK.
>
>A programmer would expect next to nothing due to the name of a service
>since it is not possible to define much in the way of expectations with only 8
>bytes of name.
>A programmer would read the description to understand what a service does.
>
From: IBM MVS Programming: Assembler Services Reference, Volume 2 (IAR-XCT)
Version 2 Release 3 SA23-1370-30
Chapter 107. TIME — Obtain time and date:
...
You can use the STCKCONV and CONVTOD macros to convert between
TOD-clock format and various time of day and date formats. The STCKCONV
macro converts a TOD-clock value to a time of day and date value and the
CONVTOD macro converts a time of day and date value to a TOD clock value.
...
OK. You're correct in your pedantry; it does not assert that the time output by
these services corresponds to the input values -- it guarantees only the format.
I still feel that statements such as this entice a programmer to that misbelief.
Would you be willing to see added to this description a caution such as:
Note: if the (E)TOD clock is set according to IBM's recommendation,
the times output by STCKCONV and CONVTOD do not match the input
values, but may differ according to the content of various common
control blocks.
?
What was the objective of providing these two services? Did they address
a User Requirement? Did they meet that requirement? They give correct
results only for dates before 1972, and I see little value in that.
>A programmer would wonder when they might want to use TIME and when they
>might want to use STCKCONV, and base their decision on the service
>definitions.
>The difference is between "what date/time is it" and "what is the
>date/time that a STCK value architecturally is" (which, ignoring bits
>52-63, is the number of microseconds since the start of the standard
>epoch).
>
An alternative statement might be:
If the (E)TOD clock is set according to IBM's recommendation, and the
input to STCKCONV is the result of STCK, the output of STCKCONV will
be TAI minus 10 seconds. Conversely, if the input to TODCONV is
a TAI value minus 10 seconds, the output will be the corresponding
(E)TOD value.
OK. You're right that the programmer is free to choose any epoch/origin.
Yet it would be a courtesy to state, if only as an example, what the
programmer can expect when choosing the origin recommended by IBM.
-- gil
----------------------------------------------------------------------
For IBM-MAIN subscribe / signoff / archive access instructions,
send email to lists...@listserv.ua.edu with the message: INFO IBM-MAIN
