Prototype and description of the function coordtransextraind()

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

 

coordcalcextraind()
Calculation of Extra Pparameters independent from coordinate transformations.
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 coordcalcextraind(
     double nCoordX,
     double nCoordY,
     const char *pszCoord,
     double nEllHgt,
     unsigned short nCoordSys,
     unsigned short nRefSys,
     unsigned short nUnit,
     unsigned short nStrip,
     unsigned long lNoStrip,
     unsigned long l3D,
     double *nGeoLon,
     double *nGeoLat,
     double *nOrigin,
     double *nConvergence);

Prototype of the DLL function in Visual Objects syntax:
_DLL function coordcalcextraind(;
     nCoordX as real8,;                    // 8 Byte
     nCoordY as real8,;                    // 8 Byte
     pszCoord as psz,;                     // 4 Byte, char*
     nEllHgt as real8,;                    // 8 Byte
     nCoordSys as word,;                   // 2 Byte
     nRefSys as word,;                     // 2 Byte
     nUnit as word,;                       // 2 Byte
     nStrip as word,;                      // 2 Byte
     lNoStrip as logic,;                   // 4 Byte
     l3D as logic,;                        // 4 Byte
     nGeoLon ref real8,;                   // 4 Byte
     nGeoLat ref real8,;                   // 4 Byte
     nOrigin ref real8,;                   // 4 Byte
     nConvergence ref real8);              // 4 Byte
as logic pascal:geodll32.coordcalcextraind  // 4 Byte


The function calculates the Extra Parameters Meridian Convergence, Origin
Center Meridian and Geographical Point Coordinate for a coordinate in any
coordinate Reference System (CRS). In contrast to the function
coordcalcextra(), the use of the setcalcextra() function is not required.

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

Coordinates in arbitrary coordinate Reference Systems (CRS) can always be
converted into Geographical Point Coordinates.

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
Geographical Point. It can be calculated e.g. for all Mercator and Lambert
projections.

Note that the calculation of Extra Parameters is not possible with every
coordinate transformation. In this case, 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 the Extra Parameters have the value -9999.

For transferring the numerical coordinate nCoordX / nCoordY or the
alphanumeric coordinate pszCoord as well as the CRS settings nCoordSys,
nRefSys, nUnit, nStrip and lNoStrip please read the detailed notes in the
description of the function coordtransex().


The parameters are returned as follows:
nCoordX       Longitude, East or X component of the numeric coordinate.
              During processing of an alphanumeric coordinate this
              parameter is without meaning. The input format of the
              coordinate (notation) is described in the list "Defaults
              of the Coordinate Systems".

nCoordY       Latitude, North or Y component of the numeric coordinate.
              During processing of an alphanumeric coordinate this
              parameter is without meaning. The input format of the
              coordinate (notation) is described in the list "Defaults
              of the Coordinate Systems".

pszCoord      Alphanumeric source coordinate.
              During processing of a numeric coordinate this parameter is
              without meaning. In this case for pszCoordQ a NULL pointer
              can be passed. The input format of the coordinate (notation)
              is described in the list "Defaults of the Coordinate
              Systems".

nEllHgt       Ellipsoidical height of the target coordinate
(ref)           or
              Z component of a cartesian coordinate.
              With 3D transformations in the case of using different source
              and target Reference Systems (nRefSysQ, nRefSysZ), the
              ellipsoidical height of the target coordinate is calculated.

nCoordSys     Coordinate System of the coordinate.
              (see list "Coordinate Reference Systems").

nRefSys       Geodetic Reference System of the coordinate.
              (see list "Coordinate Reference Systems").

nUnit         Measurement Unit of the coordinate.
0             The coordinate components are specified in a standard
              Measurement Unit, as for the Coordinate System preset in
              GeoDLL. If necessary, they are translated in meters for
              internal use.
              (see list "Default settings" [source code: settings_e.txt]).
› 0           The coordinate components are specified in a particular
              Measurement Unit and are translated in meters for internal
              use.
              (see list "Coordinate Reference Systems alphabetical"
              [source: sysalpha_e.txt]).
1000          No effect. The coordinate components are not converted to
              another Measurement Unit.

nStrip        Meridian strip to use with the Coordinate System.
              This parameter has only an effect, if a "Transversal Mercator
              meridian strip system" is registered in nCoordSys.
0             Using of the leading digits of the easting for the
              calculation of the natural meridian strip.
› 0           Using of the value in nStrip for the calculation of the
              natural meridian strip.

lNoStrip      Setting for the suppressing of the meridian strip number in
              the eastings. This parameter has only an effect, if a
              "Transversal Mercator meridian strip system" is registered in
              nCoordSys.
TRUE          Eastings must be passed without leading meridian strip
              numbers.
FALSE         Eastings must be passed with leading meridian strip numbers.

l3D           Setting for coordinate transformation in 3D mode. When the
              3D mode is on, a value must be passed in nEllHgt.
TRUE          Execution as 3D coordinate transformation.
FALSE         Execution as 2D coordinate transformation.

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

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

nOrigin        Longitude of Origin Center.
               Or -9999, if the value could not be calculated.

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

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


The following topics are explained in detail in the descriptions of the
functions coordtransex() .and. coordtrans3dex():
  Range validity
  Notations
  Standard Reference Systems
  3D Coordinate Transformation


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.