Table of Contents

6.02 Time

Returns the current time in one of several different formats. Optionally, if a time is supplied in one of the supported formats, it will convert the time to another format.

Time

Description:

Time returns the current time or a supplied time in one of several different formats.

Syntax:

time([option_out [,option_in [,time ]]])

Parameters:

option_out
One of Normal, Long, UTC, Hours, Minutes, Seconds, Timestamp, Offset, Elapsed, Reset.
Note that only the first character is used. Any remaining characters are ignored. This will apply even if the word is spelled incorrectly.
option_in
One of Normal, Long, UTC, Hours, Minutes, Seconds, Timestamp.
If this option is specified, it defines the format of the time in the following parameter.
time
Time to be used as source in the format specified by option_in. If this time is omitted, option_in is ignored and the current time is used.

Return Value:

A string containing the current time depending on the option specified.

Remarks:

Where an output option only is specified the current time is converted to the that format.

If there is no option or the option is invalid, the current time is returned in the 24-hour clock format: hh:mm:ss. Midnight is returned as 00:00:00.

If an input time is specified, that time is used instead of the current time.

Normal
The local time in the format hh:mm:ss. This is the default if no option is provided or it is invalid.
Long
The time in the format: hh:mm:ss.ddd where ddd is decimal fractions of a second to three decimal places (milliseconds).
UTC
The Universal Co-ordinated Time (UTC - also known as GMT) in the format hh:mm:ss.
Hours
The number of hours since midnight.
Minutes
The number of minutes since midnight.
Seconds
The number of seconds since midnight.
Timestamp
Unix time stamp as a decimal number. This is the number of seconds since 01/01/1970 00:00:00 UTC.

The UTC offset option is used for information only and is not used as part of a time conversion.

Offset
The number of minutes between UTC time and local time. This does not include daylight saving time. For GMT this is 0, for EST is -300 and for WET is 60.

The remaining two options are used to return the elapsed time and are not used as part of a time conversion.

Elapsed
The number of seconds.microseconds since the elapsed time clock was started or reset. (See The Elapsed Time Clock below). The value is returned in the format: sssssssss.uuuuuu without leading zeros or blanks. The fractional part always has six digits.
Reset
The number of seconds.microseconds since the elapsed time clock was started or reset (See The Elapsed Time Clock below). The value is returned in the format: sssssssss.uuuuuu without leading zeros or blanks. The fractional part always has six digits. This option resets the elapsed-time clock.

The first call to date or time in one clause causes a time stamp to be made that is then used for any further calls to date or time in that clause. This means that multiple calls to either function in a single expression or clause will be consistent with each other.

Example:

Here are some examples, assuming the time is 16:54:22 on 31 August 2008:

time()    -> '16:54:22'
time('H') -> '16'
time('L') -> '16:54:22.123456' /* Perhaps */
time('M') -> '1014'            /* 54 + 60*16 */
time('N') -> '16:54:22'
time('O') -> '60'              /* Minutes between UTC time and local time */
time('S') -> '60862'           /* 22 + 60*(54 + 60*16) */
time('T') -> '1220201662'      /* Seconds since 01/01/1970 00:00:00 GMT */
time('U') -> '15:54:22'        /* Universal Co-ordinated Time (UTC or GMT) */

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'), the current system time stamp is returned. This is the number of seconds and microseconds since 01/01/1970 00:00:00 in the format ssssssssss.uuuuuu. Repeated calls to time('E') will return the current time stamp or if the counter has been reset, the current elapsed time.

Note that the actual value returned for the microseconds is system dependent and can change at less than microsecond intervals. Refer to the system documentation for the exact interval.

On the first call in a program to time('R'), the current system time stamp is returned and then the elapsed time clock is re-started. Subsequent calls to time('E') or time('R') will return the current elapsed time.

(To be implemented) The clock is saved across internal routine calls. An internal routine inherits the time clock that was started by its caller, but any timing the caller is doing is not affected, even if the clock is reset by the internal routine.

An example of the elapsed time clock in use:

time('R') → 1220201662.123450  /* The first call on 31-08-2008 */ 
  /* 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 */ 

Implementation Status:

LynPlex Interpreter
Fully implemented
LynPlexC Compiler
To be implemented
Currently there is limited support revolving around VB date serials.
LynPlexS Compiler
To be implemented
Currently there is limited support for time handling using the following Xst library functions.
XstDateAndTimeToFileTime
XstFileTimeToDateAndTime
XstGetDateAndTime
XstGetDateAndTimeFormatted
XstGetLocalDateAndTime
XstGetSystemTime
XstSetDateAndTime

See Also:


lynplex/lp0602.txt · Last modified: 2014/12/29 12:55 by don