Prototype and description of the function getntvgridarray()

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

getntvgridarray()
Determination of parameters of one or all NTv2 grids in arrays.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall getntvgridarray(
     const char *pszFileNtv,
     unsigned long lAscii,
     unsigned short nGridNo,
     double aGridVal[][6],
     double aGridFrame[4],
     unsigned long aGridSize[],
     unsigned short nGridMax,
     unsigned short *nGridCount);

Prototype of the DLL function in Visual Objects syntax:
_DLL FUNCTION getntvgridarray;
     (pszFileNtv as psz,;                  // 4 Byte, char*
     lAscii as logic,;                     // 4 Byte
     nGridNo as word,;                     // 2 Byte
     aGridVal as real8 ptr,;               // 4 Byte
     aGridFrame as real8 ptr,;             // 4 Byte
     aGridSize as dword ptr,;              // 4 Byte
     nGridMax as word,;                    // 2 Byte
     nGridCount ref word);                 // 4 Byte
as logic pascal:geodll32.getntvgridarray


The function returns the numerical parameters of one or more grids from
an ASCII or binary formatted NTv2 file in arrays. The array aGridVal returns
the bounding rectangles and mesh sizes of the grids. The array aGridFrame
returns a full covering rectangle of all processed grids. The array
aGridSize returns the numbers of grid meshes contained in the grids.


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

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

nGridNo     n: Number of the grid in the NTv2 file for which the
               numerical parameters are to be determined.
            0: The numeric parameters of all grids contained in the NTv2
               file are determined.

aGridVal    Pointer to an array or structure with nGridMax * 6 elements of
[n][6]      type double. For the subgids following parameters are stored in
  or        the array:
NULL        1: South border of the grid in degree
            2: North border of the grid in degree
            3: East border of the grid in degree
            4: West border of the grid in degree
            5: Grid spacing on latitude of the grid meshes in degree
            6: Grid spacing on longitude of the grid meshes in degree
            If aGridVal is NULL, no Array will be returned.

aGridFrame  Pointer to an array or structure with 4 elements of type
[4]         double. The rectangle enclosing the grids is stored in the
  or        array as follows:
NULL        1: South border of the enclosing rectangle in degree
            2: North border of the enclosing rectangle in degree
            3: East border of the enclosing rectangle in degree
            4: West border of the enclosing rectangle in degree
            If aGridFrame or aGridVal is NULL, no Array will be returned.

aGridSize   Pointer to an array or structure with nGridMax unsigned long
[n]         elements. In the array, the numbers of grid meshes of the
  or        processed grids are registered.
NULL        If aGridSize is NULL, no Array will be returned.


nGridMax    The maximum size of the arrays or structures analogous to the
            definition in the calling program. The size depends on the
            number of grids expected in the NTv2 file. If necessary, the
            number of grids can be determined with the function
            getntvgridcount().

nGridCount  The number of grids actually processed. The number of the
(ref)       grids is returned by reference.

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


Example with fix arrays in CAVO:
FUNCTION test
  LOCAL n,nGridMax,nGridCount AS WORD
  LOCAL DIM aGridVal[500,6],DIM aGridFrame[4] AS REAL8
  LOCAL DIM aGridSize[500] AS DWORD
  LOCAL pszFileName AS PSZ
  pszFileName := PSZ("C:\ntv2\ntv2_0.gsb")
  nGridMax := 500
  IF getntvgridarray(pszFileName,FALSE,0,@aGridVal,@aGridFrame,@aGridSize,;
  nGridMax,@nGridCount)
    ? nGridCount
    FOR n:=1 UPTO nGridCount
      ? aGridVal[n,1],aGridVal[n,2],aGridVal[n,3],aGridVal[n,4]
      ? aGridSize[n]
    NEXT n
    ? aGridFrame[1],aGridFrame[2],aGridFrame[3],aGridFrame[4]
  ELSE
    geterrorcode(@pszError)
    ? Psz2String(pszError)
  ENDIF
RETURN 0


Example with dynamic structures in CAVO:
STRUCTURE GRIDVAL
  MEMBER DIM a[1,6] AS REAL8

STRUCTURE GRIDSIZE
  MEMBER DIM a[1] AS DWORD

FUNCTION test   // Property "Range Checking" must be off!
  LOCAL n,nGridMax,nGridCount AS WORD
  LOCAL stGridVal AS GRIDVAL
  LOCAL DIM aGridFrame[4] AS REAL8
  LOCAL stGridSize AS GRIDSIZE
  LOCAL pszFileName AS PSZ
  pszFileName := PSZ("C:\ntv2\ntv2_0.gsb")
  IF .not. getntvgridcount(pszFileName,FALSE,@nGridMax)
    geterrorcode(@pszError)
    ? Psz2String(pszError)
  ELSE
    ? nGridMax
    stGridVal := MemAlloc(nGridMax * _sizeof(GRIDVAL))
    stGridSize := MemAlloc(nGridMax * _sizeof(GRIDSIZE))
    IF .not. getntvgridarray(pszFileName,FALSE,0,stGridVal,@aGridFrame,;
    stGridSize,nGridMax,@nGridCount)
      geterrorcode(@pszError)
      ? Psz2String(pszError)
    ELSE
      ? nGridCount
      FOR n:=1 UPTO nGridCount
        ? stGridVal.a[n,1],stGridVal.a[n,2],stGridVal.a[n,3],stGridVal.a[n,4]
        ? stGridSize.a[n]
      NEXT n
      ? aGridFrame[1],aGridFrame[2],aGridFrame[3],aGridFrame[4]
    ENDIF
    MemFree(stGridVal)
    MemFree(stGridSize)
  ENDIF
RETURN 0


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.