Handling Memory Buffers

Occasionally it is necessary to work with raw memory blocks. In such cases the user is responsible for allocating and freeing the memory blocks. However, many API functions can work with not only BDL strings, but also with memory buffers.

A memory block is represented by a handle returned by the Alloc() function. The keyword IN together with the memory handle represent the newly allocated memory buffer. When used as a parameter for an API function, runtime automatically converts the handle into a valid parameter for the external function. The only difference between an ordinary string variable is that the LENSPEC and SIZEPEC parameters are not set automatically by runtime.

Example

dll "some.dll"
  "FillBuffer"
    function FillBuffer(sBuffer : inout string,
                        nBufSize : in number sizespec optional,
                        nDataLen : out number lenspec optional);
  "WriteData"
    function WriteData(sData : in string,
                       nDataLen : in number lenspec optional);
transaction TMain
var
  sBuffer : string;
  hBuffer : number;
  nLen    : number;
begin
  FillBuffer(sBuffer, 1024); // sBuffer is automatically resized and the length is automatically set
  WriteData(sBuffer); // nDataLen is automatically set correctly
  hBuffer := Malloc(1024);
  FillBuffer(in hBuffer, 1024, nLen);
  WriteData(in hBuffer, nLen);  // nDataLen must be set manually
  Free(hBuffer);
end TMain;

Note: The IN modifier for actual number parameters requires either a STRING, PTR or DSTRING formal parameter type.