|
Prototype and description of the function getepsg2geodll() (Function of the unlock requiring group "Parameter determination") |
|
getepsg2geodll()
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
GeoDLL.
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) EU = European continent
NA = North American continent
MA = Central America and the Caribbian
SA = South American continent
AS = Asian continent
NO = Near East and Middle East
AF = African continent
AA = Australian continent
PI = Polynesia, Indonesia, Micronesia
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
setstringallocate().
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.
URL: http://en.wikipedia.org/wiki/ISO_two-letter_country_codes
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.
Examples:
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
setstringallocate().
returnVal In case of an error the function returns FALSE, otherwise TRUE.
Unlocking:
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.
|