Prototype and description of the function getellsys()

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

 

getellsys()
Determination of the designations and parameters of the geodetic ellipsoids
used in a geodetic System.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getellsys(
     unsigned short wRefSysQ,
     unsigned short wRefSysZ,
     unsigned short wCoordSysQ,
     unsigned short wCoordSysZ,
     char **pszEllSys);

Prototype of the DLL function in Visual Objects syntax:
_DLL function getellsys(;
     wRefSysQ as word,;                    // 2 Byte
     wRefSysZ as word,;                    // 2 Byte
     wCoordSysQ as word,;                  // 2 Byte
     wCoordSysZ as word,;                  // 2 Byte
     pszEllSys ref psz);                   // 4 Byte, char**, 600 alloc.
as logic pascal:geodll32.getellsys         // 4 Byte

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


The function returns the designations and earth semi axes parameters and
the flattenings of the ellipsoids fitting to the source and target systems
passed in wRefSysQ, wRefSysZ, wCoordSysQ and wCoordSysZ as formatted text in
the parameter pszEllSys. The text is returned in the language set by the
function setLanguage() before.


The parameters are passed and/or returned as follows:
wRefSysQ    Geodetic source Reference System. The available reference
            systems are specified in the list "Coordinate and Reference
            systems".

wRefSysZ    Geodetic target Reference System to which coordinates of
            the source Reference System has to be transformed. The
            available Reference Systems are specified in the list
            "Coordinate Reference Systems".

wCoordSysQ  Source Coordinate System. It is needed only if for the source
            or target Reference Systems the flags 1100, 1150 or 1200 (no
            Reference System Transition) or the flag 0 (standard reference
            system) are set, in order to indicate the standard ellipsoid
            used in that case. The available Coordinate Systems are specified
            in the list "Coordinate Reference Systems".

wCoordSysZ  Target Coordinate System. It is needed only if for the source
            or target Reference Systems the flags 1100, 1150 or 1200 (no
            Reference System Transition) or the flag 0 (standard reference
            system) are set, in order to indicate the standard ellipsoid used
            in that case. The available Coordinate Systems are specified in
            the list "Coordinate Reference Systems".

pszEllSys   The ellipsoid parameters will be provided together with their
(ref)       description in a formatted text and returned by reference. The
            lines of the text are separated with "Return and Linefeed".
            Note: "ref pszEllSys" corresponds to "char**" in C. 600 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 text looks dependently of the geodetic source and target systems
e.g. like this:
   Ellipsoid of the source system:
   GRS80 (1980)
   6378137.0000 Semi-major axis [meter]
   6356752.3141 Semi-minor axis [meter]
   00298.257220 Inverse flattening [1/f]

   Ellipsoid of the target system:
   Hayford (1909)/Intern. (1924)
   6378388.0000 Semi-major axis [meter]
   6356911.9461 Semi-minor axis [meter]
   00297.000000 Inverse flattening [1/f]


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.