Prototyp und Beschreibung der Funktion getepsg2geodll()

(Funktion der freischaltpflichtigen Gruppe "Parameterermittlung")

 

getepsg2geodll()
Ermittlung der zu einem EPSG-Code äquivalenten GeoDLL-Codes.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall getepsg2geodll(
    unsigned short nEpsg,
    unsigned short *nCoordSys,
    unsigned short *nRefSys,
    unsigned short *nStrip,
    unsigned long *lNoStrip,
    unsigned long *l3D,
    unsigned short *nUnit,
    char **pszConti,
    char **pszCountry);

Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function getepsg2geodll(;
     nEpsg as word,;                       // 2 Byte
     nCoordSys ref word,;                  // 4 Byte
     nRefSys ref word,;                    // 4 Byte
     nStrip ref word,;                     // 4 Byte
     lNoStrip ref logic,;                  // 4 Byte
     l3D ref logic,;                       // 4 Byte
     nUnit ref word,;                      // 4 Byte
     pszConti ref psz,;                    // 4 Byte, char**, 3 alloc.
     pszCountry ref psz);                  // 4 Byte, char**, 6 alloc.
as LOGIC PASCAL:geodll32.getepsg2geodll    // 4 Byte

Die Allokation von Speicher für "ref psz" / "char**" ist nur notwendig,
wenn zuvor setstringallocate(FALSE) aufgerufen worden ist.


Die Funktion ermittelt zu einem als EPSG-Code übergebenen Koordinaten-
bezugssystem die dazu äquivalenten GeoDLL-Codes für das Koordinatensystem,
das Bezugssystem und für die verwendete Maßeinheit. Zusätzlich werden für
das EPSG-Koordinatenbezugssystem die Meridianstreifennummer und ein Flag
für deren Verwendung, sowie ein Flag für die Projektionsart 2D oder 3D
zurückgegeben. Zum Zweck der räumlichen Zuordnung des EPSG-Koordinaten-
bezugssystems werden Kennungen für den Kontinent und für das Land ermittelt.
Die ermittelten GeoDLL-Codes und Eigenschaften können direkt an andere
GeoDLL-Funktionen, wie z.B. coordtrans(), als Parameter übergeben werden.

EPSG ist die Abkürzung für "European Petroleum Survey Group Geodesy". Das
ist eine Arbeitsgruppe der europäischen Öl- und Gaserkundungsunternehmen.
Die EPSG und deren Nachfolger OGP "International Association of Oil and Gas
Producers" haben es sich zur Aufgabe gemacht, ein Systems mit weltweit
eindeutigen Schlüsselnummern (EPSG-Codes) geodätischer Daten wie
Koordinatenbezugssysteme, Referenzellipsoide oder Kartenprojektionen
aufzubauen.

Die Funktion getepsg2geodll() ermittelt die äquivalent zu einem EPSG-
Koordinatenbezugssystem passenden Nummern des GeoDLL-Koordinatensystems
und des GeoDLL-Bezugssystems. Es wird ausdrücklich darauf hingewiesen,
dass von GeoDLL nicht immer genau dieselben Parameter für die Koordinaten-
transformation und für den Bezugssystemwechsel verwendet werden, wie sie in
der EPSG-Datenbank vorhanden sind. Der Grund dafür ist, dass manche EPSG-
Parametersätze nicht den Qualitätsansprüchen von KilletSoft genügen. GeoDLL
verwendet meist Parametersätze, die von den jeweiligen Vermessungs-
verwaltungen veröffentlicht oder KilletSoft aus erster Hand zur Verfügung
gestellt oder dort eingekauft worden sind. KilletSoft hat im Laufe der
Jahre eine eigene qualitativ hochwertige Datensammlung mit exakten
geodätischen Parametersätzen angelegt. Da die EPSG-Kodierung in vielen
GIS-Systemen verwendet wird und dadurch einen hohen Bekanntheitsgrad
erhalten hat, stellen wir einige Funktionen zur Verfügung, welche die
Auswahl der benötigten Koordinatensysteme und Bezugssysteme bei der
Programmierung mit GeoDLL vereinfachen.

Funktionen mit EPSG-Codierung:
coordtransepsg()   Koordinatentransformation mit EPSG-Codes
getepsg2geodll()   Diese Funktion
getepsgcrsname()   Ermittlung der Bezeichnung eines EPSG-CRS


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
nEpsg       Kennung des EPSG-Koordinatenbezugssystems für das die GeoDLL-
            Kennungen ermittelt werden sollen.

nCoordSys   Referenz auf die die GeoDLL-Kennung für das äquivalente
(ref)       Koordinatensystem.

nRefSys     Referenz auf die die GeoDLL-Kennung für das äquivalente
(ref)       Bezugssystem.

nStrip      Referenz auf die GeoDLL-äquivalente Meridianstreifennummer
(ref)       bei Meridianstreifensystemen.

lNoStrip    Referenz auf ein Flag für die Unterdrückung der Meridian-
(ref)       streifennummer im Ostwert. Dieser Parameter kann nur dann TRUE
            sein, wenn in nCoordSys ein "Transversales Mercator Streifen-
            system" eingetragen ist.
TRUE (1)    Ostwerte werden ohne führende Meridianstreifennummer berechnet.
FALSE (0)   Ostwerte werden mit führender Meridianstreifennummer berechnet.

l3D         Referenz auf ein Flag für die Darstellung der Koordinaten
(ref)       mit der dritten Koordinatenkomponente "Ellipsoidische Höhe".
TRUE (1)    Koordinaten werden mit dritter Koordinatenkomponente berechnet.
FALSE (0)   Koordinaten werden ohne dritte Koordinatenkomponente berechnet.

nUnit       Referenz auf die GeoDLL-Kennung für die Maßeinheit, die für die
(ref)       Koordinaten verwendet wird.
            00 = Ohne Auswirkung
            01 = Internationales Meter
            02 = Legales Meter
            03 = Internationales Fuß
            04 = US Survey Fuß
            05 = Britisches Fuß
            06 = Indisches Fuß
            07 = Preußisches Fuß
            08 = Internationales Yard
            09 = US Survey Yard
            10 = Britisches Yard
            11 = Indisches Yard
            12 = Kilometer
            13 = Seemeile
            14 = Landmeile

pszConti    Referenz auf die alphanumerische Kennung für den Kontinent.
(ref)       AF = Afrikanischer Kontinent
            AS = Asiatischer Kontinent
            AA = Australasiatischer Kontinent
            EU = Europäischer Kontinent
            NA = Nordamerikanischer Kontinent
            MA = Mittelamerika und Karibik
            SA = Südamerikanischer Kontinent
            #I = Weltweite Systeme
            Achtung: "ref pszConti" entspricht "char**" in C. Es müssen
            3 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()".

pszCountry  Referenz auf die alphanumerische Kennung für das Land.
(ref)       Die zweistelligen alphanumerischen Kennungen in Großschreibung
            entsprechen dem "ISO 3166-1 alpha-2"-Code.
            URL: http://en.wikipedia.org/wiki/ISO_two-letter_country_codes
            Sonderkennungen:
            #I = Internationale Systeme
            #M = Multinationale Systeme
            Die zweistelligen Länderkennungen können zusätzlich durch eine
            mit Bindestrich abgesetzte Regionskennung erweitert sein. Das wird
            beispielsweise bei den einzelnen Staaten der USA angewendet.
            Beispiele:
            DE    = Deutschland
            US-AL = USA Alabama
            Achtung: "ref pszCountry" entspricht "char**" in C. Es müssen
            6 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()".

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


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.