Prototype and description of the function setuserrefsys()

(Function of the unlock requiring group "User definitions")

 

setuserrefsys()
Configuration of the transformation parameters for a user-defined Reference
System Transition between two geodetic Reference Systems.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall setuserrefsys(
     unsigned short nRefSysTyp,
     double nTranslatX,
     double nTranslatY,
     double nTranslatZ,
     double nRotatX,
     double nRotatY,
     double nRotatZ,
     double nMeasure);

Prototype of the DLL function in Visual Objects syntax:
_DLL function setuserrefsys(;
     nRefSysTyp as word,;                  // 2 Byte
     nTranslatX as real8,;                 // 8 Byte
     nTranslatY as real8,;                 // 8 Byte
     nTranslatZ as real8,;                 // 8 Byte
     nRotatX as real8,;                    // 8 Byte
     nRotatY as real8,;                    // 8 Byte
     nRotatZ as real8,;                    // 8 Byte
     nMeasure as real8);                   // 8 Byte
as logic pascal:geodll32.setuserrefsys     // 4 Byte


The function passes transformation parameters for a user-defined Reference
System Transition between two geodetic Reference Systems. Three translation
vectors and if necessary three rotation angles and a scale factor will be
passed.

Calculation methods:
If additional to the translation vectors the rotation angles and the scale
factor are present, these are used as definition parameters for the Helmert
7-parameter transformation. Are these values missing (all rotations and the
scale factor are zero) the Molodensky 3-parameter transformation is used
automatically.

For the Helmert 7-parameter transformation there are two variants:
   "Coordinate Frame Rotation"
   "Position Vector Transformation" using Bursa / Wolf formulas
The variants differ only by reverse signs of the three rotation parameters.
Since GeoDLL uses the variant "Coordinate Frame Rotation" internally, the
signs of the rotation angles in parameter sets for the "Position Vector
Transformation" are to be reversed.

For the Molodensky 3-parameter transformation there is only one variant:
   "Geocentric Transformation"

Use of the Reference System parameters:
With the functions coordtrans?() the parameters of the user-defined
Reference System described here are used, if for the source and target
Reference Systems (nRefSysQ, nRefSysZ) the value 1000 is passed as flag.

It must be noted that for a user-defined Reference System Transition apart
from the transformation parameters also the semi axes of the source and
target ellipsoids are needed. Reading the ellipsoid semi axes is done with
the functions setuserellsource() and setuserelltarget().


The parameters are passed and/or returned as follows:
nRefSysTyp (Type of the user-defined Reference System)
   Parameter variable
               Description of the parameter

0              Erase the user-defined Reference System
   nTranslatX  0.0 or arbitrary value without effect
   nTranslatY  0.0 or arbitrary value without effect
   nTranslatZ  0.0 or arbitrary value without effect
   nRotatX     0.0 or arbitrary value without effect
   nRotatY     0.0 or arbitrary value without effect
   nRotatZ     0.0 or arbitrary value without effect
   nMeasure    0.0 or arbitrary value without effect

1              Set the user-defined Reference System
   nTranslatX  Translation vector on the X axis in meter
   nTranslatY  Translation vector on the Y axis in meter
   nTranslatZ  Translation vector on the Z axis in meter
   nRotatX     Rotation angle of the X axis in seconds
   nRotatY     Rotation angle of the Y axis in seconds
   nRotatZ     Rotation angle of the Z axis in seconds
   nMeasure    Scale factor in ppm (parts per million).

returnVal      If the parameters for the user-defined Reference System
               are successful stored, the function returns TRUE,
               otherwise FALSE.


Unlocking
This function is a component of the unlock requiring function group
"user definitions". 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.