Time Functions

Functions Synopsis

Due to a lack of design when starting FOCUS, timer functions and time functions share the same function prefix : TIM_*(). We apologize for this mess!

The Windows environment gives the developer a bunch of time oriented functions to work with. With few functions, FOCUS sets major services at your disposal.

It's a marvelous opportunity for us to tell you that the Windows environment handles dates as times. It basically means that working with times means working with dates.

In order to maintain the necessary consistency, times and dates are now all handled through their UTC (Universal Time Coordinated) value. This makes it more convenient to distinguish the last update of a file, certainly when it comes to compare time stamps of two files that are updated at two different places, Paris and Los Angeles for example.

So we come to this bottom line : dates and times are equivalent (time type, or DateTime type for Visual FoxPro), and what's more all times are UTC values.

Therefore, we felt obliged to provide a lot of TIME functions whereas FoxPro only provides local time functions.

Please be aware that FOCUS time functions cannot operate on dates before 01-01-1970!

Notice that all local times are determined by taking into account the daylight saving setting.

Section / FoxPro / FOCUS
Local Time / UTC / Local Time / UTC
Time / TIME() / N/A / TIM_localT( TIM_time() ) / TIM_gmT( TIM_time() )
Date / DATE() / N/A / TIM_localT( TIM_time() ) / TIM_gmT( TIM_time() )

FoxPro

? DATE(), TIME()

Focus

nTime = TIM_time()
? TIM_date( nTime ), "Local time :" + TIM_localT( nTime ), ;
"UTC : " + TIM_gmT( nTime )

Time Functions

TIM_ctime(): Converts a time value retrieved via TIM_time() as a character string.

Syntax

TIM_ctime( nTime )  szTime

Parameters

nTimecurrent time with a number form.

Returns

szTimeconverted time.

Example

LOCAL nCurrentTime
nCurrentTime = TIM_time() & 807029258
? TIM_localt( nCurrentTime ) & "16:47:38"
? TIM_gmt( nCurrentTime ) & "14:47:38"
? TIM_ctime( nCurrentTime ) & "Sat Jul 29 16:47:38 1995"

TIM_FormatMilli(): Transforms a number of milliseconds in HH:MM:SS.mmm.

Syntax

TIM_FormatMilli( nMilliSeconds )  szTimeString

Parameters

nMilliSecondsnumber of milliseconds to turn into a time string.

Returns

szTimeStringconverted time.

Example

? TIM_FormatMilli( 3600000 ) & "01:00:00.000"
? TIM_FormatMilli( 24 * 60 * 60 * 1000 ) & "24:00:00.000"

TIM_FormatTimeInterval(): Converts a time interval, specified in milliseconds, to a string.

Syntax

TIM_FormatTimeInterval( n )  szInterval

Parameters

ninteger to treat as a time interval in milliseconds.

Returns

szIntervaln expressed as a displayable time string.

Example

? TIM_FormatTimeInterval(400) & "0 sec"

? TIM_FormatTimeInterval(4000) & "4 sec"

? TIM_FormatTimeInterval(4400) & "4 sec"

? TIM_FormatTimeInterval(86400) & "1 min 26 sec"

? TIM_FormatTimeInterval(86400000) & "24 hr 0 sec"

? TIM_FormatTimeInterval(86460000) & "24 hr 1 min 0 sec"

TIM_GetNumberOfDays(): Computes the days difference between two dates.

Syntax

TIM_GetNumberOfDays( dDate1,dDate2 )  nDays

Parameters

dDate1first date to consider.

dDate2second date to consider.

Returns

nDaysthe number of days between dDate1 and dDate2.

Example

? TIM_GetNumberOfDays( DATE(),{18/11/59} ) & 13872

TIM_gmt(): Converts a time value retrieved via TIM_time() to an Universal Time Coordinated (UTC).

Syntax

TIM_gmt( nTime )  szTime

Parameters

nTimecurrent time with a number form.

Returns

szTimeconverted time.

Example

LOCAL nCurrentTime
nCurrentTime = TIM_time() & 807029258
? TIM_localt( nCurrentTime ) & "16:47:38"
? TIM_gmt( nCurrentTime ) & "14:47:38"
? TIM_ctime( nCurrentTime ) & "Sat Jul 29 16:47:38 1995"

TIM_LastVersion(): Returns the file stamp of Time functions.

Remark

This function helps the developer identifying the last version of a set of functions. Sometimes the global version information of FOCUS.FLL (MIS_major() and MIS_minor()) does not help tracking down the changes in a project. Starting with version 6.0 of FOCUS.FLL, each source file has now an internal date and time stamp.

Syntax

TIM_LastVersion()  szLastVersion

Parameters

None.

Returns

szLastVersionstring identifying the last version of the functions set. The string is similar to "C:\Focus\5.0\FWTIME.C-Mon Oct 19 15:55:22 1998".

TIM_localt(): Converts a time value retrieved via TIM_time() to a local time string.

Syntax

TIM_localt( nTime )  cTime

Parameters

nTimecurrent time with a number form.

Returns

cTimeconverted time.

Example

LOCAL nCurrentTime
nCurrentTime = TIM_time() & 807029258
? TIM_localt( nCurrentTime ) & "16:47:38"
? TIM_gmt( nCurrentTime ) & "14:47:38"
? TIM_ctime( nCurrentTime ) & "Sat Jul 29 16:47:38 1995"

TIM_MakeSeconds(): Computes the number of seconds from a time string.

Syntax

TIM_MakeSeconds( cTime )  nSeconds

Parameters

cTimefirst date to consider.

Returns

nSecondsthe number of seconds expressed by cTime.

Example

? TIM_MakeSeconds( TIME() ) & 64972

TIM_MakeTime(): Computes a time value from a date.

Syntax

TIM_MakeTime( dDate,nSeconds )  nTime

Parameters

dDatedate to transform to a time value.

nSecondsoptional number of seconds to add to dDate.

Returns

nTimethe number of seconds expressed by cTime.

Example

? TIM_MakeTime( DATE(),TIM_MakeSeconds( TIME() ) ) & 879189312
? TIM_time() & Identical !!!

TIM_SetFormat(): Customizes the internal string buffer that TIM_UserTime() will use.

Comment

The TIM_SetFormat() and TIM_UserTime() are closely related to each other. The TIM_UserTime() permits to obtain a string which is capable to express a DateTime value into any suitable form. For example, given a date, it is possible to have the following returns from TIM_UserTime():"Today is Tue" or "Today is Tuesday 08 August (08/08/95)" or even "Today is Tuesday 08 August (08/08/95). This date is day 220 of the year". In fact, any form fits. It's just up the developer to mention how he wants to get the result.

By default, the internal setting is set to "%d-%m-%Y at %H:%M:%S".

In order for TIM_UserTime() to return an appropriate format, you can should use the TIM_SetFormat() function.

Syntax

TIM_SetFormat( szFormat ) szCurFormat

Parameters

szFormattime format string. By default, the internal setting is set to "%d-%m-%Y at %H:%M:%S".

Escape / Description
%a / Abbreviated weekday name
%A / Full weekday name
%b / Abbreviated month name
%B / Full month name
%c / Date and time representation appropriate for locale
%d / Day of month as decimal number (01 - 31)
%H / Hour in 24-hour format (00 - 23)
%I / Hour in 12-hour format (01 - 12)
%j / Day of year as decimal number (001 - 366)
%m / Month as decimal number (01 - 12)
%M / Minute as decimal number (00 - 59)
%p / Current locale's A.M./P.M. indicator for 12-hour clock
%S / Second as decimal number (00 - 59)
%U / Week of year as decimal number, with Sunday as first day of week (00 - 51)
%w / Weekday as decimal number (0 - 6; Sunday is 0)
%W / Week of year as decimal number, with Monday as first day of week (00 - 51)
%x / Date representation for current locale
%X / Time representation for current locale
%y / Year without century, as decimal number (00 - 99)
%Y / Year with century, as decimal number

Returns

szCurFormatthe function returns the previous setting.

Example

LOCAL nTime
nTime = TIM_time() & Let's FOCUS handle the current time
TIM_SetFormat( "Today is %a" )
? TIM_UserTime( nTime ) & "Today is Tue"
TIM_SetFormat( "Today is %A" )
? TIM_UserTime( nTime ) & "Today is Tuesday"
TIM_SetFormat( "Today is %A %d %B" )
? TIM_UserTime( nTime ) & "Today is Tuesday 08 August"
TIM_SetFormat( "Today is %A %d %B (%x)" )
? TIM_UserTime( nTime ) & "Today is Tuesday 08 August
& (08/08/95)"

TIM_SetSystemTime(): Sets the system time to an Universal Coordinated Time (UTC).

Syntax

TIM_SetSystemTime( UCTime )  lSuccess

Parameters

UCTimeuniversal coordinated time string.

Returns

lSuccess.T. if operation is successful; .F. otherwise.

The application must have system-time privilege (the SE_SYSTEMTIME_NAME privilege) for this function to succeed. This privilege is disabled by default. Use the AdjustTokenPrivileges() function to enable the privilege and again to disable it after the time has been set.

Example

* This example won't change anything as far as the system time
* is concerned. This is due to the fact that it sets the system
* time at what it was. However, you have the basic principles
* that must be used to control these settings.
LOCAL nUCTime
LOCAL cUCTime
nUCTime = TIM_time()
cUCTime = TIM_gmt( nUCTime )
? TIM_SetSystemTime( cUCTime )

TIM_SplitMilli(): Splits a number of millseconds into its basic components (HH:MM:SS.mmm).

Syntax

TIM_SplitMilli( nMilliSeconds,@nHH,@nMM,@nSS,@nm )  szTimeString

Parameters

nMilliSecondsnumber of milliseconds to split.

nHHnumber to receive the hours. Must be passed by reference.

nMMnumber to receive the minutes. Must be passed by reference.

nSSnumber to receive the seconds. Must be passed by reference.

nmnumber to receive the milliseconds. Must be passed by reference.

Returns

szTimeStringconverted time.

Example

LOCAL nHH,nMM,nSS,nm
nHH = 0
nMM = 0
nSS = 0
nm = 0
? TIM_SplitMilli( 3600000,@nHH,@nMM,@nSS,@nm ) & "01:00:00.000"
? nHH & 1
? nMM & 0
? nSS & 0
? nm & 0

TIM_ticks(): Returns the number of milliseconds since Windows was started.

Syntax

TIM_ticks()  nTicks

Parameters

None.

Returns

nTicksnumber of milliseconds elapsed since Windows was started.

TIM_time(): Gets the current time.

Syntax

TIM_time()  nTime

Parameters

None.

Returns

nTimecurrent time with a number form.

Example

See TIM_localt(), TIM_gmt(), TIM_ctime().

TIM_UserTime(): Gets a formatted string expressing a DateTime value.

Comment

In order for TIM_UserTime() to return an appropriate format, you can should use the TIM_SetFormat() function.

Syntax

TIM_UserTime( tTime )  szTime

Parameters

tTimea time value like the one returned by TIM_time().

Returns

szTimeresulting string compliant to TIM_SetFormat() setting.

Example

Time Functions

Time Functions

TIM_ctime(): Converts a time value retrieved via TIM_time() as a character string.

Syntax

Parameters

Returns

Example

TIM_FormatMilli(): Transforms a number of milliseconds in HH:MM:SS.mmm.

Syntax

Parameters

Returns

Example

See also

TIM_FormatTimeInterval(): Converts a time interval, specified in milliseconds, to a string.

Syntax

Parameters

Returns

Example

See also

TIM_GetNumberOfDays(): Computes the days difference between two dates.

Syntax

TIM_gmt(): Converts a time value retrieved via TIM_time() to an Universal Time Coordinated (UTC).

TIM_LastVersion(): Returns the file stamp of Time functions.

TIM_localt(): Converts a time value retrieved via TIM_time() to a local time string.

TIM_MakeSeconds(): Computes the number of seconds from a time string.

TIM_MakeTime(): Computes a time value from a date.

TIM_SetFormat(): Customizes the internal string buffer that TIM_UserTime() will use.

TIM_SetSystemTime(): Sets the system time to an Universal Coordinated Time (UTC).

TIM_SplitMilli(): Splits a number of millseconds into its basic components (HH:MM:SS.mmm).

TIM_ticks(): Returns the number of milliseconds since Windows was started.