Prototype and description of the function gettznamebynum() (Function of the unlock requiring group "Time Zone Calculations") |
gettznamebynum() Determination of a time zone designation from a GeoDLL time zone index. Prototype of the DLL function in C++ syntax (attend lower case!): extern "C" __declspec(dllimport) unsigned long __stdcall gettznamebynum( unsigned short nTimeZone, char **pszTimeZone); Prototype of the DLL function in Visual Objects syntax: _DLL function gettznamebynum(; nTimeZone as word,; // 2 Byte pszTimeZone ref psz); // 4 Byte, char**, 40 alloc. as logic pascal:geodll32.gettznamebynum // 4 Byte The allocation of memory for "ref psz" / "char**" is necessary only if setstringallocate(FALSE) is called before. A time zone is a region that has an uniform standard time for legal, commercial, and social purposes. Time zones are primarily longitude dependent, but secondary they follow the boundaries of countries or their administrative subdivisions. The time zones supported by GeoDLL are based on an uniform naming convention, designed by Paul Eggert, such as America/New_York and Europe/Paris. The time zones have offsets from Coordinated Universal Time (UTC) as a number of hours (UTC-12 to UTC+12). Many higher latitude countries use Daylight Saving Time (DST) for a part of the year, typically by changing clocks one hour forward. The function determines the name of a time zone based on a GeoDLL time zone index. The text is returned in the language set by the function setLanguage() before. A distinction is made between national and international time zones. The designation of a national time zone consists of an area name and a city name. Example: "Europe/Berlin". An international time zone consists dependent of the longitude a designation between "UTC-12:00" and "UTC+12:00" and an international identifier between "Alpha" and "Zulu". Example: "Offshore UTC+01:00/Alpha". The required GeoDLL time zone index can be determined like follows: gettznumbycoordexact() Exact determination of a index from a coordinate gettznumbycoordfast() Fast determination of a index from a coordinate List From the list of supported GeoDLL time zones The parameters are passed and/or returned as follows: nTimeZone Time zone index, which has been previously calculated by other time zone functions or has been read from the list. pszTimeZone Designation of the time zone. The string is returned by reference. (ref) See description above. Note: "ref pszTimeZone" corresponds to "char**" in C. 40 bytes of memory for the zero terminated string must be allocated with dependence to the call of the function setstringallocate(). Please consider the notes in the description of the function setstringallocate(). returnVal In case of an error the function returns FALSE, otherwise TRUE. Unlocking: This function is a component of the unlock requiring function group "Time zone calculations". It is unlocked for unrestricted use together with the other functions of the group by passing the unlock parameters, acquired from the software distribution company, trough the function setunlockcode(). Without unlocking only a few function calls for test purposes (shareware principle) are possible. |