Q(uick)BASIC Function: FRE

Quick View

FRE

A memory management function that returns the amount of available memory

Worth knowing

Useful and cross-version information about the programming environments of QBasic and QuickBasic.

Syntax

FRE(numeric-expression)
FRE(stringexpression$)

Description/Parameter(s)

numeric-expression

A value that specifies the type of memory:

Value	FRE returns
-1	The size of the largest array (nonstring) you can create
-2	The unused stack space
Any other number	The available string space

stringexpression$

Any string expression. FRE compacts the free string space into a single block, then returns the amount of available string space.

Example

PRINT "String Space", FRE("")
PRINT "Unused Stack Space", FRE(-2)
PRINT "Array Space", FRE(-1)

Syntax

FRE(stringexpression)
FRE(numeric-expression)

Description/Parameter(s)

The FRE function returns the following values when it has a numeric argument (numeric-expression):

Argument	Value Returned
-1	The size, in bytes, of the largest nonstring array that could be dimensioned
-2	The amount, in bytes, of unused stack space available to the program
Any other numeric value	The size of the next free block of string storage

When the argument is a string expression (stringexpression), FRE returns the size, in bytes, of the free string storage. Before FRE returns the number of free bytes, it compacts the free string storage into a single block.

Note:

FRE(-2) returns meaningful values only when a program is executing. Values returned by FRE(-2) are not accurate when the function is called from the Immediate window, during program tracing, or when watching a variable.

Examples

This example shows some of the values FRE returns before and after dimensioning an array.

' $DYNAMIC
CLS                 ' Clear screen
PRINT "Before dimensioning arrays:  " FRE(""),FRE(0),FRE(-1)
DIM LARGE%(150,150), BIG$(5000)
PRINT "After dimensioning arrays:   " FRE(""),FRE(0),FRE(-1)

The actual values FRE will return on your own computer may be different.

Sample Output:

Before dimensioning arrays: 58420 58420 322120 After dimensioning arrays: 38404 38404 276496

Syntax

FRE(stringexpression$)
FRE(numeric-expression%)

Description/Parameter(s)

The argument stringexpression$ can be a string literal or a string variable.

Usage Notes

The values returned for different types of arguments depend on whether you are using near strings or far strings:

Function	Near strings	Far strings
FRE(a$)	Remaining space in DGROUP (in bytes)	Remaining space in a$'s segment (in bytes)
FRE("string literal")	Remaining space in DGROUP (in bytes)	Remaining space for temporary strings (in bytes)
FRE(0)	Remaining space in DGROUP (in bytes)	Error message: "Illegal function call"
FRE(-1)	Remaining space in far memory for DOS (in bytes); long integer 2147483647 (for OS/2)	Remaining space in far memory for DOS (in bytes); long integer 2147483647 (for OS/2)
FRE(-2)	Remaining stack space (in bytes)	Remaining stack space (in bytes)
FRE(-3)	Remaining space in expanded memory (in kilobytes)	Remaining space in expanded memory (in kilobytes)
FRE(any other number)	Error message: "Illegal function call"	Error message: "Illegal function call"

Using FRE(-3) and Expanded Memory

If expanded memory is not available, FRE(-3) returns the message "Feature unavailable."
If you start QBX without the /E:n switch, you will be using all expanded memory available on your computer.

QBX /E:4096

If you have specified 4 megabytes of expanded memory as shown above, and then you use 2 megabytes of expanded memory in your program, FRE(-3) will return 2048.

If you are using BC to run a program with expanded-memory overlays, the value returned by FRE(-3) is based on the total amount of expanded memory available. (When using overlays, you cannot limit the amount of expanded memory used by your program.)
For more information on using expanded memory, see ⮜ Using Expanded Memory ⮞.
For more information on memory allocation, see Chapter 15, "Optimizing Program Size and Speed" in the Programmer's Guide.

Important

FRE(-2) returns meaningful values only when a program is executing. Values returned by FRE(-2) are not accurate when the function is called from the Immediate window, during program tracing, or when watching a variable. The unused stack space indicates how much stack is needed so that DGROUP can be reclaimed.

Example

This example uses the FRE function to report the availability of memory resources. The example also uses the STACK function to allocate stack space.
If QBX is invoked with the /Ea switch, the integer arrays used in this example will be placed in available EMS memory space, otherwise they will occupy far memory. If the arrays are placed in EMS, each array will reduce available EMS memory by 16K. If not in EMS, far memory will be reduced by the number of bytes occupied by the array rounded up to an even 16 bytes.

DECLARE SUB MakeSubString ()
DECLARE SUB Printit (a$)
DECLARE SUB Recursive (n!)
 
CLS
'Report the way things are to begin.
PRINT "Remaining space (in bytes) to begin with is:"
CALL Printit(a$)
 
'Create a 32K string and give report.
String1$ = STRING$(32767, 90)
PRINT "The remaining space after creating a 32K far string is:"
CALL Printit(String1$)
 
'Make a substring and give report.
MakeSubString
PRINT "The remaing space after returning from a sub is:"
CALL Printit(String2$)
 
'Do 50 recursive calls to a SUB.
n = 50
CALL Recursive(n)
 
'Allocate 2K for the stack.
STACK (2048)
PRINT "After allocating 2K for the stack, the space is:"
CALL Printit(a$)
 
'Do another 50 recursive calls to a SUB.
n = 50
CALL Recursive(n)
 
'Dimension a 1001 element dynamic array in EMS.
REDIM a%(999)
PRINT "After dimensioning a 1000-element integer array, the space is:"
CALL Printit(a$)
 
PRINT "After dimensioning a second 1000-element integer array, the space is:"
REDIM B%(999)
CALL Printit(a$)
 
'Reset the stack to the default size.
PRINT "Stack reset to default value: "; STACK

SUB MakeSubString
SHARED String1$
    String2$ = STRING$(32767, 90)
    PRINT "The space remaining after creating a 32K sub string is:"
    CALL Printit(String1$)
END SUB

SUB Printit (a$)
    PRINT "Far Memory"; TAB(15); "Stack"; TAB(25);
    PRINT "String Segment"; TAB(45); "Temp. Segment"; TAB(65); "EMS Memory"
    PRINT FRE(-1); TAB(15); FRE(-2); TAB(25); FRE(a$); TAB(45); FRE("");
    PRINT TAB(65); FRE(-3); "K"
    PRINT
END SUB

SUB Recursive (n)
SHARED String1$
    n = n - 1
    IF n = 0 THEN
  PRINT "The remaining space after 50 recursive calls is:"
  CALL Printit(String1$)
  EXIT SUB
    ELSE
  CALL Recursive(n)
    END IF
END SUB