Prototype and description of the function vincentyinverse()

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

vincentyinverse()
Distance and bearings on the earth ellipsoid by two given points (Vincenty
inverse formula).

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall vincentyinverse(
     double nGeoLon1,
     double nGeoLat1,
     double nGeoLon2,
     double nGeoLat2,
     double *nDistance,
     double *nAzimut1,
     double *nAzimut2,
     unsigned short nEllipsoid);

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


The function calculates the distance on the earth ellipsoid between two
geographical coordinates and the forward bearing and backward bearing
(azimuths) between the two points. The calculation uses the geographical
coordinates of a starting point and of the destination point. This
calculation in the geodesy is also referred to as "Inverse Position
Computation".

The "Vincenty Inverse Formula" is used for the calculation on the earth
ellipsoid, which returns the result with high accuracy. Vincentys formulas
are working with an accuracy of 0.5 mm for the distance and 0.000015
seconds for the azimuthal bearings. Two nearly antipodal points (on the
globe nearly opposite) can not be calculated with this formula and result
in an error.

Source:
Vincenty direct formula - Thaddeus Vincenty,
"Direct and Inverse Solutions of Geodesics on the Ellipsoid with
application of nested equations",
Survey Review, Vol XXII no 176, 1975.

The geographic coordinates nGeoLon1 (longitude of the first point) and
nGeoLat1 (latitude of the first point) as well as the geographic
coordinates nGeoLon2 (longitude of the second point) and nGeoLat2
(latitude of the second point) must be passed in [degrees]-notation
[vggg.ggg] to the function.

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. In nAzimut1 the forward bearing from point 1 to
point 2 in [degrees]-notation [vggg.ggg] is returned. nAzimut2 contains
the backward bearing from point 2 in direction of point 1. The bearing
will be calculated in the range of 0 up to 360 degrees, where 0 degrees
points north and 90 degrees points east.


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

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

nGeoLon2    Geographic longitude of the second point in [degrees] notation
            vggg.ggg

nGeoLat2    Geographic latitude of the second point in [degrees] notation
            vgg.ggg

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

nAzimut1    Forward bearing from point 1 in direction to point 2 in
(ref)       [degrees] notation ggg.ggg as result

nAzimut2    Backward bearing from point 2 in direction to point 1 in
(ref)       [degrees] notation ggg.ggg as result

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:
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.