Prototype and description of the function gettznamebynum()

(Function of the unlock requiring group "Time Zone Calculations")


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()

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

returnVal    In case of an error the function returns FALSE, otherwise TRUE.

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.