|
Prototype and description of the function getcoordform3d() (Function of the unlock requiring group "Parameter determination") |
|
getcoordform3d()
Determination of the east, north and height component notations of
a 3D Coordinate System.
Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getcoordform3d(
unsigned short wCoordSys,
unsigned short wCoordLength,
unsigned short wHeightLength,
char **pszCoordFmEa,
unsigned short *wCoordLgEa,
char **pszCoordFmNo,
unsigned short *wCoordLgNo,
char **pszCoordFmHgt,
unsigned short *wCoordLgHgt,
unsigned short *wCoordTyp);
Prototype of the DLL function in Visual Objects syntax:
_DLL function getcoordform3d(;
wCoordSys as word,; // 2 Byte
wCoordLength as word,; // 2 Byte
wHeightLength as word,; // 2 Byte
pszCoordFmEa ref psz,; // 4 Byte, char**, 30 alloc.
wCoordLgEa ref word,; // 4 Byte
pszCoordFmNo ref psz,; // 4 Byte, char**, 30 alloc.
wCoordFmNo ref word,; // 4 Byte
pszCoordFmHgt ref psz,; // 4 Byte, char**, 30 alloc.
wCoordFmHgt ref word,; // 4 Byte
wCoordTyp ref word); // 4 Byte
as logic pascal:geodll32.getcoordform3d // 4 Byte
The allocation of memory for "ref psz" / "char**" is necessary only if
setstringallocate(FALSE) is called before.
The function returns the east, north and height component notations of
the 3D Coordinate System fitting to wCoordSys in the string parameters
pszCoordFmEa (east component), pszCoordFmNo (north component) and
pszCoodFmHgt (height component). In case of cartesic coordinates the
function returns the notation of the cartesian Z component instead of the
notation of the ellipsoidal height component. The notations are expanded
by adding decimal places to the size indicated in wCoordLength (east and
north components) and wHeightLength (height component). The notations of
alphanumeric coordinates are not expanded. The minimum number of digits
or characters necessary for the east and north components are returned in
the parameters wCoordLgEa and wCoordLgNo and for the height component in
the parameter wCoordLgHgt. The notations are returned in the language set
by the function setLanguage() before.
The parameters are passed and/or returned as follows:
wCoordSys Coordinate System, for which the notations are to be
determined. The available Coordinate Systems are specified in
the list "Coordinate Reference Systems".
wCoordLength Length, to which the notations of the east and north
components are expanded by adding decimal places. Passing a
zero causes the representation of the notations with only one
decimal place. Passing the value 1000 causes the representation
without any decimal places.
wHeightLength Length, to which the notations of the height component is
expanded by adding decimal places. Passing a zero causes the
representation of this notation with only one decimal place.
Passing the value 1000 causes the representation without any
decimal places.
pszCoordFmEa The string with the notation of the east component of the
(ref) coordinate is returned by reference. The exactly format of the
notation is described in the list "Defaults of the coordinate
systems".
Note: "ref pszCoordFmEa" corresponds to "char**" in C. 30 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().
wCoordLgEa The minimum number of digits or characters necessary for the
(ref) east component of the coordinate is returned by reference.
pszCoordFmNo The string with the notation of the north component of the
(ref) coordinate is returned by reference. The exactly format of the
notation is described in the list "Defaults of the coordinate
systems".
Note: "ref pszCoordFmNo" corresponds to "char**" in C. 30 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().
wCoordLgNo The minimum number of digits or characters necessary for the
(ref) north component of the coordinate is returned by reference.
pszCoordFmHgt The string with the notation of the height component of the
(ref) coordinate is returned by reference. For the ellipsoidal height
the format "±mmmmm" is predefined. For cartesian coordinates the
notation of the Z component correspond with the notations in
pszCoorFmEa and pszCoorFmNo.
Note: "ref pszCoordFmNo" corresponds to "char**" in C. 30 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().
wCoordLgHgt The minimum number of digits or characters necessary for the
(ref) height component of the coordinate is returned by reference.
wCoordTyp The type of the Coordinate System is returned by reference:
(ref) 0 = numeric Coordinate System
1 = alphanumeric Coordinate System
returnVal In case of an error the function returns FALSE, otherwise TRUE.
The returned notations and numbers of digits / characters looks dependently
of the Coordinate System and the desired east / south return length (here 10)
and height length (here 9) e.g. like this:
Geographic coordinates [deg, min, sec]:
±dddmmss.s 8 ±ddmmss.ss 7 ±mmmmm.mm 6 0
or Austrian Gauss-Krueger coordinates:
kkkmmm.mm 6 kkkmmm.mm 6 ±mmmmm.mm 6 0
or British National grid:
aaeeeeennnnn 12 ‹blank› 0 ±mmmmm.mm 6 1
or Cartesian coordinates:
mmmmmmm.mm 7 mmmmmmm.mm 7 mmmmmmm.mm 7 0
Unlocking:
This function is a component of the unlock requiring function group
"parameter determination". 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.
|