Prototype and description of the function setntvpolyvalid()

(Function of the unlock requiring group "NTv2 grid data")

 

setntvpolyvalid()
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 lPolyValid);

Prototype of the DLL function in Visual Objects syntax:
_DLL function setntvpolyvalid(;
     lPolyValid 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 lPolyValid, 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 lPolyValid as usual.
However, the execution is a bit slower due to the testing.

If FALSE is passed in lPolyValid, 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:
lPolyValid    Switch for the Polygonal Validity Check.
TRUE          Polygonal Validity Check is switches on.
FALSE         Polygonal Validity Check is switches off.
              (default)

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 grid data". 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.