Prototyp und Beschreibung der Funktion getntvbinaryfile()

(Funktion der freischaltpflichtigen Gruppe "NTv2-Gitterdaten")

 

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

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
__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


Die Funktion gibt bis zu drei zu einem NTv2-gestützten Bezugssystem passende
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.

Mit den Funktionen getntvbinaryfile() und setntvbinaryfile() bzw.
setntvbinautofile() kann eine automatische Auswahl und Initialisierung der
erforderlichen NTv2-Datei realisiert werden. Dazu müssen sich die benötigten
NTv2-Dateien in einem gemeinsamen Verzeichnis befinden. Beim Wechsel zu einem
NTv2-gestützten Bezugssystem wird mit der Funktion getntvbinaryfile() der Name
der erforderlichen NTv2-Datei ermittelt. Wenn die Datei im gemeinsamen
Verzeichnis vorhanden ist, wird sie dort mit den Funktionen setntvbinaryfile()
oder setntvbinautofile() initialisiert.

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.
Alternativ kann auch die Funktion setntvbinautofile() verwendet werden,
die den Dateinamen nur in einer Warteposition ablegt. Die Prüfung und die
Allokation von Speicherplatz erfolgt dabei erst mit dem ersten NTv2-
Bezugssystemwechsel.


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 Gitterdaten". Sie wird zusammen mit den anderen Funktionen der Gruppe
durch die Eingabe der bei der Vertriebsfirma erworbenen Freischaltparameter
per Aufruf der Funktion setunlockcode() zur uneingeschränkten Nutzung frei
geschaltet. Ohne die Freischaltung sind nur wenige Funktionsaufrufe zu
Testzwecken (Sharewareprinzip) möglich. Es ist zu beachten, dass zusätzlich
die Funktionsgruppe "Koordinatentransformationen" frei geschaltet sein muss.