Prototype and description of the function coordcalcextra()

(Function of the unlock requiring group "Coordinate Transformations")

coordcalcextra()
Calculation of Extra Parameters during coordinate transformations with the
coordtrans*() functions.
Meridian Convergence, Origin Center and Geographical Point coordinate.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall coordcalcextra(
     double *nGeoLonQ,
     double *nGeoLatQ,
     double *nOriginQ,
     double *nConvergenceQ,
     double *nGeoLonZ,
     double *nGeoLatZ,
     double *nOriginZ,
     double *nConvergenceZ);

Prototype of the DLL function in Visual Objects syntax:
_DLL function coordcalcextra(;
     nGeoLonQ ref real8,;                  // 4 Byte
     nGeoLatQ ref real8,;                  // 4 Byte
     nOriginQ ref real8,;                  // 4 Byte
     nConvergenceQ ref real8,;             // 4 Byte
     nGeoLonZ ref real8,;                  // 4 Byte
     nGeoLatZ ref real8,;                  // 4 Byte
     nOriginZ ref real8,;                  // 4 Byte
     nConvergenceZ ref real8);             // 4 Byte
as logic pascal:geodll32.coordcalcextra    // 4 Byte


The function calculates additional (extra) parameters for each coordinate
transformation performed with functions of the type coordtrans*(). The
prerequisite for this is the previous activation of the calculations by
the function setcalcextra(). The Extra Parameters can be prompted after
each coordinate transformation.

The Extra Parameters calculated by a coordinate transformation are
retained until the function setcalcextra() with set parameter on TRUE is
called next time.

The following Extra Parameters are available:
   Longitude of the Geographical Point coordinate in the source system.
   Latitude of the Geographical Point coordinate in the source system.
   Longitude of Origin Center in the source System.
   Meridian Convergence at the Geographical Point in the source system.
   Longitude of the Geographical Point coordinate in the target system.
   Latitude of the Geographical Point coordinate in the target system.
   Longitude of Origin Center in the target System.
   Meridian Convergence at the Geographical Point in the target system.

Coordinates in arbitrary coordinate Reference Systems (CRS) can always be
converted into Geographical Point Coordinates. They are available for the
source system and for the target system.

The Longitude of Origin Center is the north-aligned central meridian of the
Coordinate System.

The Meridian Convergence is often also referred as map convergence or grid
convergence. The Meridian Convergence is the angle between the north
direction of the coordinate grid and the geographic north direction at the
Origin Center. It can be calculated e.g. for all Mercator and Lambert
projections. The convergence is available for the source system and for the
target system.

Note that the calculation of some Extra Parameters is not possible with
every coordinate transformation. In these cases, the values -9999 are
returned for the corresponding Extra Parameters.

The Meridian Convergence and the Central Meridian are currently supported
by the following systems:
  All Transversal Mercator systems
  All normal Mercator systems
  All Lambert Conformal Conic systems

If no Extra Parameters could be calculated, the function is terminated with
the return value FALSE and all Extra Parameters have the value -9999.

This function may be extended in later GeoDLL versions. Please ensure the
correct parameter passing after you have installed an update!


The parameters are returned as follows:
nGeoLonQ       Geographical longitude in decimal notation calculated from
(ref)          the source coordinate (Geographical Point).
               Or -9999, if the value could not be calculated.

nGeoLatQ       Geographical latitude in decimal notation calculated from
(ref)          the source coordinate (Geographical Point).
               Or -9999, if the value could not be calculated.

nOriginQ       Longitude of Origin Center in the source system.
               Or -9999, if the value could not be calculated.

nConvergenceQ  Meridian Convergence at the Geographical Point in the source
(ref)          system.
               Or -9999, if the value could not be calculated.

nGeoLonZ       Geographical longitude in decimal notation calculated from
(ref)          the target coordinate (Geographical Point).
               Or -9999, if the value could not be calculated.

nGeoLatZ       Geographical latitude in decimal notation calculated from
(ref)          the target coordinate (Geographical Point).
               Or -9999, if the value could not be calculated.

nOriginZ       Longitude of Origin Center in the target system.
               Or -9999, if the value could not be calculated.

nConvergenceZ  Meridian Convergence at the Geographical Point in the target
(ref)          system.
               Or -9999, if the value could not be calculated.

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


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