Prototype and description of the function point2pointsphere()

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

point2pointsphere()
Calculation of a destination point on the earth sphere by given start
point, bearing and distance.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall point2pointsphere(
     double nGeoLon1,
     double nGeoLat1,
     double nDistance,
     double nAzimut,
     double *nGeoLon2,
     double *nGeoLat2)

Prototype of the DLL function in Visual Objects syntax:
_DLL function point2pointsphere(;
     nGeoLon1 as real8,;                   // 8 Byte
     nGeoLat1 as real8,;                   // 8 Byte
     nDistance as real8,;                  // 8 Byte
     nAzimut as real8,;                    // 8 Byte
     nGeoLon2 ref real8,;                  // 4 Byte
     nGeoLat2 ref real8);                  // 2 Byte
as logic pascal:geodll32.point2pointsphere // 4 Byte


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

For the earth surface a sphere with the radius 6371.221 km is taken as basic.
Since the function does not consider the ellipsoidal surface of the earth,
inevitably a minimum deviation from the exact distance results. More exact
results are reached by much lower calculation speed with the function
point2pointgeo().

The geographic coordinate nGeoLon1 (longitude) and nGeoLat1 (latitude) of the
start point as well as the forward bearing nAzimut from the start point to the
destination point must be passed in [degrees]-notation [vggg.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 as meters by the parameter nDistance.

The function returns as results the geographic coordinates nGeoLon2
(longitude) and nGeoLat2 (latitude)  of the destination point in [degrees]-
notation [vggg.ggg].

The parameters are passed and/or returned as follows:
nGeoLon1    Geographic longitude of the start point in [degrees] notation
            vggg.ggg

nGeoLat1    Geographic latitude of the start point in [degrees] notation
            vgg.ggg

nDistance   Distance between the points in meters on the earth phere

nAzimut     Forward bearing from point 1 in direction to point 2 in
            [degrees] notation ggg.ggg

nGeoLon2    Geographic longitude of the destination point in [degrees] notation
(ref)       vggg.ggg as result

nGeoLat2    Geographic latitude of the destination point in [degrees] notation
(ref)       vggg.ggg as result

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


For geographic coordinates in [degrees] notation applies:
v           Optional sign for longitudes west of Greenwich and latitudes
            south of the equator.
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.