|
Prototyp und Beschreibung der Funktion gettzparbynum() (Funktion der freischaltpflichtigen Gruppe "Zeitzonenberechnungen") |
|
gettzparbynum()
Ermittlung der Zeitzonen-Parameter aus einem GeoDLL-Zeitzonen-Index.
Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettzparbynum(
unsigned short nTimeZone,
float *fUtc,
float *fDst,
char **pszDstStart,
char **pszDstEnd);
Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function gettzparbynum(;
nTimeZone as word,; // 2 Byte
fUtc ref real4,; // 4 Byte
fDst ref real4,; // 4 Byte
pszDstStart ref psz,; // 4 Byte, char**, 10 alloc.
pszDstEnd ref psz); // 4 Byte, char**, 10 alloc.
as logic pascal:geodll32.gettzparbynum // 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 aus einem GeoDLL-Zeitzonen-Index die Zeitzonen-Parameter
UTC, DST und Schlüssel für den Beginn und das Ende der Sommerzeit-Periode (DST-
Periode).
Die bis zu sechsstelligen Schlüssel für den Beginn und das Ende der DST-Periode
sind wie folgt aufgebaut:
Zeichen 1 und 2: Schlüssel für den Monat (01 bis 12)
Zeichen 3 bis 6: Schlüssel für den Tag
2 Ziffern:
Die beiden Ziffern stellen einen festen Tag im Monat dar (01 bis 31)
2 Buchstaben und 2 Ziffern:
Die beiden Buchstaben stellen den Wochentag im Monat dar:
SU Sonntag MO Montag TU Dienstag WE Mittwoch TH Donnerstag
FR Freitag SA Samstag
Die beiden Ziffern stellen den frühstmöglichen Tag im Monat (›=) dar,
auf das der Wochentag fallen kann.
2 Buchstaben und ein "L":
Die beiden Buchstaben stellen den Wochentag im Monat wie oben dar.
Der Buchstabe "L" bedeutet das der letzte Wochentag im Monat gemeint ist.
Beispiele:
0321 der 21. März
03SU08 der Sonntag am/nach dem 8. März
03FR23 der Freitag am/nach dem 23. März
03SUL der letzte Sonntag im März
04THL der letzte Donnerstag im April
Wenn der Schlüssel pszDstStart für den Beginn der DST-Periode ein höheres Datum
enthält als der Schlüssel pszDstEnd für das Ende der DST-Periode, befindet sich
die Zeitzone auf der südlichen Hemisphäre. Die DST-Periode erstreckt sich dabei
über den Jahreswechsel.
Wenn in der Zeitzone keine DST-Periode verwendet wird, sind die beiden Schlüssel
pszDstStart und PszDstEnd leer (NullStrings) und der Parameter fDst enthält den
Wert 0.
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.
fUtc Offset der Zeitzone von der Coordinated Universal Time (UTC) in
(ref) Stunden. Der Wert wird per Referenz zurückgegeben.
fDst DST (Daylight Saving Time) in Stunden, wenn in der Zeitzone die
(ref) Sommerzeit verwendet wird. Der Wert wird per Referenz zurück-
gegeben.
0.0: Wenn in der Zeitzone kein DST verwendet wird.
pszDstStart Schlüssel für das Datum, an dem die DST-Periode beginnt. Der String
(ref) wird per Referenz zurückgegeben. Syntax siehe oben.
Achtung: "ref pszDstStart" entspricht "char**" in C. Es müssen 10
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()".
pszDstEnd Schlüssel für das Datum, an dem die DST-Periode endet. Der String
(ref) wird per Referenz zurückgegeben. Syntax siehe oben.
Achtung: "ref pszDstEnd" entspricht "char**" in C. Es müssen 10
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.
|