TIME


>>-TIME(--+--------+--)----------------------------------------><
          '-option-'

returns the local time in the 24-hour clock format: hh:mm:ss (hours, minutes, and seconds) by default, for example, 04:41:37.

You can use the following options to obtain alternative formats, or to gain access to the elapsed-time clock. (Only the capitalized and highlighted letter is needed; all characters following it are ignored.)

Civil: returns the time in Civil format: hh:mmxx. The hours may take the values 1 through 12, and the minutes the values 00 through 59. The minutes are followed immediately by the letters am or pm. This distinguishes times in the morning (12 midnight through 11:59 a.m.—appearing as 12:00am through 11:59am) from noon and afternoon (12 noon through 11:59 p.m.—appearing as 12:00pm through 11:59pm). The hour has no leading zero. The minute field shows the current minute (rather than the nearest minute) for consistency with other TIME results.
Elapsed: returns sssssssss.uuuuuu, the number of seconds.microseconds since the elapsed-time clock (described later) was started or reset. The number has no leading zeros or blanks, and the setting of NUMERIC DIGITS does not affect the number. The fractional part always has six digits.
Hours: returns up to two characters giving the number of hours since midnight in the format: hh (no leading zeros or blanks, except for a result of 0).
Long: returns time in the format: hh:mm:ss.uuuuuu (uuuuuu is the fraction of seconds, in microseconds). The first eight characters of the result follow the same rules as for the Normal form, and the fractional part is always six digits.
Minutes: returns up to four characters giving the number of minutes since midnight in the format: mmmm (no leading zeros or blanks, except for a result of 0).
Normal: returns the time in the default format hh:mm:ss, as described previously. The hours can have the values 00 through 23, and minutes and seconds, 00 through 59. All these are always two digits. Any fractions of seconds are ignored (times are never rounded up). This is the default.
Reset: returns sssssssss.uuuuuu, the number of seconds.microseconds since the elapsed-time clock (described later) was started or reset and also resets the elapsed-time clock to zero. The number has no leading zeros or blanks, and the setting of NUMERIC DIGITS does not affect the number. The fractional part always has six digits.
Seconds: returns up to five characters giving the number of seconds since midnight in the format: sssss (no leading zeros or blanks, except for a result of 0).

Here are some examples, assuming that the time is 4:54 p.m.:

TIME()       ->   '16:54:22'
TIME('C')    ->   '4:54pm'
TIME('H')    ->   '16'
TIME('L')    ->   '16:54:22.123456'   /* Perhaps */
TIME('M')    ->   '1014'           /* 54 + 60*16 */
TIME('N')    ->   '16:54:22'
TIME('S')    ->   '60862'  /* 22 + 60*(54+60*16) */

The elapsed-time clock: You can use the TIME function to measure real (elapsed) time intervals. On the first call in a program to TIME('E') or TIME('R'), the elapsed-time clock is started, and either call returns 0. From then on, calls to TIME('E') and to TIME('R') return the elapsed time since that first call or since the last call to TIME('R').

The clock is saved across internal routine calls, which is to say that an internal routine inherits the time clock its caller started. Any timing the caller is doing is not affected, even if an internal routine resets the clock. An example of the elapsed-time clock:

time('E')    ->    0          /* The first call */
/* pause of one second here */
time('E')    ->    1.002345   /* or thereabouts */
/* pause of one second here */
time('R')    ->    2.004690   /* or thereabouts */
/* pause of one second here */
time('R')    ->    1.002345   /* or thereabouts */

Restriction: See the note under DATE about consistency of times within a single clause. The elapsed-time clock is synchronized to the other calls to TIME and DATE, so multiple calls to the elapsed-time clock in a single clause always return the same result. For the same reason, the interval between two usual TIME/DATE results may be calculated exactly using the elapsed-time clock.

Note: Starting with z/OS® V2R1, the REXX elapsed timer can tolerate a change of the local time while the elapsed timer is running.

For example, if the local time is adjusted ahead (as with a change from Standard Time to Daylight Savings Time), or backwards (as with a fall back from Daylight Savings Time to Standard Time) while a REXX program is running with an active elapsed timer, the REXX program will see no disruption to the elapsed timer and will continue to run normally, because internally the elapsed timer start time is adjusted, relative to the new local time, to produce a resultant elapsed local time that is within approximately +/- 2 seconds of the actual elapsed UTC timer. If the local time is not changed across an elapsed timer interval, the elapsed timer remains precise down to the nearest microsecond.

Implementation maximum: If the number of seconds in the elapsed time exceeds nine digits (equivalent to over 31.6 years), an error results.