Prototype and description of the function gettzcurrentbynum() (Function of the unlock requiring group "Time Zone Calculations") |
gettzcurrentbynum() Determination of the current time zone parameters from a GeoDLL time zone index. Prototype of the DLL function in C++ syntax (attend lower case!): extern "C" __declspec(dllimport) unsigned long __stdcall gettzcurrentbynum( unsigned short nTimeZone, float *fUtc, float *fDst, unsigned long *lIsDstActiv, unsigned long *nDstStart, unsigned long *nDstEnd, unsigned long *lIsSouthHemi, float *fLocalTime); Prototype of the DLL function in Visual Objects syntax: _DLL function gettzcurrentbynum(; nTimeZone as word,; // 2 Byte fUtc ref real4,; // 4 Byte fDst ref real4,; // 4 Byte lIsDstActiv ref logic,; // 4 Byte dwDstStart ref dword,; // 4 Byte dwDstEnd ref dword,; // 4 Byte lIsSouthHemi ref logic,; // 4 Byte fLocalTime ref real4); // 4 Byte as logic pascal:geodll32.gettzcurrentbynum // 4 Byte 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 current time zone parameters UTC, DST and local time, as well as the dates for the beginning and end of the daylight saving period (DST period). Flags indicate whether a DST period in the time zone is used and whether the DST period, as usual in the southern hemisphere, exceeds the turn of the year. For the calculations the function takes the current date from the computer. The local time fLocalTime is composed of the UTC and DST, but the DST is only added if the current date is within the DST period. The beginning and the end of the DST period will be returned in the parameters dwDstStart and dwDstEnd given as a date of the current year with the following syntax: jjjjmmtt jjjj four digits indicating the current year mm two digits indicating the month in which the DST period changes tt two digits indicating the day on which the DST period changes If dwDstStart for the start of DST period contains a higher date than dwDstEnd 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 parameters pszDstStart, pszDstEnd and fDst contain the value 0 and the parameters lIsDstActiv and lIsSouthHemi are set to FALSE. 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. lIsDstActiv Flag for the activity of the DST at the current date. The flag is (ref) returned by reference. TRUE: Current date is within the DST period. FALSE: Current date is outside the DST period or DST is not used in the time zone. dwDstStart Date on which the DST period starts. The value is returned by (ref) reference. Syntax see above. dwDstEnd Date on which the DST period ends. The value is returned by (ref) reference. Syntax see above. lIsSouthHemi Flag for the location of the time zone in the southern hemisphere. (ref) The flag is returned by reference. TRUE: dwDstStart › dwDstEnd --› southern hemisphere FALSE: dwDstStart ‹ dwDstEnd --› nothern hemisphere fLocalTime Local time in the time zone considering the DST period at the (ref) current date as an offset from Coordinated Universal Time (UTC) in hours. The value is returned by reference. fLocalTime = fUtc + fDst 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. |