Prototype and description of the function getntvdirmatch()

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

getntvdirmatch()
Determination of a matching NTv2 file in a common directory.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getntvdirmatch(
     unsigned short wRefSys,
     const char *pszNtvDir,
     char **pszNtvDirFile);

Prototype of the DLL function in Visual Objects syntax:
_DLL function getntvdirmatch;
     (wRefSys as word,;                    // 2 Byte
     pszNtvDir as psz,;                    // 4 Byte, char*
     pszNtvDirFile ref psz);               // 4 Byte, char**, 125 alloc.
as logic pascal:geodll32.getntvdirmatch    // 4 Byte


GeoDLL supports the automatic assignment of the required NTv2 files from a
common directory with up to three directory levels. After passing the
directory path with the function setntvbinautodir(), the required NTv2 file
is searched every time when changing to an NTv2-supported Reference
System. If the file is present in the common directory, it is initialized
automatically for Ntv2 transformations.

Regardless of the call to the function setntvbinautodir(), the NTv2 binary
file matching the Reference System wRefSys can be found in the common
directory with the function getntvdirmatch(). The full path of the file
found in the directory pszNtvDir or its subdirectories is then returned in
pszNtvDirFile.

The path name may contain a drive letter and a directory path. The path name
should end with a backslash (\)
Example: "c:\calculations\ntv2_files\"
Attention, in C syntax double backslashes must be used!

Subdirectories are supported to the third level.
Example:
c:\calculations\ntv2_files\world.gsb
c:\calculations\ntv2_files\australia\A66_NAT.gsb
c:\calculations\ntv2_files\brasilia\SAD69_003.gsb
c:\calculations\ntv2_files\germany\beta2007.gsb
c:\calculations\ntv2_files\germany\berlin\ntv2berlin.gsb
c:\calculations\ntv2_files\germany\hessen\HeTa2010.gsb


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

pszNtvDir     Path of a common directory for NTv2 binary files.
              The path may must contain a drive letter and a directory path
              with a trailing backslash.

pszNtvDirFile Path and filename of NTv2 binary file matching the Ntv2-
(ref)         Reference System.
              Note: "ref pszNtvDirFile" corresponds to "char**" in C.
              125 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.


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.