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(dllexport) 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.