Prototype and description of the function point2pointutm()

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

point2pointutm()
Calculation of a UTM destination point on the earth ellipsoid by given
UTM start point, bearing and distance.

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

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


The function calculates the UTM coordinates of a destination point on the
earth ellipsoid. The calculation uses the UTM coordinates of a start point,
its forward bearing (azimuth) and the distance in meters between the points.

The "Vincenty Direct Formula" is used for the calculation on the earth
ellipsoid, which returns the result with high accuracy.

The UTM coordinate nUtmEast1 / nUtmNorth1 of the start point must be passed to
the function. The easting value must contain the UTM strip number. The forward
bearing nAzimut from the start point to the destination point must be passed
in [degrees]-notation [ggg.ggg] to the function. The bearing must be in the
range of 0 up to 360 degrees, where 0 degrees points north and 90 degrees
points east. The distance between the points must be passed in meter with the
parameter nDistance.

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 function returns as result the UTM coordinate nUtmEast2 (UTM easting) and
nUtmNorth2 (UTM northing) of the destination point. The Easting includes the
UTM zone number.

The parameters are passed and/or returned as follows:
nUtmEast1   UTM easting of the start point in meters including the UTM zone
            number

nUtmNorth1  UTM northing of the start point in meters

nDistance   Distance between the points in meters on the earth ellipsoid

nAzimut     Forward bearing from the start point in direction of the
            destination point in [degrees] notation ggg.ggg

nUtmEast2   UTM easting of the destination point in meters including the UTM
(ref)       zone number as result

nUtmNorth2  UTM northing of the destination point in meters as result
(ref)

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.


For geographic coordinates in [degrees] notation applies:
g           degrees and decimal fraction of a degree.


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.