Prototyp und Beschreibung der Funktion setntvbinautodir()

(Funktion der freischaltpflichtigen Gruppe "NTv2-Transformationen")

setntvbinautodir()
Verzeichnis zur automatischen Verwendung von NTv2-Binärdateien setzen oder
zurücksetzen.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall setntvbinautodir(
     const char *pszBinaryDir);

Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function setntvbinautodir;
     (pszBinaryDir as psz)                 // 4 Byte, char*
as logic pascal:geodll32.setntvbinautodir  // 4 Byte


Mit der Funktion setntvbinautodir() kann eine automatische Auswahl und
Initialisierung der erforderlichen NTv2-Datei mit den dafür vorgesehenen
Dateinamen realisiert werden. Dazu müssen sich die benötigten NTv2-Dateien
in einem gemeinsamen Verzeichnis mit bis zu drei Verzeichnisebenen befinden.
Beim Wechsel zu einem NTv2-gestützten Bezugssystem wird die erforderliche
NTv2-Datei dort gesucht. Wenn die Datei im gemeinsamen Verzeichnis gefunden
worden ist, wird sie automatisch initialisiert.

Beim Aufruf von setntvbinautodir() wird eine eventuell noch vorhandene
NTv2-Instanz aufgelöst. Beim ersten NTv2-Bezugssystemwechsel bildet GeoDLL
dann automatisch eine neue NTv2-Instanz mit der automatisch gefundenen
NTv2-Datei. Dabei wird eine neue NTv2-Instanz unter Verwendung der dafür
benötigten NTv2-Datei erzeugt. Die NTv2-Instanz bleibt für weitere NTv2-
Berechnungen bestehen, bis ein anderes NTv2-Bezugssystem eingestellt wird.
Bei Aufrufen der Funktionen setntvbinaryfile() und setntvbinautofile() wird
die vorhandene NTv2-Instanz ebenfalls aufgelöst und durch eine neue ersetzt.

Für geodätische Berechnungen mit NTv2-Gitterdateien können der GeoDLL die
Pfade der Dateien mit weiteren Funktionen bekannt gemacht werden:

Mit der Funktion setntvbinaryfile() kann eine bestimmte NTv2-Datei in einem
beliebigen Verzeichnis gezielt initialisiert werden. Das ist z.B. notwendig,
wenn mit den GeoDLL-Bezugssystemen 208 und 209 eine beliebige, nicht implizit
von GeoDLL unterstützte NTv2-Datei initialisiert werden muss. Die Funktion
arbeitet aber auch mit allen implizit von GeoDLL unterstützten NTv2-Dateien.

Die Funktion setntvbinautofile() kann verwendet werden, um den Dateipfad nur
in einer Warteposition abzulegen. Die Prüfung und die Allokation von
Speicherplatz erfolgt dabei erst mit dem ersten NTv2-Bezugssystemwechsel.

Um eine geöffnete NTv2-Gitterdatei wieder zu schließen und die damit
verbundene NTv2-Instanz in GeoDLL freizugeben, kann die Funktion
closentvbinaryfile() verwendet werden. Das ist aber nur in besonderen Fällen
notwendig. Lesen Sie dazu bitte die Funktionsbeschreibung.  Alternativ kann
der NTv2-Dateipfad durch einen Aufruf dieser Funktion mit einem Null-String
als Parameter zurückgesetzt werden.

Sie können die von GeoDLL unterstützten NTv2-Dateien direkt von der
KilletSoft Internetseite http://www.killetsoft.de/p_gdln_d.htm#download
herunterladen oder dort die Verweise zu den Originalquellen verwenden. Auf
der Internetseite finden Sie auch eine ausführliche Beschreibung des
NTv2-Standards.

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 nach NTv2-Binärdateien
durchsucht.
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:
pszBinaryDir  Pfad eines gemeinsamen Verzeichnisses für NTv2-Binärdateien.
              Der Pfad darf einen Laufwerksbuchstaben und eine
              Verzeichniskette mit abschließendem Backslash enthalten.

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.