Prototype and description of the function setntvpolyvalid()

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


Sets the Polygonal Validity Check for NTv2 calculations.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall setntvpolyvalid(
     unsigned long lSwitch);

Prototype of the DLL function in Visual Objects syntax:
_DLL function setntvpolyvalid(;
     lSwitch as logic);                     // 4 Byte, char*
as logic pascal:geodll32.setntvpolyvalid    // 4 Byte

The scope of a NTv2 file is by default defined by rectangular coordinate
boxes. In order to be able to implement polygonal structures, e.g. such as
national borders, the producer of a NTv2 file therein can specify a
Polygonal Validity Scope. For this, outside of the poligonal validity
located grid meshes are indicated by the exopolygonal entries -99/-99 in
their shift or accuracy values.

GeoDLL can check the grid meshes on exopolygonal entries and exclude hits
from the calculation and comment them with an error message. The Polygonal
Validity Check will be switched on or off using the function
setntvpolyvalid(). Detailed information can be found in the help section
"Polygonal Validity Scopes".

If the value TRUE is passed in lSwitch, GeoDLL checks for each NTv2
Reference System Transition, whether the coordinate to be transformed is
within the polygonal validity scope of the NTv2 file. NTv2 files without
polygonal validity scope are processed also with set lSwitch as usual.
However, the execution is a bit slower due to the testing.

If FALSE is passed in lSwitch, GeoDLL does not check on polygonal
validity scope. The execution time then is a little faster. Reference
System Transitions in grid meshes with exopolygonal entries -99/-99 for
the shift values are excluded from the calculation and acknowledged with
an error message. Reference System transitions in grid meshes with
exopolygonal entries only for the accuracy values are calculated as usual.

The parameters are passed and/or returned as follows:
lSwitch       Switch for the Polygonal Validity Check.
TRUE          Polygonal Validity Check is switches on.
FALSE         Polygonal Validity Check is switches off.

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

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.