Prototype and description of the function getrefsys()

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

 

getrefsys()
Determination of the transformation parameters for the Reference System
Transition between the geodetic source and target Reference Systems.

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

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

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


The function returns the transformation parameters for the Reference
System Transition fitting to the geodetic source and target reference
systems wRefSysQ and wRefSysZ as formatted text in the parameter pszRefSys.
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 identification 1100, 1150 or
            1200 (no Reference System Transition) is passed, in order to
            indicate the used standard ellipsoid. In addition it is needed,
            if for the source Reference System the identification 0
            (standard Reference System) is passed, in order to indicate the
            standard Reference System that is fitting the coordinate
            system. 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 identification 1100, 1150 or
            1200 (no Reference System Transition) is passed, in order to
            indicate the used standard ellipsoid. In addition it is needed,
            if for the target Reference System the identification 0
            (standard Reference System) is passed, in order to indicate the
            standard Reference System that is fitting the coordinate
            system. The available Coordinate Systems are specified in the
            list "Coordinate Reference Systems".

pszRefSys   The transformation parameters will be provided together with
(ref)       their descriptions in a formatted text and returned by
            reference. The lines of the text are separated with "Return
            and Linefeed".
            Note: "ref pszRefSys" corresponds to "char**" in C. 1200 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().

lForBack    Flag for the representation of Seven Helmert parameters.
            An explanation of the Forward and Backward Transformation can
            be found below.
TRUE:       The seven parameters of the Helmert transformation are each
            presented separately for the Forward Transformation from the
            source system to WGS84 and for the Backward Transformation from
            WGS84 to the target system.
FALSE:      The seven parameters of the Helmert transformation are added
            from the parts Forward Transformation and Backward
            Transformation. They are valid directly from the source to the
            target system and are presented together. User defined
            Reference System Transitions are always shown in this format.

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


GeoDLL calculates Reference System Transitions with Helmert transformation
parameters as Forward and Backward Transformations. With a Forward
Transformation, starting from the source system, first the rotations and
then the translations are performed. With a Backward Transformation,
leading to the target system, in reverse order first the translations and
then the rotations are calculated. Forward and Backward Transformations are
executed each across the current dynamic reference system WGS84. Only user
defined Reference System Transitions are an exception. They are always
calculated directly from the source to the target system.


Calculating bidirectional coordinate transformations with Forward and
Backward Transformations like in GeoDLL does not lead in minor deviations,
that occur in many GIS systems.

With "on" switched flag lForBack the returned text looks dependently of
the geodetic source and target Reference Systems e.g. like this:

  Geodetic Reference Systems:
  DHDN/PD (DE Old States South ‹±1m), Rauenberg, Bessel
     to
  ETRS89 (EU), geocentric, GRS80

  Transformation parameters:
  7 Parameter Helmert Transformation (Bursa-Wolf)
  Coordinate Frame Rotation
  Forward and Backward Transformation separate

  Forward Transformation source system to WGS84
  00597.046300 Translation vector for X-axis [meter]
  00071.349100 Translation vector for Y-axis [meter]
  00412.187300 Translation vector for Z-axis [meter]
  -00.89181300 Rotation around the X-axis [seconds]
  -00.05477000 Rotation around the Y-axis [seconds]
  001.54161600 Rotation around the Z-axis [seconds]
  0007.5733800 Scale correction factor [ppm]

  Backward Transformation WGS84 to target system
  00000.053700 Translation vector for X-axis [meter]
  00000.050900 Translation vector for Y-axis [meter]
  -0000.087300 Translation vector for Z-axis [meter]
  -00.00218700 Rotation around the X-axis [seconds]
  -00.01323000 Rotation around the Y-axis [seconds]
  000.02138400 Rotation around the Z-axis [seconds]
  0000.0026200 Scale correction factor [ppm]

With "off" switched flag lForBack the returned text looks dependently of
the geodetic source and target Reference Systems e.g. like this:

  Geodetic Reference Systems:
  DHDN/PD (DE Old States South ‹±1m), Rauenberg, Bessel
     to
  ETRS89 (EU), geocentric, GRS80

  Transformation parameters:
  7 Parameter Helmert Transformation (Bursa-Wolf)
  Coordinate Frame Rotation
  Forward and Backward Transformation united

  Transformation source system to target system
  00597.100000 Translation vector for X-axis [meter]
  00071.400000 Translation vector for Y-axis [meter]
  00412.100000 Translation vector for Z-axis [meter]
  -00.89400000 Rotation around the X-axis [seconds]
  -00.06800000 Rotation around the Y-axis [seconds]
  001.56300000 Rotation around the Z-axis [seconds]
  0007.5760000 Scale correction factor [ppm]


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 no function calls are possible.