Prototyp und Beschreibung der Funktion getntvdirmatch()

(Funktion der freischaltpflichtigen Gruppe "NTv2-Transformationen")

getntvdirmatch()
Ermittlung einer passenden NTv2-Datei aus einem Sammelverzeichnis.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall getntvdirmatch(
     unsigned short wRefSys,
     const char *pszNtvDir,
     char **pszNtvDirFile);

Prototyp der DLL-Funktion 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 unterstützt die automatische Zuordnung der benötigten NTv2-Dateien
aus einem gemeinsamen Verzeichnis mit bis zu drei Verzeichnisebenen. Nach
der Übergabe des Verzeichnispfades mit der Funktion setntvbinautodir()
wird dort jedesmal beim Wechsel zu einem NTv2-gestützten Bezugssystem die
erforderliche NTv2-Datei gesucht. Wenn die Datei im gemeinsamen Verzeichnis
gefunden worden ist, wird sie automatisch für NTv2-Transformationen
initialisiert.

Unabhängig vom Aufruf der Funktion setntvbinautodir() kann mit der Funktion
getntvdirmatch() in dem gemeinsamen Verzeichnis eine zu dem Bezugssystem
wRefSys passende NTv2-Binärdatei aufgefunden werden. Der vollständige
Dateipfad der im Verzeichnis pszNtvDir oder dessen Unterverzeichnissen
gefundenen Datei wird dann in pszNtvDirFile zurückgegeben.

Der Verzeichnisname darf einen Laufwerksbuchstaben und eine Verzeichniskette
enthalten. Der Verzeichnisname muss mit einem Backslash (\) abschließen.
Beispiel: "c:\berechnungen\ntv2_dateien\".
Achtung, in C-Syntax müssen doppelte Backslashes verwendet werden!

Es werden Unterverzeichnisse bis in die dritte Ebene unterstützt.
Beispiel:
c:\berechnungen\ntv2_dateien\world.gsb
c:\berechnungen\ntv2_dateien\australien\A66_NAT.gsb
c:\berechnungen\ntv2_dateien\brasilien\SAD69_003.gsb
c:\berechnungen\ntv2_dateien\deutschland\beta2007.gsb
c:\berechnungen\ntv2_dateien\deutschland\berlin\ntv2berlin.gsb
c:\berechnungen\ntv2_dateien\deutschland\hessen\HeTa2010.gsb


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
wRefSys       NTv2-gestütztes Bezugssystem. Die verfügbaren Bezugssysteme
              sind in der Liste "Koordinatenbezugssysteme" aufgeführt.

pszNtvDir     Pfad eines gemeinsamen Verzeichnisses für NTv2-Binärdateien.
              Der Pfad darf einen Laufwerksbuchstaben und eine
              Verzeichniskette mit abschließendem Backslash enthalten.

pszNtvDirFile Pfad und Dateiname einer zu dem NTv2-Bezugssytem passenden
(ref)         NTv2-Binärdatei.
              Achtung: "ref pszNtvDirFile" entspricht "char**" in C. Es
              müssen 125 Byte Speicher für den Null terminated string in
              Abhängigkeit vom Aufruf der Funktion setstringallocate()
              allokiert werden. Beachten Sie dazu die Hinweise im Kapitel
              "Prototyp und Beschreibung der Funktion setstringallocate()".

returnWert    Im Fehlerfall gibt die Funktion FALSE zurück, sonst TRUE.


Freischaltung:
Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe
"NTv2-Transformationen". Sie wird zusammen mit den anderen Funktionen der
Gruppe durch die Eingabe der bei der Vertriebsfirma erworbenen Freischalt-
parameter per Aufruf der Funktion setunlockcode() zur uneingeschränkten
Nutzung frei geschaltet. Ohne die Freischaltung sind nur wenige Funktions-
aufrufe zu Testzwecken (Sharewareprinzip) möglich. Es ist zu beachten, dass
zusätzlich die Funktionsgruppe "Koordinatentransformationen" frei geschaltet
sein muss.