Prototyp und Beschreibung der Funktion getntvcalcextra()

(Funktion der freischaltpflichtigen Gruppe "NTv2-Transformationen")

getntvcalcextra()
Berechnung von Extra-Parametern während NTv2-Transformationen.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall getntvcalcextra(
     short *nGridNum,
     double *nShiftLon,
     double *nShiftLat,
     double *nShiftBear,
     double *nShiftDist,
     double *nShiftAngle,
     long *nRowCount,
     long *nColCount,
     long *nRowCoord,
     long *nColCoord,
     long *nMashInd);

Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL FUNCTION getntvcalcextra;
     (nGridNum REF WORD,;                  // 2 Byte
      nShiftLon REF REAL8,;                // 8 Byte
      nShiftLat REF REAL8,;                // 8 Byte
      nShiftBear REF REAL8,;               // 8 Byte
      nShiftDist REF REAL8,;               // 8 Byte
      nShiftAngle REF REAL8,;              // 8 Byte
      nRowCount REF DWORD,;                // 4 Byte
      nColCount REF DWORD,;                // 4 Byte
      nRowCoord REF DWORD,;                // 4 Byte
      nColCoord REF DWORD,;                // 4 Byte
      nMashInd REF DWORD);                 // 4 Byte
 AS LOGIC PASCAL:geodll32.getntvcalcextra  // 4 Byte


Die Funktion berechnet bei jeder Koordinatentransformation, die mit
Funktionen des Typs coordtrans*() unter Verwendung von NTv2-Datumswechsel
durchgeführt wird, zusätzliche (extra) Parameter. Voraussetzung dafür ist
das vorherige Einschalten der Berechnungen mit der Funktion
setcalcextra(). Jeweils nach einer NTv2-Koordinatentransformation können
die Extra-Parameter abgefragt werden.

Die bei einer NTv2-Koordinatentransformation berechneten Extra-Parameter
bleiben solange erhalten, bis die Funktion setcalcextra() das nächste Mal
mit dem auf TRUE gesetzten Parameter aufgerufen wird.

Folgende Extra-Parameter stehen zur Verfügung:
  Die Nummer des bei der Berechnung ermittelten NTv2-Gitters.
  Shiftwert der Länge an der Koordinate in Sekunden.
  Shiftwert der Breite an der Koordinate in Sekunden.
  Gepeilter Shiftwert an der Koordinate in Sekunden.
  Gepeilter Shiftwert an der Koordinate in Meter
  Gepeilter Winkel an der Koordinate in Grad
  Anzahl der Zeilen im ermittelten NTv2-Gitter.
  Anzahl der Spalten im ermittelten NTv2-Gitter.
  Zeile der für die Koordinate gefundenen Gittermasche.
  Spalte der für die Koordinate gefundenen Gittermasche.
  Index der für die Koordinate gefundenen Gittermasche.

Die Nummer des NTv2-Subgitters kann zur Ermittlung weiterer Informationen,
z.B. mit der Funktion getntvgridheader(), verwendet werden.

Die Shiftwerte der Länge und Breite geben den Versatz zwischen dem Quell-
Bezugssystem und dem Ziel-Bezugssystem in Sekunden an.

Der gepeilte Shiftwert in Sekunden ist der Absolutbetrag der Hypotenuse
aus den Längen- und Breiten-Shiftwerten in Sekunden.

Der gepeilte Shiftwert in Meter ist die mit der Formel von Vincenty
berechnete Unterschied zwischen der Quell- und Zieilkoordinate im Ziel-
Bezugssystem.

Der gepeilte Winkel in Grad ist der mit der Formel von Vincenty
berechnete Winkel zwischen der Quell- und Zielkoordinate im Ziel-
Bezugssystem.

Die Anzahl der Zeilen und Spalten gibt Auskunft über die maximale
Ausdehnung des ermittelten  NTv2-Ggitter.

Die für die berechnete Koordinate gefundenen Zeile und Spalte geben
Auskunft über die Position der Gittermasche im rechteckigen NTv2-Ggitter.

Der für die berechnete Koordinate gefundenen Index stellt die
fortlaufende Nummer der Gittermasche im NTv2-Gitter dar.



Die Parameter werden folgendermaßen zurückgegeben:
nGridCount  Nummer des bei der Berechnung ermittelten NTv2-Gitters.
(ref)       Oder -9999, falls der Wert nicht berechnet werden konnte.

nShiftLon   Shiftwert der Länge an der Koordinate in Sekunden.
(ref)       Oder -9999.0, falls der Wert nicht berechnet werden konnte.

nShiftLat   Shiftwert der Breite an der Koordinate in Sekunden.
(ref)       Oder -9999.0, falls der Wert nicht berechnet werden konnte.

nShiftBear  Gepeilter Shiftwert an der Koordinate in Sekunden.
(ref)       Oder -9999.0, falls der Wert nicht berechnet werden konnte.

nRowCount   Anzahl der Zeilen im ermittelten NTv2-Gitters.
(ref)       Oder -9999, falls der Wert nicht berechnet werden konnte.

nColCount   Anzahl der Spalten im ermittelten NTv2-Gitters.
(ref)       Oder -9999, falls der Wert nicht berechnet werden konnte.

nRowCoord   Zeile der für die Koordinate gefundenen Gittermasche.
(ref)       Oder -9999, falls der Wert nicht berechnet werden konnte.

nColCoord   Spalte der für die Koordinate gefundenen Gittermasche.
(ref)       Oder -9999, falls der Wert nicht berechnet werden konnte.

nMashInd    Index der für die Koordinate gefundenen Gittermasche.
(ref)       Oder -9999, falls der Wert nicht berechnet werden konnte.

returnWert  Im Fehlerfall gibt die Funktion FALSE zurück, sonst TRUE.


Freischaltung:
Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe
"NTv2-Transformationen". Sie wird zusammen mit den anderen Funktionen der
Gruppe durch die Eingabe der bei der Vertriebsfirma erworbenen Freischalt-
parameter per Aufruf der Funktion setunlockcode() zur uneingeschränkten
Nutzung frei geschaltet. Ohne die Freischaltung sind nur wenige Funktions-
aufrufe zu Testzwecken (Sharewareprinzip) möglich. Es ist zu beachten, dass
zusätzlich die Funktionsgruppe "Koordinatentransformationen" frei geschaltet
sein muss.