Prototype and description of the function getntvheader()

(Function of the unlock requiring group "NTv2 Tools")


Determination of the header parameter of a NTv2 file.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getntvheader(
     const char *pszFileNtv,
     unsigned long lAscii,
     char **pszNtvHeader);

Prototype of the DLL function in Visual Objects syntax:
_DLL function getntvheader;
     (pszFileNtv as psz,;                  // 4 Byte, char*
     lAscii as logic,;                     // 4 Byte
     pszGridHeader ref psz);               // 4 Byte, char**, 600
as logic pascal:geodll32.getntvheader

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

The parameters are passed and/or returned as follows:
pszFileNtv  File name of the ASCII or binary formatted NTv2 file from which
            the NTv2 header parameter are to be determined. The file name
            may contain a drive letter, a directory path and a file name

lAscii      TRUE: The NTv2 file is ASCII formatted.
            FALSE: The NTv2 file is binary formatted.

pszNtvHeader  Header parameter of the NTv2 file.
(ref)       Note: "ref pszNtvHeader" corresponds to "char**" in C. 600 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

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

The returned text looks dependently of the geodetic source and target systems
e.g. like this:
   Header of the NTv2 file beta2007.gsb
   Number of file header records:  11
   Number of grid header records:  11
   Number of grids:  1
   Unit of shift values:  SECONDS
   Version description:  NTv2.0
   Name of the source Reference System:  DHDN90
   Name of the target Reference System: ETRS89
   Semi-major axis of the source ellipsoid [meter]:  6377397.155
   Semi-minor axis of the source ellipsoid [meter]:  6356078.963
   Semi-major axis of the target ellipsoid [meter]:  6378137.000
   Semi-minor axis of the target ellipsoid [meter]:  6356752.314

This function is a component of the unlock requiring function group "NTv2
tools". 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 no
calls for test purposes (shareware principle) are possible with this function.