Prototype and description of the function getepsg2geodll()

(Function of the unlock requiring group "Parameter determination")


Determination of the GeoDLL codes equivalent to an EPSG code.

Prototype of the DLL function in C++ syntax (attend lower case!):
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);

Prototype of the DLL function 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

The allocation of memory for "ref psz" / "char**" is necessary only if
setstringallocate(FALSE) is called before.

The function determines for a Coordinate Reference System, given as an EPSG
code, the equivalent GeoDLL codes for the Coordinate System, the reference
system and the used Measurement Unit. In addition, for the given EPSG
Coordinate Reference System the Meridian Strip Number and a flag for its
use, as well as a flag for the projection types 2D or 3D are returned. For
the purpose of the spatial area of use of the EPSG Coordinate Reference
System, identifiers for the continent and for the country will be returned.
The determined GeoDLL codes and properties can be passed directly as
parameters to other GeoDLL functions, e.g. coordtrans().

EPSG is the acronym for "European Petroleum Survey Group Geodesy". This is
a working group of the European oil and gas exploration companies. The EPSG
and their successors OGP "International Association of Oil and Gas
Producers" have made it to their task to build a system with globally
unique identitfiers (EPSG codes) for geodetic data, such as Coordinate
Reference Systems, Reference Ellipsoids or Map Projections.

The function getepsg2geodll() returns the appropriate codes of the GeoDLL
Coordinate System and the GeoDLL Reference System equivalent to an EPSG
Coordinate Reference System. It is expressly noted, that not always
exactly the same parameters for Coordinate Transformations and Reference
System Transitions are used by GeoDLL, as they are present in the EPSG
database. The reason for this is that some EPSG parameter sets do not meet
the quality standards of KilletSoft products. GeoDLL mostly uses parameter
sets which have been published by the respective survey administrations or
have made firsthand available to KilletSoft by them or even have been
purchased from them. KilletSoft has created its own high-quality data
collection of exact geodetic parameter sets over the past years. Since the
EPSG coding is used in many GIS and thus has obtained a high level of
awareness, we provide some functions, that simplifies the selection of the
required Coordinate Systems and Reference Systems while programming with

Functions using EPSG coding:
coordtransepsg()   Coordinate Transformation with EPSG code
getepsg2geodll()   This function
getepsgcrsname()   Determination of the designation of a EPSG CRS

The parameters are passed and/or returned as follows:
nEpsg       Code of the EPSG coordinate Reference System for which the
            GeoDLL codes are to be determined.

nCoordSys   GeoDLL code for an EPSG equivalent Coordinate System returned by
(ref)       reference.

nRefSys     GeoDLL code for an EPSG equivalent geodetic Reference System
(ref)       returned by reference.

nStrip      GeoDLL equivalent meridian strip number in meridian strip
(ref)       systems returned by reference.

lNoStripQ   Flag for the suppressing of the meridian strip number in
(ref)       the eastings returned by reference. This parameter can only be
            TRUE, if a "Transversal Mercator meridian strip system" is
            registered in nCoordSys.
TRUE (1)    Eastings are calculated without leading meridian strip numbers.
FALSE (0)   Eastings are calculated with leading meridian strip numbers.

l3D         Flag for displaying the coordinates with the third coordinate
(ref)       component "Ellipsoidal Height" returned by reference.
TRUE (1)    Coordinates are calculated with the third coordinate component.
FALSE (0)   Coordinates are calculated without third coordinate component.

nUnit       By reference returned GeoDLL code for the Measurement Unit used
(ref)       for the coordinates.
            00 = Without effect
            01 = International Meter
            02 = Legal Meter
            03 = International Foot
            04 = US Survey Foot
            05 = British Foot
            06 = Indian Foot
            07 = Prussian Foot
            08 = International Yard
            09 = US Survey Yard
            10 = British Yard
            11 = Indian Yard
            12 = Kilometer
            13 = Nautic Mile
            14 = Statute Mile

pszConti    Alphanumeric identifier for the continent returned by reference.
(ref)       AF = African continent
            AS = Asian continent
            AA = Australasian continent
            EU = European continent
            NA = North American continent
            MA = Central America and the Caribbian
            SA = South American continent
            WW = World-wide systems
            Note: "ref pszConti" corresponds to "char**" in C. 3 bytes of
            memory for the zero terminated string must be allocated with
            dependence to the call of the function setstringallocate().
            Please consider the notes in the description of the function

pszCountry  Alphanumeric identifier for the country returned by reference.
(ref)       The uppercase two-digit alphanumeric identifiers correspond to
            the "ISO 3166-1 alpha-2" code.
            Special Identifiers:
            #I = International Coordinate Reference Systems (continentwide)
            #M = Multinational Coordinate Reference Systems (continentwide)
            #G = Google/OSM World/Pixel/Tile coordinates (worldwide)
            #W = GPS Messungen - ITRS-Epochen (continentwide or worldwide)
            The two-digit country identifiers can be further enlarged by
            hyphenated region identifier. That is, for example, for the
            individual states of the USA done.
            DE    = Germany
            US-AL = USA Alabama
            Note: "ref pszCountry" corresponds to "char**" in C. 6 bytes of
            memory for the zero terminated string must be allocated with
            dependence to the call of the function setstringallocate().
            Please consider the notes in the description of the function

returnVal   In case of an error the function returns FALSE, otherwise TRUE.

This function is a component of the unlock requiring function group
"parameter determination". It is unlocked for unrestricted use together with
the other functions of the group by passing the unlock parameters, acquired
from the software distribution company, trough the function setunlockcode().
Without unlocking only a few function calls for test purposes (shareware
principle) are possible.