Time Manager
 

 < Home   < Developers   < Development Support   < Documentation

53 Time Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

53 Time Manager

Time Manager Data Structures

DateFormatType

DateTimeType

DateType

DaylightSavingsTypes

DayOfMonthType

TimeFormatType

TimeType

Time Manager Constants

Time Manager Functions

DateAdjust

DateDaysToDate

DateSecondsToDate

DateTemplateToAscii

DateToAscii

DateToDays

DateToDOWDMFormat

DayOfMonth

DayOfWeek

DaysInMonth

TimAdjust

TimDateTimeToSeconds

TimGetSeconds

TimGetTicks

TimSecondsToDateTime

TimSetSeconds

TimeToAscii

TimeZoneToAscii

TimTimeZoneToUTC

TimUTCToTimeZone

       

This chapter provides reference material for the time manager.

Time Manager Data Structures

Time Manager Functions

The header file DateTime.h declares the API that this chapter describes. For more information on the time manager, see the section "Time" in the Palm OS Programmer's Companion, vol. I.

Time Manager Data Structures

The time manager uses these structures to store information.

DateFormatType

The DateFormatType enum specifies the different display formats for date values.

typedef enum { 
    dfMDYWithSlashes, 
    dfDMYWithSlashes, 
    dfDMYWithDots, 
    dfDMYWithDashes, 
    dfYMDWithSlashes, 
    dfYMDWithDots, 
    dfYMDWithDashes, 
    dfMDYLongWithComma, 
    dfDMYLong, 
    dfDMYLongWithDot, 
    dfDMYLongNoDay, 
    dfDMYLongWithComma, 
    dfYMDLongWithDot, 
    dfYMDLongWithSpace, 
    dfMYMed, 
    dfMYMedNoPost, 
    dfMDYWithDashes 
} DateFormatType; 

Value Descriptions

dfMDYWithSlashes
The month, day, and year numbers separated by slashes. For example,
12/31/95.

This is considered a short format.
dfDMYWithSlashes
The day, month, and year numbers separated by slashes. For example,
31/12/95.

This is considered a short format.
dfDMYWithDots
The day, month, and year numbers separated by dots. For example, 31.12.95.

This is considered a short format.
dfDMYWithDashes
The day, month, and year numbers separated by dashes. For example,
31-12-95.

This is considered a short format.
dfYMDWithSlashes
The year, month, and day numbers separated by slashes. For example,
95/12/31.

This is considered a short format.
dfYMDWithDots
The year, month, and day numbers separated by dots. For example, 95.12.31.

This is considered a short format.
dfYMDWithDashes
The year, month, and day numbers separated by dashes. For example,
95-12-31.

This is considered a short format.
dfMDYLongWithComma
The month, day, and year in long format, with a comma. For example,
Dec 31, 1995.

This is considered a long format.
dfDMYLong
The month, day, and year in long format. For example, 31 Dec 1995.

This is considered a long format.
dfDMYLongWithDot
The month, day, and year in long format, with a dot. For example,
31. Dec 1995.

This is considered a long format.
dfDMYLongNoDay
The month and year in long format. For example, Dec 1995.

This is considered a long format.
dfDMYLongWithComma
The day, month, and year in long format, with a comma. For example,
31 Dec, 1995.

This is considered a long format.
dfYMDLongWithDot
The year, month, and day in long format with dot separators. For example, 1995.12.31.

This is considered a long format.
dfYMDLongWithSpace
The year, month, and day in long format with space separators. For example, 1995 Dec 31.

This is considered a long format.
dfMYMed
The month in long format with the two-digit year, preceded by an apostrophe. For example, Dec '95.

This is considered a medium format.
dfMYMedNoPost
The month in long format with the two-digit year. For example, Dec 95.

This is considered a medium format.
dfMDYWithDashes
The month, day, and year numbers separated by dashes. For example,
12-31-95.

This is considered a short format.

Compatibility

The dfMDYWithDashes constant is defined in Palm OS® 4.0 and higher.

DateTimeType

The DateTimeType structure represents a date and time value.

typedef struct{ 
  Int16    second; 
  Int16    minute; 
  Int16    hour; 
  Int16    day; 
  Int16    month; 
  Int16    year; 
  Int16    weekDay; 
} DateTimeType 
typedef DateTimeType 	*DateTimePtr; 

Field Descriptions

second
The number of seconds. This is a value between 0 and 59.
minute
The number of minutes. This is a value between 0 and 59.
hour
The number of hours. This is a value between 0 and 23.
day
The day number. This is a value between 1 and 31.
month
The month number. This is a value between 1 and 12.
year
The year number.
weekDay
The day number. This represents the number of days since Sunday and is thus a value between 0 and 6.

DateType

The DateType structure represents a date value.

typedef struct{ 
  UInt16 year   :7; 
  UInt16 month  :4; 
  UInt16 day    :5; 
} DateType; 
  
typedef DateType *DatePtr; 

Field Descriptions

year
The number of years since 1904.

Note that this is the format used on Macintosh computers.
month
The month number. This is a value between 1 and 12.
day
The day number. This is a value between 1 and 31.

DaylightSavingsTypes

The DaylightSavingsTypes enum specifies the different forms of daylight savings times that you can specify for date and time values.

Note that the table uses "DST" to represent daylight savings time.

typedef enum { 
    dsNone, 
    dsUSA, 
    dsAustralia, 
    dsWesternEuropean, 
    dsMiddleEuropean, 
    dsEasternEuropean, 
    dsGreatBritain, 
    dsRumania, 
    dsTurkey, 
    dsAustraliaShifted 
} DaylightSavingsTypes; 

Value Descriptions

dsNone
No DST (daylight savings time)
dsUSA
U.S.A. DST
dsAustralia
Australian DST
dsWesternEuropean
Western European DST
dsMiddleEuropean
Middle European DST
dsEasternEuropean
Eastern European DST
dsGreatBritain
Great Britain and Eire DST
dsRumania
Rumanian DST
dsTurkey
Turkish DST
dsAustraliaShifted
Australian DST, with the 1986 shift

Compatibility

If 4.0 New Feature Set is present, this data type is obsolete. In versions 4.0 and higher, Palm OS represents daylight savings time as an integer value that gives the number of minutes to add to the current time for daylight savings time.

DayOfMonthType

The DayOfMonth enum specifies the different day-of-the-week numeric values that are returned by the DayOfMonth function. These values are used to represent repeating appointments that occur on specific days of the month; for example, the first Friday or the third Tuesday of each month.

typedef enum { 
    dom1stSun, dom1stMon, dom1stTue, dom1stWen, 
      dom1stThu, dom1stFri, dom1stSat, 
    dom2ndSun, dom2ndMon, dom2ndTue, dom2ndWen, 
      dom2ndThu, dom2ndFri, dom2ndSat, 
    dom3rdSun, dom3rdMon, dom3rdTue, dom3rdWen, 
      dom3rdThu, dom3rdFri, dom3rdSat, 
    dom4thSun, dom4thMon, dom4thTue, dom4thWen, 
      dom4thThu, dom4thFri, dom4thSat, 
    domLastSun, domLastMon, domLastTue, 
      domLastWen, domLastThu, domLastFri, 
      domLastSat 
} DayOfWeekType; 

Value Descriptions

dom1stSun
The first Sunday of the month.
dom1stMon
The first Monday of the month.
dom1stTue
The first Tuesday of the month.
dom1stWen
The first Wednesday of the month.
dom1stThu
The first Thursday of the month.
dom1stFri
The first Friday of the month.
dom1stSat
The first Saturday of the month.
dom2ndSun
The second Sunday of the month.
dom2ndMon
The second Monday of the month.
dom2ndTue
The second Tuesday of the month.
dom2ndWen
The second Wednesday of the month.
dom2ndThu
The second Thursday of the month.
dom2ndFri
The second Friday of the month.
dom2ndSat
The second Saturday of the month.
dom3rdSun
The third Sunday of the month.
dom3rdMon
The third Monday of the month.
dom3rdTue
The third Tuesday of the month.
dom3rdWen
The third Wednesday of the month.
dom3rdThu
The third Thursday of the month.
dom3rdFri
The third Friday of the month.
dom3rdSat
The third Saturday of the month.
dom4thSun
The fourth Sunday of the month.
dom4thMon
The fourth Monday of the month.
dom4thTue
The fourth Tuesday of the month.
dom4thWen
The fourth Wednesday of the month.
dom4thThu
The fourth Thursday of the month.
dom4thFri
The fourth Friday of the month.
dom4thSat
The fourth Saturday of the month.
domLastSun
The last Sunday of the month.
domLastMon
The last Monday of the month.
domLastTue
The last Tuesday of the month.
domLastWen
The last Wednesday of the month.
domLastThu
The last Thursday of the month.
domLastFri
The last Friday of the month.
domLastSat
The last Saturday of the month.

Compatibility

On Palm OS versions earlier than 4.0, this type was named DayOfWeekType.

TimeFormatType

The TimeFormatType enum specifies the different display formats for time values.

typedef enum  
  { 
      tfColon, 
      tfColonAMPM, 
      tfColon24h, 
      tfDot, 
      tfDotAMPM, 
      tfDot24h, 
      tfHoursAMPM, 
      tfHours24h, 
      tfComma24h, 
  } TimeFormatType; 
typedef TimeFormatType *TimeFormatPtr; 

Value Descriptions

tfColon
The hour and minutes separated by a colon character. For example, 1:00.
tfColonAMPM
The hour and minutes separated by a colon and followed by an AM/PM indication. For example, 1:00 pm.
tfColon24h
The 24-hour time with the hour and minutes separated by a colon character. For example, 13:00.
tfDot
The hour and minutes separated by a dot character. For example, 1.00.
tfDotAMPM
The hour and minutes separated by a period and followed by an AM/PM indication. For example, 1.00 pm.
tfDot24h
The 24-hour time with the hour and minutes separated by a dot character. For example, 13.00.
tfHoursAMPM
The hour value followed by an AM/PM indication. For example, 1 pm.
tfHours24h
The 24-hour value, followed by an AM/PM indication. For example, 13.
tfComma24h
The 24-hour time with the hour and minutes separated by a comma character. For example, 13,00.

TimeType

The TimeType structure represents a time value.

typedef struct { 
  UInt8   hours; 
  UInt8   minutes; 
} TimeType; 
typedef TimeType *TimePtr; 

Field Descriptions

hours
The number of hours. This is a value between 0 and 23.
minutes
The number of minutes. This is value between 0 and 59.

Time Manager Constants

The following table shows the constants that represent the maximum lengths of strings returned by the date and time formatting routines DateToAscii, DateToDOWDMFormat, and TimeToAscii.

Constant
Value
Description
dateStringLength
9
Maximum length of the string returned by DateToAscii for short date formats.
longDateStrLength
15
Maximum length of the string returned by DateToAscii for medium and long date formats.
timeStringLength
9
Maximum length of the string returned by TimeToAscii.
dowDateStringLength
19
Maximum length of the string returned by DateToDOWDMFormat for short date formats.
dowLongDateStrLength
25
Maximum length of the string returned by DateToDOWDMFormat for both medium and long date formats.

Time Manager Functions

DateAdjust

Purpose

Return a new date +/- the days adjustment.

Prototype

void DateAdjust (DatePtr dateP, Int32 adjustment)

Parameters

<-> datePA pointer to a DateType structure with the date to be adjusted.
-> adjustmentThe number of days by which to adjust the date.

Result

Returns nothing. Upon return, dateP contains the adjusted date.

Comments

This function advances the date and manages month and year wrapping conditions.

See Also

TimAdjust

DateDaysToDate

Purpose

Converts a date specified as the number of days since January 1, 1904 to a DateType structure.

Prototype

void DateDaysToDate (UInt32 days, DatePtr date)

Parameters

-> daysThe number of days since 1/1/1904.
<-> dateA pointer to a DateType structure that is updated with the computed date values.

Result

Returns nothing. Upon return, the date information is returned in the structure referenced by the date parameter.

See Also

DateSecondsToDate, DateToDays

DateSecondsToDate

Purpose

Converts a date specified as the number of seconds since January 1, 1904 to a DateType structure.

Prototype

void DateSecondsToDate (UInt32 seconds, DatePtr date)

Parameters

-> secondsThe number of seconds since 1/1/1904.
<- dateA pointer to a DateType structure that is updated with the computed date values.

Result

Returns nothing. The structure referenced by the date parameter is updated with the date information.

See Also

DateDaysToDate, DateToDays

DateTemplateToAscii

Purpose

Convert the specified date values into a string that is formatted according to a formatting template specification.

Prototype

UInt16 DateTemplateToAscii (const Char *templateP, UInt8 months, UInt8 days, UInt16 years, Char *stringP, Int16 stringLen)

Parameters

-> templatePA pointer to the template string used to format the date. The maximum length of this string is maxDateTemplateLen bytes, excluding the null terminator character.
See the Comments section below for details on how to specify date formatting in this template string.
-> monthsThe month number, which must be a value between 1 and 12.
-> daysThe day number, which must be a value between 1 and 31.
-> yearsThe four-digit year number. For example, 1995.
<- stringPA pointer to a string that is updated with the result.
If stringP is NULL, this function does not write an output string; however, it does return the length required for the output string.
If stringP is not NULL, this function writes the formatted string to stringP, writing up to stringSize bytes into stringP.
-> stringLenThe size of the stringP buffer.

Result

The length of the formatted string, without the terminating NULL byte.

The DateTemplateToAscii returns the required length of the formatted string even if the stringP parameter is NULL; this allows you to determine the buffer size at runtime.

Comments

This function is intended as a replacement for the DateToAscii and DateToDOWDMFormat functions.

This function uses the formatting template referenced by templateP to create a formatted string from the date values that you pass in.

You specify a series of formatting substrings in templateP. Each substring has the form:


   ^<valueType><formatModifier> 

Each substring has three components:

The ^ character begins a substring.

The <valueType> component is a single-digit value that specifies the value type.

The <formatModifier> component is a single-letter value that specifies how you want that value formatted.

The following is an example of a template specification with three substrings:

^0z ^2l ^4r 

Table 53.1 shows the values you can specify for the <valueType> component. Note that the formatted result depends on the <modifier> value.

Table 53.1 Template value types for the DateTemplateToAscii function 
Value
Value type
Formatted examples
0
Day number
1, 01, 23, 31
1
Day name
Tue, Tuesday
2
Month name
May, Aug, August
3
Month number
4, 04, 11
4
Year number
97, 1997

Table 53.2 shows the values you can specify for the <modifier> component of each template substring.

Table 53.2 Template modifier types for the DateTemplateToAscii function
Modifier
Description
s
Formats the value in short form
r
Formats the value in regular form
l
Formats the value in long form
z
Adds a leading zero to the formatted numeric value

Finally, Table 53.3 shows examples of each value type formatted with each modifier type.

Table 53.3 Examples of formatted values 
Value type
Raw value
s
(Short format)
r
(Regular format)
l
(Long format)
z
(Zero format)
0
(Day number)
2
2
2
2
02
1
(Day name)
2
T
Tue
Tuesday
n/a
2
(Month name)
11
N
Nov
November
n/a
3
(Month number)
11
11
11
11
11
4
(Year number)
2000
00
2000
2000
n/a

For example, calling DateTemplateToAscii as follows:

DateTemplateToAscii("^0z ^2l ^4r", 2, 7, 
  2000, myStr, 20) 

Produces the following formatted string:

07 February 2000 

Compatibility

Implemented only if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call DateGlueTemplateToAscii. For more information, see Chapter 76, "PalmOSGlue Library."

See Also

DateToAscii, DateToDOWDMFormat

DateToAscii

Purpose

Convert the passed date to a string using the format specified by the dateFormat parameter.

Prototype

void DateToAscii (UInt8 months, UInt8 days, UInt16 years, DateFormatType dateFormat, Char *pString)

Parameters

-> monthsThe month number, which must be a value between 1 and 12.
-> daysThe day number, which must be a value between 1 and 31.
-> yearsThe four-digit year number. For example, 1995.
-> dateFormatAny DateFormatType format.
<- pStringA pointer to string that is updated with the result.
This string must be of length dateStringLength for short formats or longDateStrLength for medium or long formats. Note that these lengths do include the terminating NULL byte. For more information about required string lengths, see Time Manager Constants.

Result

Returns nothing. The string reference by pString is updated with the formatted string.

Comments

If you are using a debug ROM, the string buffer is filled with either dateStringLength or longStrLength debugging bytes, depending on the value of the dateFormat parameter.

It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.

Note that you can use the DateTemplateToAscii function instead of this function if the 3.5 feature set is present. You can call the DateTemplateToAscii function with a NULL string buffer to predetermine the required size for your buffer.

See Also

TimeToAscii, DateToDOWDMFormat, DateTemplateToAscii

DateToDays

Purpose

Convert the DateType structure to the number of days elapsed from January 1, 1904.

Prototype

UInt32 DateToDays (DateType date)

Parameters

-> dateA DateType structure.

Result

Returns the number of days elapsed from January 1, 1904 to the specified date.

See Also

DateDaysToDate

DateToDOWDMFormat

Purpose

Convert a date to a formatted string using the format specified by the dateFormat parameter. The resultant string includes the name of the day of the week.

Prototype

void DateToDOWDMFormat (UInt8 months, UInt8 days, UInt16 years, DateFormatType dateFormat, Char *pString)

Parameters

-> monthsThe month number, which must be a value between 1 and 12.
-> daysThe day number, which must be a value between 1 and 31.
-> yearsThe four-digit year number. For example, 1995.
-> dateFormat Any DateFormatType format.
<- pStringA pointer to a string that is updated with the result. The string must be of length dowDateStringLength for short formats or dowLongDateStrLength for medium or long date formats. See Time Manager Constants for string buffer lengths.

Result

Returns nothing. The string referenced by pString is updated with the formatted string.

Comments

The values of some of the Time Manager Constants that specify the required string buffer lengths do change from time to time. You should always use the constants or verify the required lengths by checking the datetime.h file.

It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.

Note that you can use the DateTemplateToAscii function instead of this function if the 3.5 feature set is present. You can call the DateTemplateToAscii function with a NULL string buffer to predetermine the required size for your buffer.

Compatibility

On Palm OS 3.1 Japanese ROMs, this function contains a bug that prevented it from properly displaying 4-byte long day names. To prevent this bug from affecting your application, use DateGlueToDOWDMFormat in the PalmOSGlue library instead of calling this function directly. For more information, see Chapter 76, "PalmOSGlue Library."

See Also

DateToAscii, DateTemplateToAscii

DayOfMonth

Purpose

Return a value that represents the day of a month on which the specified date occurs. The value represents a quantity such as "First Monday" or "Third Friday" as is used for repeating appointments in the Datebook.

Prototype

Int16 DayOfMonth (Int16 month, Int16 day, Int16 year)

Parameters

-> monthThe month number, which must be a value between 1 and 12.
-> dayThe day number, which must be a value between 1 and 31.
-> yearThe four-digit year number. For example, 1995.

Result

Returns a value that represents day of the month. This value is one of the DayOfMonthType values.

Comments

The returns value can be used to specify on which day of the month an appointment repeats.

DayOfWeek

Purpose

Return the day of the week value for a specified date.

Prototype

Int16 DayOfWeek (Int16 month, Int16 day, Int16 year)

Parameters

-> monthThe month number, which must be a value between 1 and 12.
-> dayThe day number, which must be a value between 1 and 31.
-> yearThe four-digit year number. For example, 1995.

Result

Returns one of the following values for the day of the week of the specified date, as shown in the following table:

Day name
Returned day value
Sunday
0
Monday
1
Tuesday
2
Wednesday
3
Thursday
4
Friday
5
Saturday
6

DaysInMonth

Purpose

Return the number of days in the month.

Prototype

Int16 DaysInMonth (Int16 month, Int16 year)

Parameters

-> monthThe month number, which must be a value between 1 and 12.
-> yearThe four-digit year number. For example, 1995.

Result

Returns the number of days in the month for the specified year.

TimAdjust

Purpose

Return a new date, with the time adjusted by the specified number of seconds.

Prototype

void TimAdjust (DateTimePtr dateTimeP, Int32 adjustment)

Parameters

<-> dateTimePA pointer to a DateType structure.
-> adjustment The number of seconds by which to adjust the time.

Result

Returns nothing. The structure referenced by dateTimeP is modified to contain the updated date and time.

Comments

This function advances the time by the specified number of seconds and takes care of any wraparound conditions.

See Also

DateAdjust

TimDateTimeToSeconds

Purpose

Return the number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the specified date and time.

Prototype

UInt32 TimDateTimeToSeconds (DateTimePtr dateTimeP)

Parameters

-> dateTimePA pointer to a DateTimeType structure.

Result

The number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the date referenced by dateTimeP.

See Also

TimSecondsToDateTime

TimGetSeconds

Purpose

Return the current date and time of the device in seconds since 12:00 A.M. on January 1, 1904.

Prototype

UInt32 TimGetSeconds (void)

Parameters

None.

Result

The number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the current date and time on the device.

See Also

TimSetSeconds

TimGetTicks

Purpose

Return the tick count since the last reset. The tick count does not advance while the device is in sleep mode.

Prototype

UInt32 TimGetTicks (void)

Parameters

None.

Result

Returns the tick count.

Comments

You can call the SysTicksPerSecond routine to determine the number of ticks per second.

See Also

SysTicksPerSecond

TimSecondsToDateTime

Purpose

Converts a date specified as the number of seconds since January 1, 1904 to a DateTimeType structure.

Prototype

void TimSecondsToDateTime (UInt32 seconds, DateTimePtr dateTimeP)

Parameters

-> secondsA date specified as the number of seconds elapsed from 12:00 A.M. on January 1, 1904 to the date
<- dateTimePA pointer to a DateTimeType structure that is updated with the date and time values.

Result

Returns nothing. The structure referenced by dateTimeP is updated with the date and time computed for the number of seconds since 12:00 A.M. on January 1, 1904.

See Also

TimDateTimeToSeconds

TimSetSeconds

Purpose

Set the clock of the device to the date and time passed as the number of seconds since 12:00 A.M. on January 1, 1904.

Prototype

void TimSetSeconds (UInt32 seconds)

Parameters

-> secondsThe number of seconds since 12:00 A.M. on January 1, 1904.

Result

Returns nothing.

Comments

On systems with the Notification Feature Set is present, this function broadcasts the sysNotifyTimeChangeEvent to all interested parties. See Chapter 40, "Notification Manager." for more information.

See Also

TimGetSeconds

TimeToAscii

Purpose

Convert the time to a string that is formatted according to the specified timeFormat.

Prototype

void TimeToAscii (UInt8 hours, UInt8 minutes, TimeFormatType timeFormat, Char *pString)

Parameters

-> hoursThe number of hours. This must be a value between 0 and 23.
-> minutesThe number of minutes. This must be a value between 0 and 59.
-> timeFormatThe time format for the resultant string. This must be one of the TimeFormatType values.
<- pStringA pointer to a string that is updated with the resultant string. This string must be of length timeStringLength.
See Time Manager Constants for information on string buffer lengths.

Result

Returns nothing. The string referenced by pString is updated with the formatted string.

Comments

If you are using a debug ROM in Palm OS 3.5, the string buffer is filled with timeStringLength debugging bytes.

It is important to allocate enough space for your string buffer. Finding buffer overflow errors can be difficult when using a debug ROM. One common situation is when you pass a buffer that is too small from a form, for an element such as a label or title. Then, the buffer overflow can clobber objects that follow the form in memory. When a form element's location information is corrupted, it disappears from the display.

See Also

DateToAscii

New TimeZoneToAscii

Purpose

Convert a time zone to a string.

Prototype

void TimeZoneToAscii (Int16 timeZone, const LmLocaleType *localeP, Char *string)

Parameters

-> timeZone A pointer to the time zone, given as minutes east of Greenwich Mean Time (GMT).
-> localePA pointer to a locale (see LmLocaleType) that identifies the time zone country. You can use the constant lmAnyLanguage as the value for the language field of the structure pointed to by this parameter.
<- stringA pointer to a string in which to return the result. This string must be of length timeZoneStringLength.

Result

Returns nothing.

Comments

This function returns a descriptive string for the specified time zone. This string identifies the time zone first by its country, such as "USA (Mountain)" or "Canada (Eastern)." If the function cannot find a time zone that matches the specified GMT offset and country, it returns a string containing the time zone as a numeric offset from the GMT (for example, "GMT+9:00").

Compatibility

Implemented only if 4.0 New Feature Set is present.

New TimTimeZoneToUTC

Purpose

Converts a date and time from a given time zone to Universal Coordinated Time (UTC). UTC is also known as Greenwich Mean Time (GMT).

Prototype

UInt32 TimTimeZoneToUTC (UInt32 seconds, Int16 timeZone, Int16 daylightSavingAdjustment)

Parameters

-> secondsThe number of seconds since 12:00 A.M. on January 1, 1904.
-> timeZone The time zone, given as the number of minutes east of UTC. For time zones west of UTC but before the international dateline, this is a negative number.
-> daylightSavingAdjustmentThe number of minutes to add to the current time for daylight savings time in this time zone.

Result

Returns the same time as seconds but in the Universal Coordinated Time. The value is still given as the number of seconds since 12:00 A.M. on January 1, 1904.

Comments

The returned value is not necessarily the time in Greenwich because Greenwich may be observing daylight saving time.

You can use this function to convert the local time to UTC. The time zone and the daylight savings adjustment are system preferences that can be retrieved using PrefGetPreference. For example, the following code converts the current local time to UTC:

Int16 timeZone =  
  PrefGetPreference(prefTimeZone); 
Int16 daylightSavingAdjustment =  
  PrefGetPreference(  
  prefDaylightSavingAdjustment); 
UInt32 utcTime =  
  TimTimeZoneToUTC(TimGetSeconds(), timeZone,  
  daylightSavingAdjustment); 

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TimUTCToTimeZone

New TimUTCToTimeZone

Purpose

Converts a date and time from Universal Coordinated Time (UTC) to the specified time zone. UTC is also known as Greenwich Mean Time (GMT).

Prototype

UInt32 TimUTCToTimeZone (UInt32 seconds, Int16 timeZone, Int16 daylightSavingAdjustment)

Parameters

-> secondsThe number of seconds since 12:00 A.M. on January 1, 1904 in UTC.
-> timeZone The time zone, given as the number of minutes east of UTC. For time zones west of UTC before the international dateline, this is a negative number.
-> daylightSavingAdjustmentThe number of minutes to add to the current time for daylight savings time in this time zone.

Result

Returns the same time as seconds but in the specified time zone. The value is still given as the number of seconds since 12:00 A.M. on January 1, 1904.

Comments

The seconds value is not necessarily the time in Greenwich because Greenwich may be observing daylight saving time.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

TimTimeZoneToUTC