Prototyp und Beschreibung der Funktion gettznamebynum()

(Funktion der freischaltpflichtigen Gruppe "Zeitzonenberechnungen")

gettznamebynum()
Ermittlung einer Zeitzonenbezeichnung aus einem GeoDLL-Zeitzonen-Index.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettznamebynum(
     unsigned short nTimeZone,
     char **pszTimeZone);

Prototyp der DLL-Funktion 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

Die Allokation von Speicher für "ref psz" / "char**" ist nur notwendig,
wenn zuvor setstringallocate(FALSE) aufgerufen worden ist.


Eine Zeitzone ist eine Region mit einer einheitlichen Standardzeit für
rechtliche, wirtschaftliche und soziale Zwecke. Zeitzonen sind primär vom
Längengrad abhängig, folgen aber sekundär den Grenzen von Staaten oder deren
administrativen Untereinheiten. Die von GeoDLL unterstützten Zeitzonen basieren
auf einer einheitlichen Namenskonvention von Paul Eggert, wie z.B.
Amerika/New_York und Europa/Paris. Die Zeitzonen entsprechen Offsets von der
Coordinated Universal Time (UTC) als eine Anzahl von Stunden (UTC-12 bis
UTC+12). Viele Staaten in höheren Breitengraden verwenden die Sommerzeit (DST)
in einen Teil des Jahres, die normalerweise durch das Vorstellen der Uhren um
eine Stunde realisiert wird.

Die Funktion ermittelt die Bezeichnung einer Zeitzone anhand eines GeoDLL-
Zeitzonen-Index. Der Text wird in der zuvor mit der Funktion setLanguage()
gesetzten Sprache zurückgegeben.

Es wird zwischen nationalen und internationalen Zeitzonen unterschieden. Die
Bezeichnung einer nationalen Zeitzone besteht aus einem Gebietsnamen und einem
Stadtnamen. Beispiel: "Europa/Berlin".
Eine internationale Zeitzone besteht aus einer vom Längengrad abhängigen
Bezeichnung zwischen "UTC-12:00" und "UTC+12:00" und einer internationalen
Kennung zwischen "Alpha" und "Zulu". Beispiel: "Ozean UTC+01.00/Alpha".

Der benötigte GeoDLL-Zeitzonen-Index kann wir folgt ermittelt werden:
gettznumbycoordexact()  Genaue Ermittlung des Index aus einer Koordinate
gettznumbycoordfast()   Schnelle Ermittlung des Index aus einer Koordinate
Liste                   Aus der Liste der von GeoDLL unterstützten Zeitzonen


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
nTimeZone    Zeitzonen-Index, der zuvor mit anderen Zeitzonen-Funktionen
             berechnet worden ist oder der Liste entnommen worden ist.

pszTimeZone  Bezeichnung der Zeitzone. Der String wird als Referenz zurück-
(ref)        gegeben. Beschreibung siehe oben.
             Achtung: "ref pszTimeZone" entspricht "char**" in C. Es müssen 40
             Byte Speicher für den Null terminated string in Abhängigkeit vom
             Aufruf der Funktion setstringallocate() allokiert werden. Beachten
             Sie dazu die Hinweise in der Beschreibung der Funktion
             setstringallocate()".

returnWert   Im Fehlerfall gibt die Funktion FALSE zurück, sonst TRUE.


Freischaltung:
Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe
"Zeitzonenberechnungen". Sie wird zusammen mit den anderen Funktionen der
Gruppe durch die Eingabe der bei der Vertriebsfirma erworbenen Freischalt-
parameter per Aufruf der Funktion setunlockcode() zur uneingeschränkten Nutzung
frei geschaltet. Ohne die Freischaltung sind nur wenige Funktionsaufrufe zu
Testzwecken (Sharewareprinzip) möglich.