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
`A`	`AM/PM.`
`a`	`am/pm.`
`h`	Hour of day `(1-12)`.
`hh`	Hour of day with leading zero `(01-12)`.
`H`	Hour of day `(0-23)`.
`HH`	Hour of day with leading zero `(00-23)`.
`m`	Minutes `(0-59)`.
`mm`	Minutes with leading zero `(00-59)`.
`s`	Seconds `(0-59)`.
`ss`	Seconds with leading zero `(00-59)`.
`f, ff, fff`	Fractional seconds to 1, 2, or 3 decimal places.
`z`	Time zone indicator `(-7, +8)`.
`zz`	Time zone indicator `(-0700)`.
`zzz`	Time zone indicator `(-7:00)`.

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:

CODE

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.

CODE

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.