Funktion setstringallocate()

Prototyp und Beschreibung der Funktion setstringallocate()

(Nicht freischaltpflichtige Funktion)

 

setstringallocate()
Schalten der automatischen Bereitstellung von Speicherplatz für return
strings.

Prototyp der DLL-Funktion in C++ Syntax (Kleinschreibung beachten!):
extern "C" __declspec(dllimport) unsigned long __stdcall setstringallocate(
     unsigned long lSwitch);

Prototyp der DLL-Funktion in Visual Objects Syntax:
_DLL function setstringallocate(;
     lSwitch as logic);                    // 4 Byte
as logic pascal:geodll32.setstringallocate // 4 Byte


Die Funktion schaltet die automatische Bereitstellung (allocation) von
Speicherplatz für die Rückgabe von Null-terminierten Strings (PSZ, Pointer
string zero) ein- oder aus. GeoDLL kann den Speicherplatz für
zurückzugebende PSZ intern allokieren und über eine global gespeicherte
Adresse dem rufenden Programm zugänglich machen. Im rufenden Programm muss
dann weder Speicher allokiert noch Speicher wieder freigegeben werden. In
einer Multithreading-Umgebung ist die Allokation über globale Adressen
jedoch nicht möglich, weil die threads sich gegenseitig beeinflussen würden.

Wenn in lSwitch der Wert TRUE übergeben wird, erfolgt die automatische
Bereitstellung von Speicher über globale Adressen innerhalb von GeoDLL. Im
aufrufenden Programm muss der für zurückzugebende PSZs benötigte
Speicherplatz dafür weder allokiert noch später wieder freigegeben werden.

Wenn in lSwitch der Wert FALSE übergeben wird, muss das rufende Programm
für jede String-Rückgabe den Speicherplatz selbstständig allokieren und nach
der Verwendung wieder freigeben. Die Größe des benötigten Speicherplatzes
ist in den Prototypen der jeweiligen Funktionen vorgeschlagen.

Nach dem Programmaufruf bzw. dem Laden der GeoDLL ist die automatische
Bereitstellung von Speicherplatz in globalen Adressen standardmäßig
eingeschaltet.

Es gibt weitere Schalter, die GeoDLL auf den Betrieb in verschiedenen
Umgebungen vorbereiten. Dies sind die Funktionen
      setinternerrsys()
      setstaticuse()
      setmultithreading()
      setsilence()
      seteventloop()

In GeoDLL werden PSZ-Variablen grundsätzlich nicht als Rückgabewert von
Funktionen zurückgegeben, sondern als Referenzen auf PSZ-Variablen, die
im Funktionskopf als Parameter übergeben werden. Die Übergabe per Referenz
anstelle der Übergabe per Value ist notwendig, um Speicherplatz für die
PSZ-Parameter innerhalb von GeoDLL verwalten zu können. Die Übergabe eines
PSZ als Referenz  entspricht in C oder C++ der Syntax "char**". In Worten
ausgedrückt ist das ein "Zeiger auf einen Zeiger auf das erste Zeichen
eines Strings" oder eine "Adresse mit der Adresse des ersten Zeichens
eines Strings".


Die Parameter werden folgendermaßen übergeben bzw. zurückgegeben:
lSwitch       Schalter für die automatische Bereitstellung von Speicher
TRUE          Automatische Bereitstellung von Speicher einschalten
              (default)
FALSE         Automatische Bereitstellung von Speicher ausschalten

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


Freischaltung:
Die Funktion ist nicht freischaltpflichtig.