Time functions
Overview
Data Management's Time functions extract and format time information, return the current time, and calculate time-based values.
AsTime
Attempts to interpret time as a Time value.
Syntax
AsTime( time )
AsTime( time, format_string )
The AsTime function syntax has the following arguments:
Part | Description |
---|---|
time | Required. May be of type Integer, Float, DateTime, or Text (see below). |
format_string | Required if value is of type Text. Must be a valid combination of symbols from the list below. |
Format symbol | Meaning |
---|---|
|
|
|
|
| Hour of day |
| Hour of day with leading zero |
| Hour of day |
| Hour of day with leading zero |
| Minutes |
| Minutes with leading zero |
| Seconds |
| Seconds with leading zero |
| Fractional seconds to 1, 2, or 3 decimal places. |
| Time zone indicator |
| Time zone indicator |
| Time zone indicator |
Remarks
If time is an Integer or Float, time is interpreted as a "Julian" value (seconds since midnight). If time is a DateTime, then the Time portion is extracted. If time is a Text value, the format_string argument is required.
Examples
The following all produce the same valid time results:
AsTime("15:32:01", "24HOUR")
AsTime("3:32:01pm", "12HOUR")
AsTime(15*60*60 + 32*60 + 1)
The following all produce invalid time results. You can test for valid results with IsValid.
AsTime("15:21", "12HOUR")
AsTime("Acme Software", "12HOUR")
This is the same as the TIME value, because AsTime() and Julian() are inverse of each other:
AsTime(Julian(TIME))
CurrentTime
Returns a Time that is the current system time.
Syntax
CurrentTime( )
CurrentTime has no arguments.
Remarks
The format of the returned time defaults to 24-hour time, so AsText(CurrentTime()) would return (for example) "16:43:46". However, if you assign the CurrentTime() return value to a field, it will be stored in the format of the field.
Examples
Hour(CurrentTime())
returns the current hour.CurrentTime() -- TIME
returns seconds elapsed since TIME. The elapsed seconds will be a floating-point value and may contain thousandths of a second in the fractional part.
Note that you don't need to use Julian to subtract times.
FormatTime
Formats time, using the specified format_string, and returns a text value.
Syntax
FormatTime( time, format_string )
See Configuring Date, Time, and Date-Time data types for details on format strings.
Hour
Returns an Integer in the range 0 – 23 representing the hour portion of time. For elapsed Time values, the hour may be any integer, including negative numbers.
Syntax
Hour( time )
The Hour function syntax has the following arguments:
Part | Description |
---|---|
time | Required. Must be of type Time or DateTime. |
Example
If the current time is 4:35:17PM
, then Hour(CurrentTime())
returns 16
.
The following will format the current time as (for example) "10 minutes past 6 o'clock": AsText(Minute(CurrentTime())) + " minutes past " + AsText(Hour(CurrentTime())) + " O'clock"
Julian (time)
Returns a Float that is the difference, in seconds, between time and midnight.
Syntax
Julian( time )
The required argument time must be of type Time.
Examples
Julian(CurrentTime()) / 60
returns the number of minutes since midnight.
MakeTime
Generates a Time out of explicit hour, minute, and second values. The seconds may be fractional, and precision down to thousandths is processed.
Syntax
MakeTime( hour, minute, second )
The arguments hour and minute must both be Integers; second may be a Float or Integer.
The MakeTime function syntax has the following arguments:
Part | Description |
---|---|
hour | Required. Must be Integer (normal range 0 – 23). |
minute | Required. Must be Integer (normal range 0 – 59). |
second | Required. Must be Integer (normal range 0 – 59). |
Examples
MakeTime(Hour(CurrentTime()), Minute(CurrentTime()), 0)
produces the current time, rounded back to the nearest hour.MakeTime(17, 0, 0)
produces a time of 5pm. Note the use of 24-hour time values.
Minute
Returns an Integer in the range 0 – 59 representing the Minute portion of time.
Syntax
Minute( time )
The required argument time must be of type Time or DateTime.
Example
If the current time is 3:57:12PM
, then Minute(CurrentTime())
returns 57
.
ScanTime
Converts time_text, using the specified format_string, and returns a Time.
Syntax
ScanTime( time_text, format_string )
See Configuring Date, Time, and Date-Time data types for details on format strings.
Second
Returns an Integer in the range 0 – 59 representing the Second portion of time.
Syntax
Second( time )
The required argument time must be of type Time or DateTime.
Example
If the current time is 3:57:12PM
, then Second(CurrentTime())
returns 12
.
Thousandths
Returns an Integer in the range 0 – 999 representing the Thousandths-of-Seconds portion of time.
Syntax
Thousandths( time )
The required time argument must be of type Time or DateTime.
Remarks
CurrentTime() has only a resolution of seconds. The resolution of Time values from other sources depends on the source.
Example
If the current time is 3:57:12.145PM
, then Thousandths(CurrentTime())
returns 145
.