Prototype and description of the function convntvbin2ascii()

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

convntvbin2ascii()
Convert binary file with NTv2 grid data to ASCII file.

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

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


The function converts a binary file with NTv2 grid data, which can be
used for Reference System Transitions, to a human readable binary file.

NTv2 binary files with syntax errors are rejected by GeoDLL with an error
message.

You can download the NTv2 files supported by GeoDLL directly from the
KilletSoft website http://www.killetsoft.de/p_gdln_e.htm#download or use the
download links to the original sources there. On that Internet site you also
find a detailed description of the NTv2 standard.

After unpacking the ZIP compressed data they are present as ASCII data
files or ready for use as binary files. To be able to use an ASCII file
with GeoDLL functions, first it must be converted to the substantially more
efficient and more compact binary data format. The conversion, can take some
seconds or minutes. The function convntvbin2ascii() allows you to transform
an NTv2 binary file back into a readable NTv2 ASCII file.

Since the function due to the extensive calculations is time-consuming,
the event handling during the calculation by interrupting the processing
loop can be are allowed bei calling the function seteventloop().

The file names of the NTv2 binary file and of the generated ASCII file
may contain a drive letter and a directory path. The generated ASCII file
may contain any file name extension. The binary file should have the file
name extension ".gsb".
Example:
Binäry file  "c:\program_ntv2data\binary\BeTA2007.gsa"
ASCII file   "c:\program_ntv2data\ascii\beta2007_gen.gsa"
Attention, in C syntax double backslashes must be used!


The parameters are passed and/or returned as follows:
pszFileBinary  File name of the NTV2 binary file which is to be converted.
              The file name may contain a drive letter, a directory path
              and a file name extension. The file name should have the file
              name extension ".gsb".

pszFileAscii  File name of the ASCII file which is to be generated. The
              file name may contain a drive letter, a directory path and any
              file name extension.

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


Deviation from the NTv2 standard inside the NTv2 files:
GeoDLL supports Polygonal Validity Scopes. Thus grid mesh records may contain
the exopolygonal entries -99/-99 in their shift or accuracy values. Detailed
information can be found in the help section "Polygonal Validity Scopes".


Unlocking:
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.