55 Time Functions



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 )

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

Syntax

TIM_ctime( nTime ) ⎝ szTime

Parameters

nTime current time with a number form.

Returns

szTime converted 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

nMilliSeconds number of milliseconds to turn into a time string.

Returns

szTimeString converted time.

Example

? TIM_FormatMilli( 3600000 ) && "01:00:00.000"

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

See also

TIM_FormatTimeInterval().

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

Syntax

TIM_FormatTimeInterval( n ) ⎝ szInterval

Parameters

n integer to treat as a time interval in milliseconds.

Returns

szInterval n 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"

See also

TIM_FormatMilli().

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

Syntax

TIM_GetNumberOfDays( dDate1,dDate2 ) ⎝ nDays

Parameters

dDate1 first date to consider.

dDate2 second date to consider.

Returns

nDays the 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

nTime current time with a number form.

Returns

szTime converted 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

szLastVersion string 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

nTime current time with a number form.

Returns

cTime converted 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

cTime first date to consider.

Returns

nSeconds the 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

dDate date to transform to a time value.

nSeconds optional number of seconds to add to dDate.

Returns

nTime the 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

szFormat time 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

szCurFormat the 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

UCTime universal 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

nMilliSeconds number of milliseconds to split.

nHH number to receive the hours. Must be passed by reference.

nMM number to receive the minutes. Must be passed by reference.

nSS number to receive the seconds. Must be passed by reference.

nm number to receive the milliseconds. Must be passed by reference.

Returns

szTimeString converted 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

nTicks number of milliseconds elapsed since Windows was started.

TIM_time() : Gets the current time.

Syntax

TIM_time() ⎝ nTime

Parameters

None.

Returns

nTime current time with a number form.

Example

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

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

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.

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

Syntax

TIM_UserTime( tTime ) ⎝ szTime

Parameters

tTime a time value like the one returned by TIM_time().

Returns

szTime resulting string compliant to TIM_SetFormat() 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)"

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download