Prototyp und Beschreibung der Funktion getntvgridarray()

(Funktion der freischaltpflichtigen Gruppe "NTv2-Werkzeuge")

 

getntvgridarray()
Ermitteln der Parameter eines oder aller NTv2-Subgitter in Arrays.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
__declspec(dllimport) unsigned long __stdcall getntvgridarray(
     char *pszFileNtv,
     unsigned long lAscii,
     unsigned short nGridNo,
     double aGridVal[][6],
     double aGridFrame[4],
     unsigned long aGridSize[],
     unsigned short nGridMax,
     unsigned short *nGridCount);

Prototyp der DLL-Funktion 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


Die Funktion gibt die numerischen Parameter eines oder mehrerer Subgitter
aus einer ASCII- oder binär formatierten NTv2-Datei in Arrays zurück. Im
Array aGridVal werden die Begrenzungs-Rechtecke und die Maschenweiten der
Subgitter zurückgegeben. Im Array aGridFrame wird ein umfassendes
Begrenzungs-Rechteck aller bearbeiteten Subgitter zurückgegeben. Im Array
aGridSize werden die Anzahlen der Gittermaschen der Subgitter zurückgegeben.


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
pszFileNtv  Dateiname der ASCII- oder binär formatierten NTv2-Datei, für
            die die numerischen Parameter in Arrays gespeichert werden
            sollen. Der Dateiname darf einen Laufwerksbuchstaben, eine
            Verzeichniskette und eine Dateinamenserweiterung enthalten.

lAscii      TRUE: Die NTv2-Datei ist ASCII-formatiert.
            FALSE: Die NTv2-Datei ist binär formatiert.

nGridNo     n: Nummer des Subgitters in der NTv2-Datei, für das die
               numerischen Parameter ermittelt werden sollen.
            0: Es werden die numerischen Parameter aller in der NTv2-Datei
               enthaltenen Subgitter ermittelt.

aGridVal    Zeiger auf ein Array oder eine Struktur mit nGridMax * 6
[n][6]      Elementen des Typs double. Folgende Parameter werden für die
oder        Subgtter in das Array eingetragen:
NULL        1: Südliche Begrenzung des Gitters in Grad
            2: Nördliche Begrenzung des Gitters in Grad
            3: Östliche Begrenzung des Gitters in Grad
            4: Westliche Begrenzung des Gitters in Grad
            5: Gitterabstand der Breite der Gittermaschen in Grad
            6: Gitterabstand der Länge der Gittermaschen in Grad
            Wenn in aGridVal NULL eingetragen ist, wird kein Array zurück
            gegeben.

aGridFrame  Zeiger auf ein Array oder eine Struktur mit 4 Elementen des
[4]         Typs double. Das die Subgitter umfassende Rechteck wird
  oder      folgendermaßen in das Array eingetragen:
NULL        1: Südliche Begrenzung des umfassenden Rechtecks in Grad
            2: Nördliche Begrenzung des umfassenden Rechtecks in Grad
            3: Östliche Begrenzung des umfassenden Rechtecks in Grad
            4: Westliche Begrenzung des umfassenden Rechtecks in Grad
            Wenn in aGridVal oder in aGridFrame NULL eingetragen ist, wird
            kein Array zurück gegeben.

aGridSize   Zeiger auf ein Array oder eine Struktur mit nGridMax Elementen
[n]         des Typs unsigned long. In das Array werden die Anzahlen der
  oder      Gittermaschen der bearbeiteten Subgitter eingetragen.
NULL        Wenn in aGridSize NULL eingetragen ist, wird kein Array zurück
            gegeben.

nGridMax    Die maximale Größe der Arrays oder Strukturen analog zur
            Definition im rufenden Programm. Die Größe hängt von der Anzahl
            der in der NTv2-Datei erwarteten Subgitter ab. Falls nötig, kann
            die Anzahl der Subgitter mit der Funktion getntvgridcount()
            ermittelt werden.

nGridCount  Die Anzahl der tatsächlich bearbeiteten Subgitter. Die Anzahl
            der bearbeiteten Subgitter wird per Referenz zurückgegeben.

returnWert  Im Fehlerfall gibt die Funktion FALSE zurück, sonst TRUE.


Beispiel mit fixen 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


Beispiel mit dynamischen Strukturen 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


Freischaltung:
Die Funktion ist Bestandteil der freischaltpflichtigen Funktionsgruppe
"NTv2-Werkzeuge". Sie wird zusammen mit den anderen Funktionen der Gruppe
durch die Eingabe der bei der Vertriebsfirma erworbenen Freischaltparameter
per Aufruf der Funktion setunlockcode() zur uneingeschränkten Nutzung frei
geschaltet. Ohne die Freischaltung sind mit dieser Funktion keine Funktions-
aufrufe zu Testzwecken (Sharewareprinzip) möglich.