Prototype and description of the function getntvcalcextra()

(Function of the unlock requiring group "NTv2 Transformations")

getntvcalcextra()
Calculation of Extra Parameters during NTv2 transformations.

Prototype of the DLL function in C++ syntax (attend lower case!):
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);

Prototype of the DLL function 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


The function calculates additional (extra) parameters for each coordinate
transformation performed with functions of the type coordtrans*() when
they are using NTv2 datum shifts. The prerequisite for this is the
previous activation of the calculations by the function setcalcextra().
The Extra Parameters can be prompted after each NTv2 coordinate
transformation.

The Extra Parameters calculated by a NTv2 coordinate transformation are
retained until the function setcalcextra() with set parameter on TRUE is
called next time.

The following Extra Parameters are available:
  Number of the NTv2 grid identified during the calculation.
  Shift value of the longitude at the coordinate in seconds.
  Shift value of the latitude at the coordinate in seconds.
  Beared shift value at the coordinate in seconds.
  Beared shift value at the coordinate in meter.
  Beared angel at the coordinate in degree.
  Number of rows in the determined NTv2 grid.
  Number of columns in the determined NTv2 grid.
  Row of the grid mesh found for the coordinate.
  Column of the grid mesh found for the coordinate.
  Index of the grid mesh found for the coordinate.

The number of the NTv2 grid can be used to determine further
information, e.g. with the getntvgridheader() function.

The shift values of the longitude and latitude indicate the offset
between the source reference system and the target reference system in
seconds.

The bearing shift value in seconds is the absolute value of the
hypotenuse from the longitude and latitude shift values in seconds.

The bearing shift value in meters is the distance between the source
and target coordinates in the target reference system calculated using
Vincenty's formula.

The angle in degree is the angle between the source and target
coordinates in the target reference system calculated using Vincenty's
formula.

The number of rows and columns provides information about the maximum
extent of the determined subgrid.

The rows and columns found for the calculated coordinate provide
information about the position of the grid mesh in the rectangular
subgrid.

The index found for the calculated coordinate represents the sequence
number of the grid mesh in the NTv2 grid.


The parameters are returned as follows:
nGridCount  Number of the NTv2 grid identified during the calculation.
(ref)       Or -9999, if the value could not be calculated.

nShiftLon   Shift value of the longitude at the coordinate in seconds.
(ref)       Or -9999, if the value could not be calculated.

nShiftLat   Shift value of the latitude at the coordinate in seconds.
(ref)       Or -9999.0, if the value could not be calculated.

nShiftBear  Beared shift value at the coordinate in seconds.
(ref)       Or -9999.0, if the value could not be calculated.

nRowCount   Number of rows in the determined NTv2 grid.
(ref)       Or -9999.0, if the value could not be calculated.

nColCount   Number of columns in the determined NTv2 grid.
(ref)       Or -9999, if the value could not be calculated.

nRowCoord   Row of the grid mesh found for the coordinate.
(ref)       Or -9999, if the value could not be calculated.

nColCoord   Column of the grid mesh found for the coordinate.
(ref)       Or -9999, if the value could not be calculated.

nMashInd    Index of the grid mesh found for the coordinate.
(ref)       Or -9999, if the value could not be calculated.

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


Unlocking:
This function is a component of the unlock requiring function group
"NTv2 Transformations". 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. It should be noted that in addition the function
group "Coordinate Transformations" must be unlocked.