Prototype and description of the function convntvbin2area()

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

convntvbin2area()
Transfers an area of an NTv2 grid file to a new binary file.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall convntvbin2area(
     const char *pszFileBinary,
     const char *pszFileArea,
     double fLonWest,
     double fLonEast,
     double fLatSouth,
     double fLatNorth);

Prototype of the DLL function in Visual Objects syntax:
_DLL function convntvbin2area(;
     pszFileBinary as psz,;                   // 4 Byte, char*
     pszFileArea as psz,;                     // 4 Byte, char*
     fLonWest as real8,;                      // 8 Byte
     fLonEast as real8,;                      // 8 Byte
     fLatSouth as real8,;                     // 8 Byte
     fLatNorth as real8);                     // 8 Byte
as logic pascal:geodll32.convntvbin2area      // 4 Byte


The function copies the grid data of a coordinate-limited area from an
NTv2 binary file into a new NTv2 binary file.

There are some very large NTv2 binary files that are larger than the 2.15
gigabytes addressable with the "long int" C variable type. For example, the
Bavarian NTv2 binary file BY_KanU_Bayern-gesamt.gsb has a size of about 3.5
gigabytes. Unlike the Software GeoDLL and TRANSDAT by KilletSoft, many
geodetic programs and GIS can not handle such large NTv2 files. With the
function convntvbin2area() it is possible to copy an area defined by a
coordinate section from an NTv2 binary file into a new binary file. All
grids of the binary file, which intersects the coordinate section, are
taken into account. The new binary file created in this way is smaller and can
be used with any geodetic software and GIS.

The new area defined by the coordinate section may overlap the area specified
in the NTv2 file in all directions or can be completely contained in it. If
no match of the areas is detected, GeoDLL will acknowledge this with an error
message.

To distinguish it from the original grid file, in the selectively created NTv2
grid file the UPDATED entries in all considered grid headers are overwritten
with the date of the creation day. NTv2 binary files with syntax errors are
rejected by GeoDLL with an error message.

Any existing KilletSoft encryption of the NTv2 file and Polygonal Validity
Scopes contained therein will be retained when transferred to the new NTv2
file.

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.

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 binary file may
contain a drive letter and a directory path. Both binary file should have
the file name extension ".gsb".
Example:
Binary file  "c:\programm_ntv2\BeTA2007.gsb"
New binary   "c:\programm_ntv2\BeTA2007_area.gsb"
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 used as source.
              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".

pszFileArea   File name of the NTv2 binary file which is to be generated for
              the area data. 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".

fLonWest      Western longitude of the coordinate section in [degrees]
              notation vggg.ggg.

fLonEast      Eastern longitude of the coordinate section in[degrees]
              notation vggg.ggg.

fLatSouth    Southern latitude of the coordinate section in [degrees]
              notation vgg.ggg.

fLatNorth     Northern latitude of the coordinate section in [degrees]
              notation vgg.ggg.

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


For geographic coordinates in [degrees] notation applies:
v           Optional sign for longitudes west of Greenwich and latitudes
            south of the equator.
g           degrees and decimal fraction of a degree.

Deviation from the NTv2 standard inside the NTv2 files:
GeoDLL supports Polygonal Validity Scopes. Thus grid meshes 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.