Prototype and description of the function getntvbinaryfile()

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

 

getntvbinaryfile()
Determination of up to three NTv2 file names matching a reference system.

Prototype of the DLL function in C++ syntax (attend lower case!):
__declspec(dllimport) unsigned long __stdcall getntvbinaryfile(
     unsigned short wRefSys,
     char **pszNtvFileName1,
     char **pszNtvFileName2,
     char **pszNtvFileName3);

Prototype of the DLL function in Visual Objects syntax:
_DLL function getntvbinaryfile;
     (sRefSys as word,;                    // 2 Byte
     pszNtvFileName1 ref psz,;             // 4 Byte, char**, 25 alloc.
     pszNtvFileName2 ref psz,;             // 4 Byte, char**, 25 alloc.
     pszNtvFileName3 ref psz);             // 4 Byte, char**, 25 alloc.
as logic pascal:geodll32.getntvbinaryfile


The function returns up to three NTv2 file names matching a NTv2-based
reference system. The first file name is usually used. It may be followed by
a second, alternatively used file name. The last file name is used for a by
KilletSoft encrypted NTv2 file.

With the functions getntvbinaryfile() and setntvbinautofile() respective
setntvbinaryfile() 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. When changing to a NTv2-based reference
system, the name of the required NTv2 file is determined by the function
getntvbinaryfile(). If the file is present in the common directory, it is
initialized there with the functions setntvbinautofile() or
setntvbinaryfile().

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. Alternatively, the
function setntvbinautofile() can be used, which stores the NTv2 file name
only in a waiting position. Testing and the allocation of memory space takes
place primary with the first NTv2 Reference System Transition.


The parameters are passed and/or returned as follows:
wRefSysQ    NTv2 supported Reference System. The available reference system
            are specified in the list "Coordinate and Reference systems".

pszNtvFileName1  First possible NTv2 filename for the corresponding Grid
(ref)       Shift File.
            Note: "ref pszNtvFileName1" corresponds to "char**" in C. 25 bytes
            of memory for the zero terminated string must be allocated with
            dependence to the call of the function setstringallocate().
            Please consider the notes in the description of the  function
            setstringallocate().

pszNtvFileName2  Second possible NTv2 filename for the corresponding Grid
(ref)       Shift File.
            Note: "ref pszNtvFileName2" corresponds to "char**" in C. 25 bytes
            of memory for the zero terminated string must be allocated with
            dependence to the call of the function setstringallocate().
            Please consider the notes in the description of the function
            setstringallocate().

pszNtvFileName3  Third possible NTv2 filename for the corresponding Grid
(ref)       Shift File.
            Note: "ref pszNtvFileName3" corresponds to "char**" in C. 25 bytes
            of memory for the zero terminated string must be allocated with
            dependence to the call of the function setstringallocate().
            Please consider the notes in the description of the function
            setstringallocate().

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


Freischaltung:
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.