Prototyp und Beschreibung der Funktion getntvbinaryfile()

(Funktion der freischaltpflichtigen Gruppe "NTv2-Transformationen")

getntvbinaryfile()
Ermittlung von bis zu drei zu einem Bezugssystem passenden NTv2-Dateinamen.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall getntvbinaryfile(
     unsigned short wRefSys,
     char **pszNtvFileName1,
     char **pszNtvFileName2,
     char **pszNtvFileName3);

Prototyp der DLL-Funktion 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  // 4 Byte


Die Funktion gibt bis zu drei für einem NTv2-gestützten Bezugssystem
vorgesehene NTv2-Dateinamen zurück. Der erste Dateiname wird üblicherweise
verwendet. Es kann ein zweiter, alternativ verwendeter Dateiname folgen. Der
letzte Dateiname wird für eine von KilletSoft verschlüsselte NTv2-Datei
verwendet.

Für geodätische Berechnungen mit NTv2-Gitterdateien müssen der GeoDLL die
Pfade der Dateien bekannt gemacht werden. Das wird mit drei alternativen
GeoDLL-Funktionen gemacht:

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 Dateifad nur
in einer Warteposition abzulegen. Die Prüfung und die Allokation von
Speicherplatz erfolgt dabei erst mit dem ersten NTv2-Bezugssystemwechsel.

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.


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.

pszNtvFileName1  Erster möglicher NTv2-Dateiname füer die korrespondierende
(ref)       Gitterdatei.
            Achtung: "ref pszNtvFileName1" entspricht "char**" in C. Es
            müssen 25 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()".

pszNtvFileName2  Zweiter möglicher NTv2-Dateiname füer die korrespondierende
(ref)       Gitterdatei.
            Achtung: "ref pszNtvFileName2" entspricht "char**" in C. Es
            müssen 25 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()".

pszNtvFileName3  Dritter möglicher NTv2-Dateiname füer die korrespondierende
(ref)       Gitterdatei.
            Achtung: "ref pszNtvFileName3" entspricht "char**" in C. Es
            müssen 25 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.