Prototype and description of the function getcoordaxis3d()

(Function of the unlock requiring group "Parameter determination")

getcoordaxis3d()
Determination of a 3D Coordinate Systems axes designation.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getcoordaxis3d(
     unsigned short wCoordSys,
     char **pszCoordAxEa,
     char **pszCoordAxNo,
     char **pszCoordAxHgt);

Prototype of the DLL function in Visual Objects syntax:
_DLL function getcoordaxis3d(;
     wCoordSys as word,;                   // 2 Byte
     pszCoordAxEa ref psz,;                // 4 Byte, char**, 30 alloc.
     pszCoordAxNo ref psz;                 // 4 Byte, char**, 30 alloc.
     pszCoordAxHgt ref psz);               // 4 Byte, char**, 30 alloc.
as logic pascal:geodll32.getcoordaxis3d    // 4 Byte

The allocation of memory for "ref psz" / "char**" is necessary only if
setstringallocate(FALSE) is called before.


The function returns the 3D Coordinate Systems axes designations fitting
to wCoordSys in the variables pszCoordAxEa (east axis), pszCoordAxNo
(north axis) and pszCoordAxHgt (height or Z-axis). The designations 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 axes designations are to be
            determined. The available Coordinate Systems are specified in
            the list "Coordinate Reference Systems".

pszCoordAxEa  The axis designation of the east axis of the coordinate
(ref)       system is returned by reference.
            Note: "ref pszCoordAxEa" 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().

pszCoordAxNo  The axis designation of the north axis of the coordinate
(ref)       system is returned by reference.
            Note: "ref pszCoordAxNo" 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().

pszCoordAxHgt  The designation "Ellips. Height" or in case of cartesian
(ref)       coordinates the designation of the Z axis is returned by
            reference.
            Note: "ref pszCoordAxHgt" 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().

ReturnVal   In case of an error the function returns FALSE, otherwise TRUE.


The returned axes designations looks dependently of the Coordinate System
e.g. like this:
  Easting    Northing    Ellips. Height
or
  Longitude  Latitude    Ellips. Height
or in case of cartesian coordinates
  X          Y            Z


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.