Prototype and description of the function setunlockcode()

(This function needs no unlocking)

 

setunlockcode()
Unlocking of GeoDLL function groups with unlock parameters.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall setunlockcode(
     char *pszUnlockkey,
     char *pszLicensee);

Prototype of the DLL function in Visual Objects syntax:
_DLL function setunlockcode(;
     pszUnlockkey as psz,;                 // 4 Byte, char*
     pszLicensee as psz);                  // 4 Byte, char*
as logic pascal:geodll32.setunlockcode     // 4 Byte


The function unlocks all DLL functions of an unlock requiring function
group for unrestricted use. Therefore the unlock parameters from the
license agreement must be passed by the function setunlockcode() to the
DLL for each group which can be unlocked. It is important that the
parameters are passed in the same way of writing, as they are registered
in the license agreement. If functions from different groups are to be
used, setunlockcode() must be called several times successively.

The geodetic functions of the DLL are put together in unlock requiring
functional groups as follows:

The group "Coordinate Transformations" contains functions for the
realization of Coordinate Transformations and Reference System
Transitions.
  coordtrans()       2D Coordinate Transformation, numeric / alphanum. (char**)
  coordtrans2()      2D Coordinate Transformation, numeric / alphanum. (char*)
  coordtrans3()      2D Coordinate Transformation, only numeric
  coordtrans4()      2D Coordinate Transformation, only numeric, no notations
  coordtransex()     2D Coordinate Transformation, reduced eastings
  coordtrans3d()     3D Coordinate Transformation, numeric / alphanum. (char**)
  coordtrans3d2()    3D Coordinate Transformation, numeric / alphanum. (char*)
  coordtrans3d3()    3D Coordinate Transformation, only numeric
  coordtrans3d4()    3D Coordinate Transformation, only numeric, no notations
  coordtrans3dex()   3D Coordinate Transformation, reduced eastings
  coordtransepsg()   EPSG code Coordinate Transformation
  meritrans()        Meridian strip change with GK und UTM coordinates
  setcoordarea()     Coordinate System range validity check on / off

The group "NTv2 Grid Data" contains functions to perform Reference
System Transition with grid files of the NTv2 standard.
  convntvascii2bin()  Convert a NTv2 ASCII file to a binary file
  getntvgridcount()   Get count of subgrids contained in a NTv2 file
  getntvgridheader()  Get header parameter of a NTv2 subgrid
  getntvheader()      Get header parameter of a NTv2 file
  getntvrefbelong()   Get the second NTv2 Reference System
  getntvrefequiv()    Get an NTv2 equivalent Reference System
  getntvrefstatus()   Get the NTv2 membership of a Reference System
  setntvbinaryfile()  Initialize and test a NTv2 binary file
  setntvbinautofile() Set a NTv2 grid binary file in a wait position
  setntvpolyvalid()   Set Polygonal Validity Check in NTv2 files

The group "User Definitions" contains functions for input of self defined
Coordinate Systems, geodetic Reference Systems and earth ellipsoids which
can be used with the functions of the group "Coordinate Transformations"
besides the systems predefined in the GeoDLL.
  setusercoordsys1() Setup of a user-defined Coordinate System
  setusercoordsys2() Setup of a 2nd user-defined Coord. System
  setuserrefsys()    Setup of a user-defined Reference System
  setuserellsource() Setup of a user-defined source ellipsoid
  setuserelltarget() Setup of a user-defined target ellipsoid
  getusercoordpar()  Get parameter names of a user def. Coord. System
  getusercoordtyp()  Get type name of a user-defined Coordinate System

The group "Parameter Determination" contains functions to return values of
in GeoDLL predefined and user-defined coordination systems, geodetic
Reference Systems and ellipsoids.
  getcoordname()     Coordinate System name
  getcoordsys()      Formatted Coordinate Systems parameters
  getcoordform()     2D Coordinate System notations
  getcoordform3d()   3D Coordinate System notations
  getcoordaxis()     2D Coordinate System axes names
  getcoordaxis3d()   3D Coordinate System axes names
  getcoordarea()     Range validity of a Coordinate System
  getcoordstdrefsys() Default Reference System of a Coordinate System
  getcoordproj()     Projection method number of a Coordinate System
  getcoordstrstatus() Determining Coordinate System is a strip system
  getrefname()       Reference System name
  getrefsys()        Formatted Reference Systems parameters
  getellname()       Ellipsoid name
  getellsys()        Formatted ellipsoid parameters
  getellsource()     Source ellipsoid semi axes
  getelltarget()     Target ellipsoid semi axes

The group "Distance Calculations" contains functions for determination of
distance between two coordinates.
  distancegeo()      Distance between geogr. coordinates on the ellipsoid
  distancesphere()   Distance between geogr. coordinates on the sphere
  distanceutm()      Distance between UTM coordinates
  point2pointgeo()   Dest. point on ellipsoid from start point, bearing, dist.
  point2pointsphere() Dest. point on sphere from start point, bearing, distance
  point2pointutm()   UTM dest. point from UTM start point, bearing and distance
  vincentydirect()   Vincentys Direct Position Computation
  vincentyinverse()  Vincentys Inverse Position Computation

The group "Notation Calculations" contains functions for conversion of
geographic coordinates of one notation in another and for correct decimal
rounding of geographic coordinates of different notations.
  umfd2g()           Translates decimal notation to degrees notation
  umfd2gn()          Translates decimal notation to gonal notation
  umfd2n()           Translates decimal notation to nautical notation
  umfd2s()           Translates decimal notation to seconds notation
  umfg2d()           Translates degrees notation to decimal notation
  umfgn2d()          Translates gonal notation to decimal notation
  umfn2d()           Translates nautical notation to decimal notation
  umfs2d()           Translates seconds notation to decimal notation
  umfroundg()        Accurate rounding of degrees coordinates
  umfroundn()        Accurate rounding of nautical coordinates

The group "Map Calculations" contains functions for converting coordinates
in TK-numbers of the topographic maps of Germany and to determine the
corner coordinates of the topographic maps.
  kartgeo2tk()       Determine TK25 number from geographic coordinates
  karttk2geo()       Determine corner map coordinates from TK25 number
  karttknum()        Determine TK50, TK100 und TKÜ200 from a TK25 number

The group "Elevation Calculations" contains functions for the determination
of ground elevations over the Mean Sea Level from digital elevation models.
  getelevation03()   Elevation from the 3 sec. elevation model CGIAR
  getelevation30()   Elevation from the 30 sec. elevation model GLOBE
  getelevation33()   Elevation from 3/30 sec. elevation model CGIAR/GLOBE
  setelev03datapath() Sets the data path for 3 sec. elevation model CGIAR
  setelev30datapath() Sets the data path for 30 sec. elevation model GLOBE
  convelev03ascii2bin() Convert a CGIAR ASCII file to a binary file

The group "Transformation Parameter" contains functions to calculate
Helmert and Molodensky parameter sets from identical points of the source
and target Coordinate Reference Systems.
  gettranshelmert()   Calculation of seven Helmert parameters
  gettransmolodensky() Calculation of three Molodensky parameters
  gettransoutliers()  Calculation of outliers in a group of identical points
  gettransresiduals() Calculation of the residuals from identical points
  gettransresidualmax() Calculation of the "Maximum Spatial Residual"
  gettransresidualaverage() Calculation of the "Average Spatial Residual"
  gettransresidualrms() Calculation of the "Root Mean Square Residual" (RMS)

The group "Time Zone Calculations" contains functions to calculate time zones,
UTC, DST, daylight change dates and other time zone parameters from coordinates
or from GeoDLL time zone indexes.
  settzgridfile()    Initialize and test a gridfile for time zone calculations
  settzshapefile()   Initialize and test a shapefile for time zone calculations
  gettzcurrentbynum() Determ. of current time zone param. from GeoDLL index
  gettznamebynum()   Determ. of a time zone designation from a GeoDLL index
  gettznumbycoordexact() Exact determination of GeoDLL index from a coordinate
  gettznumbycoordfast() Fast determination of GeoDLL index from a coordinate
  gettzparbynum()    Determination of common time zone param. from GeoDLL index

Miscellaneous functions which do not require an unlock key and may be used
with all function groups.
  getauthor()        Copyright and program author's address
  getdisclaimer()    Disclaimer reference for GeoDLL
  getdllversion()    GeoDLL version number
  geterrorcode()     Latest error description
  getlicensee()      Licensee identification
  setcoordarea()     Coordinate System range validity check on / off
  seteventloop()     Event loop while time intensive calculations on / off
  setinternerrsys()  Internal error handler on / off
  setlanguage()      Language selection for all text returns
  setmultithreading() Using in an multithreading environment on / off
  setsilence()       Output of messages to the EventLog on / off
  setstaticuse()     Usage of fast Static Variables on / off
  setstringallocate() Automatic memory management on / off
  setunlockcode()    Input of the unlock parameters

When calling the function setunlockcode() the passed unlock parameters must
be correct. With the passing of a only one invalid unlock parameter the
functions of all unlock able groups are excluded from further function
calls.

If still no unlock parameters were acquired at the software distribution
company, the functions of unlock requiring groups can be called for a few
times per program run for test purposes (shareware principle). The test
version also displays a small message box and generates a three tone sequence.
The function setunlockcode() may not be called in this case (see previous
paragraph).


The parameters are passed and/or returned as follows:
pszUnlockkey  Unlock code from the license agreement acquired from the
              licenser as a null terminated character string (pointer
              string zero). If the used programming language should not
              support null terminated strings, then also a normal string
              with an attached null character can be passed.

pszLicensee   Designation of the licensee from the license agreement as a
              null terminated character string (pointer string zero). If
              the used programming language should not support null
              terminated strings, then also a normal string with an
              attached null character can be passed. The licensee
              designation can be queried later with the function
              getlicensee().

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


Unlocking:
The function needs no unlocking.