Prototype and description of the function getcoordform()

(Function of the unlock requiring group "Parameter determination")

getcoordform()
Determination of the east and north component notations of a 2D
Coordinate System.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getcoordform(
     unsigned short wCoordSys,
     unsigned short wCoordLength,
     char **pszCoordFmEa,
     unsigned short *wCoordLgEa,
     char **pszCoordFmNo,
     unsigned short *wCoordLgNo,
     unsigned short *wCoordTyp);

Prototype of the DLL function in Visual Objects syntax:
_DLL function getcoordform(;
     wCoordSys as word,;                   // 2 Byte
     wCoordLength as word,;                // 2 Byte
     pszCoordFmEa ref psz,;                // 4 Byte, char**, 30 alloc.
     wCoordLgEa ref word,;                 // 4 Byte
     pszCoordFmNo ref psz,;                // 4 Byte, char**, 30 alloc.
     wCoordFmNo ref word,;                 // 4 Byte
     wCoordTyp ref word);                  // 4 Byte
as logic pascal:geodll32.getcoordform      // 4 Byte

The allocation of memory for "ref psz" / "char**" is necessary only if
setstringallocate(FALSE) is called before.


The function returns the east and north component notations of the
2D Coordinate System fitting to wCoordSys in the string parameters
pszCoordFmEa (east component) and pszCoordFmNo (north component). The
notations are expanded by adding decimal places to the size indicated in
wCoordLength. The notations of alphanumeric coordinates are not expanded.
The minimum  number of digits or characters necessary for the east and
north components are returned in the parameters wCoordLgEa and wCoordLgNo.
The notations are returned in the language set by the function
setLanguage() before.


The parameters are passed and/or returned as follows:
wCoordSys   Coordinate System, for which the notations are to be
            determined. The available Coordinate Systems are specified in
            the list "Coordinate Reference Systems".

wCoordLength  Length, to which the notations are expanded by adding
            decimal places. Passing a zero causes the representation of
            the notations with only one decimal place. Passing the value
            1000 causes the representation without any decimal places.

pszCoordFmEa  The string with the notation of the east component of the
(ref)       coordinate is returned by reference. The exactly format of the
            notation is described in the list "Defaults of the coordinate
            systems".
            Note: "ref pszCoordFmEa" corresponds to "char**" in C. 30 bytes
            of memory for the zero terminated string must be allocated with
            dependence to the call of the function setstringallocate().
            Please consider the notes in the description of the function
            setstringallocate().

wCoordLgEa  The minimum  number of digits or characters necessary for the
(ref)       east component of the coordinate is returned by reference.

pszCoordFmNo  The string with the notation of the north component of the
(ref)       coordinate is returned by reference. The exactly format of the
            notation is described in the list "Defaults of the coordinate
            systems".
            Note: "ref pszCoordFmNo" corresponds to "char**" in C. 30 bytes
            of memory for the zero terminated string must be allocated with
            dependence to the call of the function setstringallocate().
            Please consider the notes in the description of the function
            setstringallocate().

wCoordLgNo  The minimum number of digits or characters necessary for the
(ref)       north component of the coordinate is returned by reference.

wCoordTyp   The type of the Coordinate System is returned by reference:
(ref)       0 = numeric Coordinate System
            1 = alphanumeric Coordinate System

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


The returned notations and numbers of digits / characters looks dependently
of the Coordinate System and the desired return length (here 10) e.g. like
this:
   Geographic coordinates [deg, min, sec]:
      vdddmmss.s    8  vddmmss.ss   7 0
   or Austrian Gauss-Krueger coordinates:
      kkkmmm.mmm    6  kkkmmm.mmm   6 0
   or British National grid:
      aaeeeeennnnn 12  ‹blank›      0 1


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