Prototype and description of the function setntvbinautofile()

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

setntvbinautofile()
Sets an NTv2 grid binary file for automatically call in a wait position.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall setntvbinautofile(
     const char *pszFileBinary);

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


The function passes the path and the name of an NTv2 grid data binary file
to the DLL. The file is automatically checked, opened and used with the
first NTv2 Reference System Transition. It is located so far in a waiting
position. This approach makes sense, because the use of NTv2 binary data
is memory intensive and the memory space only will be allocated internly, if
NTv2 Reference System Transitions are executed. In the NTv2 binary file the
grid data for NTv2 Reference System Transitions are contained. The grid data
are used, when one of the functions coordtrans???() has set the reference
system flags for an NTv2 Reference System Transition. The testing of the
file content takes place primary with the first NTv2 Reference System
Transition, then the possible error messages are initialized by the later
used function coordtrans???().

When calling setntvbinautofile() at first a still existing NTv2 class
instance is destroyed. When doing the first NTv2 Reference System Transition,
GeoDLL automatically creates a new NTv2 instance using the specified NTv2
file. The NTv2 instance remains for further NTv2 calculations until another
call of setntvbinaryfile(), setntvbinautofile() or setntvbinautodir() occurs.

For geodetic calculations with NTv2 grid files GeoDLL can make aware of the
paths of the files with further functions:

With the function setntvbinaryfile(), a particular NTv2 file can be
initialized specifically in any directory. That is, for example, necessary
if with the GeoDLL Reference Systems 208 and 209 any, not implicitly by
GeoDLL supported NTv2 file must be initialized. However, the function also
works with all implicitly by GeoDLL supported NTv2 files.

With the function setntvbinautodir() an automatically selection and
initializtion of the required NTv2 file can be realized. For this purpose,
the required NTv2 files must be stored in a common directory with up to
three subdirectories. When changing to an NTv2-based Reference System, the
required NTv2 file is searched there. If the file is present in the common
directory, it is initialized automatically.

To close an already opened NTv2-grid file and to release the corresponding
NTv2 instance in GeoDLL, the function closentvbinaryfile() can be used. But
this is only necessary in special cases. Please read the function description.

You can download the NTv2 files supported by GeoDLL directly from the
KilletSoft website http://www.killetsoft.de/p_gdln_e.htm#download or use the
download links to the original sources there.. On that Internet site you
also find a detailed description of the NTv2 standard.

The file name may contain a drive letter, a directory path and a file name
extension. The file name extension for NTv2 binary files is by standard "gsb".
Example: "c:\calculations\ntv2_files\beta2007.gsb".
Attention, in C syntax double backslashes must be used!


The parameters are passed and/or returned as follows:
pszFileBinary File name of an NTv2 binary file.
              The file name may contain a drive letter, a directory path
              and a file name extension.

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.