Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

  ◄Summary► ◄Details► ◄Example►                                   ◄Back►
 
  Argument
 
    pointer_variable    Pointer of any type, either undefined or
                        pointing to a variable
 
  Description
 
    The New procedure allocates a dynamic variable from the heap and
    sets pointer_variable to the address of the first byte of the
    memory area.
 
    The pointer_variable argument may be undefined or set to an
    existing variable. New cannot allocate a variable larger than
    65520 bytes.
 
    Use caution when pointer_variable is currently set to a dynamic
    variable. New always sets pointer_variable to a new address. If
    pointer_variable is the only reference to a dynamic variable, the
    reference is permanently lost, and the memory area cannot be
    recovered for reallocation.
 
    After allocation, refer to the new variable by dereferencing the
    pointer. Append a caret (^) to pointer_variable and use the result
    as a variable of the type of pointer_variable.
 
    New is similar to the GetMem procedure, which allocates a memory
    area of a specified size. Use Dispose to free a variable allocated
    by New. Use FreeMem to free memory allocated by GetMem.
 
    QuickPascal uses a free list to manage areas returned to the heap
    by Dispose and FreeMem. The free list is a list of pointers that
    grows downward (toward 0) from the top of the heap segment.
    FreePtr, defined in the System unit, points to the free list.
    Deallocated areas below the current top of the heap are pointed to
    by pointers kept in the free list. GetMem and New allocate from the
    free list before taking any new memory from the heap.
 
    Use caution when mixing methods for deallocating variables. Dynamic
    allocation and deallocation are usually done with the related pairs
    of procedures New/Dispose and GetMem/FreeMem. The Mark and Release
    procedures allow freeing of large areas of the heap at one time.
    Release clears the entire free list when called.
 
    If the heap does not have sufficient free space to allocate a
    variable of the type of pointer_variable, the HeapError function
    provided at start-up causes a run-time error. It is possible to
    replace the default HeapError function with a custom function.
    Check the available heap space with the MaxAvail and MemAvail
    functions.
 
    New allocates enough space for the largest part of a variant
    record. Use GetMem instead of New to allocate a smaller variant
    record. Pass GetMem the size of the desired variant.