Prototype and description of the function setstringallocate()

(This function needs no unlocking)

setstringallocate()
Switching of the automatic allocation of memory for return strings.

Prototype of the DLL function in C++ syntax (attend lower case!):
extern "C" __declspec(dllimport) unsigned long __stdcall setstringallocate(
     unsigned long lSwitch);

Prototype of the DLL function in Visual Objects syntax:
_DLL function setstringallocate(;
     lSwitch as logic);                    // 4 Byte
as logic pascal:geodll32.setstringallocate // 4 Byte


The function switches the automatic allocation of memory for the return of
zero terminated strings (PSZ, pointer string zero) on or off. GeoDLL is
able to allocate memory for returnable PSZ parameters internally and makes
them accessible to the calling program by global stored addresses. In the
calling program then neither memory must allocated nor memory must released
later. In a multithreading environment the allocation in internal global
addresses is not possible, because threads mutually would affect each other.

If in lSwitch the value TRUE is passed, the automatic allocation of memory
on global addresses will be done within GeoDLL. In the calling program
the memory, what is needed to return the PSZs, must not be allocated nor
released later.

If in lSwitch the value FALSE is passed, the calling program must allocate
the memory, what is needed to return the PSZs, independently and release it
after the use by it self. The size of the necessary memory is suggested in
the prototypes of the respective functions.

After starting the program run and loading of the GeoDLL the automatic
allocation of memory for the return of zero terminated strings is switched
on as default.

There are further switches, which prepare GeoDLL for the operating in
different environments. These are the functions
      setinternerrsys()
      setstaticuse()
      setmultithreading()
      setsilence()
      seteventloop()

In GeoDLL in each case PSZ variables are not returned by the return
value of the function, but as references on PSZ parameters, which are
passed in the function header. The passing by references instead of
passing by values is necessary, to be able to administer memory for the
PSZ parameters within GeoDLL. The passing of a PSZ as reference
corresponds to the C or C++ syntax "char**". In words expressed this is a
"pointer to a pointer to the first character of a string", or an "address
of an address of the first character of a string".


The parameters are passed and/or returned as follows:
lSwitch       Switch for the automatic allocation of memory for the return
              of zero terminated strings (PSZ)
TRUE          Automatic allocation of memory on
              (default)
FALSE         Automatic allocation of memory off

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


Unlocking:
This function needs no unlocking.