Prototype and description of the function gettzparbynum()

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

gettzparbynum()
Determination of the time zone parameter from a GeoDLL time zone index.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall gettzparbynum(
     unsigned short nTimeZone,
     float *fUtc,
     float *fDst,
     char **pszDstStart,
     char **pszDstEnd);

Prototype of the DLL function 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

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 determined from a GeoDLL time zone index the time zone parameters
UTC, DST and keys for the beginning and end of the daylight saving period (DST
period).

The up to six character long codes for the beginning and end of the DST period
are structured as follows:
  Char 1 and 2:  Key for the month (01 to 12)
  Char 3 to 6:   Key for the day
     2 digits:
       The two digits represent a fixed day in the month (01-31)
     2 letters and 2 digits:
       The two letters represent the day of the week in the month:
         SU Sunday   MO Monday   TU Tuesday   WE Wednesday   TH Thursday
         FR Friday   SA Saturday
       The two digits represent the earliest days in the month (›=), on which
       the day of the week may fall.
     2 letters and the letter "L":
       The two letters represent the day of the week in the month like above.
       The letter "L" denotes, that the last day of the week in the month is
       meant.
     Examples:
       0321    March 21
       03SU08  The Sunday on/after March 8
       03FR23  The Friday on/after March 23
       03SUL   The Last Sunday in March
       04THL   The last Thursday in April

If the key pszDstStart for the start of DST period contains a higher date than
the key pszDstEnd for the end of the DST period, the time zone is located in the
southern hemisphere. In this case the DST period exceeds the turn of the year.

If no DST period is used in the time zone, the two key pszDstStart and pszDstEnd
are empty (null string) and the parameter fDst contains the value 0.

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.

fUtc         Offset of the time zone from the Coordinated Universal Time (UTC)
(ref)        in hours. The value is returned by reference.

fDst         DST in hours, if Daylight Saving Time is used in the time zone. The
(ref)        value is returned by reference.
0.0:         If no Daylight Saving Time is used in the time zone.

pszDstStart  Key for the Date on which the DST period starts. The string is
(ref)        returned by reference. Syntax see above.
             Note: "ref pszDstStart" corresponds to "char**" in C. 10 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().

pszDstEnd    Key for the Date on which the DST period ends. The string is
(ref)        returned by reference. Syntax see above.
             Note: "ref pszDstEnd" corresponds to "char**" in C. 10 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.