Prototype and description of the function distanceutm()

(Function of the unlock requiring group "Distance calculations")

distanceutm()
Distance on the earth ellipsoid in meters between two UTM coordinates.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall distanceutm(
     double nUtmEast1,
     double nUtmNorth1,
     double nUtmEast2,
     double nUtmNorth2,
     double *nDistance,
     unsigned short nEllipsoid)

Prototype of the DLL function in Visual Objects syntax:
_DLL function distanceutm(;
     nUtmEast1 as real8,;                 // 8 Byte
     nUtmNorth1 as real8,;                // 8 Byte
     nUtmEast2 as real8,;                 // 8 Byte
     nUtmNorth2 as real8,;                // 8 Byte
     nDistance ref real8,;                // 4 Byte
     nEllipsoid as word);                 // 4 Byte
as logic pascal:geodll32.distanceutm      // 4 Byte


The function calculates the distance on the earth ellipsoid between two UTM
coordinates and returns it as distance in meters

The Vincenty Inverse Formula is used for the distance calculation on the earth
ellipsoid, which computes the result with high accuracy.

The UTM coordinates nUtmEast1 / nUtmNorth1 and nUtmEast2 / nUtmNorth2 must be
passed to the function. The easting values must contain the UTM strip number.
The coordinate pairs may be located on the same meridian strips or on
neighboring meridian strips. However, they must be on the same earth
hemisphere.

In nEllipsoid the necessary ellipsoid is passed. If in nEllipsoid the value 0
is passed, then the geodetic ellipsoid WGS84 is used. If in nEllipsoid the
value 1000 is passed, the function uses the semi axes of the user-defined
earth ellipsoid passed before by the function setuserellsource().

The result of the distance calculation is returned in the parameter nDistance
in meters.


The parameters are passed and/or returned as follows:
nUtmEast1   UTM easting of the first coordinate point.

nUtmNorth1  UTM northing of the first coordinate point.

nUtmEast2   UTM easting of the second coordinate point.

nUtmNorth2  UTM northing of the second coordinate point.

nDistance   Distance between the points in meters as result of the
(ref)       computation

nEllipsoid  Geodetic ellipsoid.
            The ellipsoid numbers are specified at the bottom part of
            the list "Systems sorted alphabetical". The numbers of
            the Reference Systems specified in the list
            "Systems sorted by countries" can be used also.

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


Unlocking:
This function is a component of the unlock requiring function group
"distance calculations". 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.