Q(uick)BASIC Function: SETMEM

Quick View

SETMEM

A memory management function that changes the amount of memory used by the far heap - the area where far objects and internal tables are stored

Worth knowing

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

Syntax

SETMEM(numeric-expression)

Description/Parameter(s)

The numeric-expression indicates the number of bytes to increase or decrease the far heap.

If the numeric-expression is negative, SETMEM decreases the far heap by the indicated number of bytes.
If the numeric-expression is positive, SETMEM attempts to increase the far heap space by the number of bytes.

SETMEM returns the total number of bytes in the far heap. If the numeric-expression is zero, SETMEM returns the current size of the far heap.

If SETMEM cannot change the far heap by the requested number of bytes, it reallocates as many bytes as possible.

SETMEM can be used in mixed-language programming to decrease the far heap space so procedures in other languages can dynamically allocate far memory.

Note:

A first call to SETMEM trying to increase the far heap has no effect because BASIC allocates as much memory as possible to the far heap when a program starts.

Example

The following program outlines how SETMEM could be used to free memory for a C function that uses malloc to get dynamic memory.
The C function must be separately compiled and then put in a Quick library or linked to the BASIC program. The C function is compiled using the large memory model, so calls to malloc use the far space freed by the BASIC program.

'*** Programming example: SETMEM function ***
'
' Do not attempt to run this program unless you have already
' separately compiled the C function, using the large memory model,
' and placed it in a Quick library or linked it to the BASIC program.
'
DECLARE SUB CFunc CDECL (BYVAL X AS INTEGER)

' Decrease the size of the far heap so CFunc can use
' malloc to get dynamic memory.
BeforeCall = SETMEM(-2048)

' Call the C function.
CFunc(1024%)

' Return the memory to the far heap; use a larger value so
' all space goes back into the heap.
AfterCall = SETMEM(3500)

IF AfterCall <= BeforeCall THEN PRINT "Memory not reallocated."

END

void far cfunc(bytes)
int bytes;
{
   char *malloc();
   char *workspace;

   /* Allocate working memory using amount BASIC freed. */
   workspace=malloc((unsigned) bytes);

   /* Working space would be used here. */

   /* Free memory before returning to BASIC. */
   free(workspace);
}

Syntax

SETMEM(numeric-expression&)

Description/Parameter(s)

If numeric-expression& is	SETMEM returns
Positive or negative	Total number of bytes in the far heap.
0	Current size of far heap.

If numeric-expression& is negative, SETMEM decreases the far heap by the indicated number of bytes.
If numeric-expression& is positive, SETMEM attempts to increase the far heap by the number of bytes.

Usage Notes

If SETMEM cannot change the far heap by the requested number of bytes, it reallocates as many bytes as possible.
SETMEM can be used in mixed-language programming to decrease the far heap space so procedures in other languages can dynamically allocate far memory.
For more information on memory allocation, see Chapter 15, "Optimizing Program Size and Speed" in the Programmer's Guide.

Programming With OS/2 Protected Mode

The SETMEM function performs no other function than to return a dummy value. This value is the previous SETMEM value adjusted by the SETMEM argument. The initial value for SETMEM is 655,360.

Important

A first call to SETMEM trying to increase the far heap has no effect because BASIC allocates as much memory as possible to the far heap when a program starts.

Example

This example uses the SETMEM function to free memory for a C function that uses the C routine malloc to get dynamic memory.
Note: To run this program, you must separately compile the C function and put it in a Quick library or link it to the BASIC program. The C function must be compiled using the large memory model, so calls to malloc use the far space freed by the BASIC program.

DECLARE SUB CFunc CDECL (BYVAL X AS INTEGER)
 
'Decrease the size of the far heap so CFunc can use malloc
'to get dynamic memory.
BeforeCall = SETMEM(-2048)
 
'Call the C function.
CFunc (1024)
 
'Return the memory to the far heap; use a larger value so
'all space goes back into the heap.
AfterCall = SETMEM(3500)
 
IF AfterCall <= BeforeCall THEN PRINT "Memory not reallocated."
 
END
 
 
'/* C Function */
'void far cfunc(bytes)
'int bytes;
'{
'   char *malloc();
'   char *workspace;
'
'   /* Allocate working memory using amount BASIC freed. */
'   workspace=malloc((unsigned) bytes);
'
'   /* Working space would be used here. */
'
'   /* Free memory before returning to BASIC. */
'   free(workspace);
'}