Prototyp und Beschreibung der Funktion getcoordform3d()

(Funktion der freischaltpflichtigen Gruppe " Parameterermittlung")

 

getcoordform3d()
Ermittlung der Schreibweisen der Ost-, Nord- und Höhenkomponenten
eines 3D Koordinatensystems.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllexport) unsigned long __stdcall getcoordform3d(
     unsigned short wCoordSys,
     unsigned short wCoordLength,
     unsigned short wHeightLength,
     char **pszCoordFmEa,
     unsigned short *wCoordLgEa,
     char **pszCoordFmNo,
     unsigned short *wCoordLgNo,
     char **pszCoordFmHgt,
     unsigned short *wCoordLgHgt,
     unsigned short *wCoordTyp);

Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function getcoordform3d(;
     wCoordSys as word,;                   // 2 Byte
     wCoordLength as word,;                // 2 Byte
     wHeightLength as word,;               // 2 Byte
     pszCoordFmEa ref psz,;                // 4 Byte, char**, 30 alloc.
     wCoordLgEa ref word,;                 // 4 Byte
     pszCoordFmNo ref psz,;                // 4 Byte, char**, 30 alloc.
     wCoordFmNo ref word,;                 // 4 Byte
     pszCoordFmHgt ref psz,;               // 4 Byte, char**, 30 alloc.
     wCoordFmHgt ref word,;                // 4 Byte
     wCoordTyp ref word);                  // 4 Byte
as logic pascal:geodll32.getcoordform3d    // 4 Byte

Die Allokation von Speicher für die zurückzugebenden psz ist nur dann
wenn zuvor setstringallocate(FALSE) aufgerufen worden ist.


Die Funktion gibt die Schreibweisen (Notationen) der Ost-, Nord und
Höhenkomponenten des in wCoordSys übergebenen 3D-Koordinatensystems in
den Stringparametern pszCoordFmEa (Ostkomponente), pszCoordFmNo
(Nordkomponente) und pszCoordFmHgt (Höhenkomponente) zurück. Bei
kartesischen Koordinaten wird statt der Notation der ellipsoidischen
Höhenkomponente die Notation der kartesischen Z-Komponente zurückgegeben.
Die Notationen werden durch das Hinzufügen von Nachkommastellen auf die
in wCoordLength (Ost- und Nordkomponenten) und wHeightLength
(Höhenkomponente) angegebene Größe expandiert. Die Notationen der
alphanumerische Koordinaten werden nicht expandiert. Die mindestens
erforderliche Anzahl von Ziffern oder Zeichen für die Ost- und
Nordkomponenten werden in den Parametern wCoordLgEa und wCoordLgNo
zurückgegeben, die der Höhenkomponente im Parameter wCoordLgHgt. Die
Notationsstrings werden in der zuvor mit der Funktion setLanguage()
gesetzten Sprache zurückgegeben.


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
wCoordSys   Koordinatensytem, für das die Notationen ermittelt werden
            sollen. Die verfügbaren Koordinatensysteme sind in der
            Liste "Koordinatenbezugssysteme" aufgeführt.

wCoordLength  Länge, auf die die Ost- und Nordnotationen durch Hinzufügen
            von Nachkommastellen expandiert werden. Die Übergabe einer Null
            bewirkt die Darstellung dieser Notationen mit nur einer
            Nachkommastelle. Die Eingabe des Wertes 1000 bewirkt die
            Darstellung ohne Nachkommastellen.

wHeightLength  Länge, auf die die Höhennotation durch Hinzufügen von
            Nachkommastellen expandiert wird. Die Übergabe einer Null
            bewirkt die Darstellung dieser Notationen mit nur einer
            Nachkommastelle. Die Eingabe des Wertes 1000 bewirkt die
            Darstellung ohne Nachkommastellen.

pszCoordFmEa  Der String für die Notation der Ostkomponente der Koordinate
(ref)       wird per Referenz zurückgegeben. Das genaue Format der Notation
            ist in der Liste "Standardwerte der Koordinatensysteme" aufgeführt.
            Achtung: "ref pszCoordFmEa" entspricht "char**" in C. Es müssen
            30 Byte Speicher für den Null terminated string in Abhängigkeit
            vom Aufruf der Funktion setstringallocate() allokiert werden.
            Beachten Sie dazu die Hinweise in der Beschreibung der Funktion
            setstringallocate()".

wCoordLgEa  Die mindestens erforderliche Anzahl von Ziffern oder Zeichen
(ref)       für die Ostkomponente der Koordinate wird per Referenz
            zurückgegeben.

pszCoordFmNo  Der String für die Notation der Nordkomponente der Koordinate
(ref)       wird per Referenz zurückgegeben. Das genaue Format der Notation
            ist in der Liste "Standardwerte der Koordinatensysteme" aufgeführt.
            Achtung: "ref pszCoordFmNo" entspricht "char**" in C. Es müssen
            30 Byte Speicher für den Null terminated string in Abhängigkeit
            vom Aufruf der Funktion setstringallocate() allokiert werden.
            Beachten Sie dazu die Hinweise in der Beschreibung der Funktion
            setstringallocate()".

wCoordLgNo  Die mindestens erforderliche Anzahl von Ziffern oder Zeichen
(ref)       für die Nordkomponente der Koordinate wird per Referenz
            zurückgegeben.

pszCoordFmHgt  Der String für die Notation der Höhenkomponente der Koordinate
(ref)       wird per Referenz zurückgegeben. Für die ellipsoidische Höhe ist das
            Format "±mmmmm" vorgegeben. Bei kartesischen Koordinaten atimmt die
            Notation der Z-Komponente mit denen in pszCoorFmEa und pszCoorFmNo
            überein.
            Achtung: "ref pszCoordFmNo" entspricht "char**" in C. Es müssen
            30 Byte Speicher für den Null terminated string in Abhängigkeit
            vom Aufruf der Funktion setstringallocate() allokiert werden.
            Beachten Sie dazu die Hinweise in der Beschreibung der Funktion
            setstringallocate()".

wCoordLgHgt  Die mindestens erforderliche Anzahl von Ziffern oder Zeichen
(ref)       für die Höhenkomponente der Koordinate wird per Referenz
            zurückgegeben.

wCoordTyp   Der Typ des Koordinatensystems wird per Referenz zurückgegeben:
(ref)       0 = Numerisches Koordinatensystem
            1 = Alphanumerisches Koordinatensystem

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


Die zurückgegebenen Notationen und Werte sehen je nach dem gewählten
Koordinatensystem und der gewünschten Rückgabelänge für die Ost- und
Nordkomponenten (hier 10) und für die Höhenkomponente (hier 9) etwa so aus:
   Geographische Koordinaten [Grad, Min, Sek]:
      ±dddmmss.s     8  ±ddmmss.ss    7  ±mmmmm.mm   6  0
   oder Österreichische Gauß-Krüger-Koordinaten:
      kkkmmm.mm      6   kkkmmm.mm    6  ±mmmmm.mm   6  0
   oder British National grid:
      aaeeeeennnnn  12   ‹blank›      0  ±mmmmm.mm   6  1
   oder Kartesische Koordinaten:
      mmmmmmm.mm     7   mmmmmmm.mm   7  mmmmmmm.mm  7  0


Freischaltung:
Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe
"Parameterermittlung". 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.