Q(uick)BASIC Statement: CLEAR

Quick View

CLEAR

A memory management statement that reinitializes all program variables, closes files, and optionally sets the stack size

Worth knowing

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

Syntax
  • CLEAR [,,stack&]
Description/Parameter(s)
stack& Sets the size (in bytes) of stack space for your program.

Closes all files, releases file buffers, clears all common variables, sets numeric variables and arrays to zero, sets string variables to null, and initializes the stack. Optionally, CLEAR also changes the size of the stack.

Example
CLEAR ,,2000

See also:

Syntax
  • CLEAR [,,stack]
Description/Parameter(s)
stack Sets the size (in bytes) of stack space for your program.

The CLEAR statement performs the following actions:

  • Closes all files and releases the file buffers
  • Clears all COMMON variables
  • Sets numeric variables and arrays to zero
  • Sets all string variables to null
  • Reinitializes the stack and, optionally, changes its size

The stack parameter sets aside stack space for your program. QuickBASIC takes the amount of stack space it requires, adds the number of bytes specified by stack, and sets the stack size to the result.

Note: Two commas are used before stack to keep QuickBASIC compatible with BASICA. BASICA included an additional argument that set the size of the data segment. Because QuickBASIC automatically manages the data segment, the first parameter is no longer required.

If your program has deeply nested subroutines or procedures, or if you use recursive procedures, you may want to use a CLEAR statement to increase the stack size. You may also want to increase the stack size if your procedures have a large number of arguments.

Clearing the stack destroys the return addresses placed on the stack during the execution of a GOSUB. This makes it impossible to execute a RETURN statement correctly and produces a "RETURN without GOSUB" run-time error message. Using a CLEAR statement in a SUB or FUNCTION produces a run-time error message that reads "Illegal function call."

Differences from BASICA

  • BASICA programs using CLEAR may require modification. In BASICA programs, any DEF FN functions or data types declared with DEFtype statements are lost after a CLEAR statement. In compiled programs, this information is not lost because these declarations are fixed at compile time.
Example

The following statement clears all program variables and sets aside 2,000 bytes on the stack for the program:

CLEAR ,,2000

See also:

Syntax
  • CLEAR [,,stack&]
Description/Parameter(s)
stack& Sets aside stack space for your program (in bytes).
  • The argument stack& sets aside stack space for your program. BASIC takes the amount of stack space it requires, adds the number of bytes specified by stack&, and sets the stack size to the result.
  • Two commas are used before stack& to keep BASIC compatible with BASICA. BASICA included an additional argument that sets the size of the data segment. Because BASIC automatically manages the data segment, the first parameter is no longer required.

Usage Notes

  • The CLEAR statement:
    Closes all files and releases the file buffers.
    Clears all common variables.
    Sets numeric variables and arrays to zero.
    Sets all string variables to null.
    Reinitializes the stack and, optionally, changes its size.
  • If your program has deeply nested subroutines or procedures, or if you use recursive procedures, you may want to use a CLEAR statement to increase the stack size. You may also want to increase the stack size if your procedures have a large number of arguments.
  • Clearing the stack destroys the return addresses placed on the stack during a GOSUB operation. This makes it impossible to execute a RETURN statement correctly and BASIC generates a "RETURN without GOSUB" run-time error message. If you use a CLEAR statement in a SUB or FUNCTION, BASIC generates the run-time error message, "Illegal function call."

Differences From BASICA

  • BASICA programs using CLEAR may require modification. In BASICA programs, any DEF FN functions or data types declared with DEFtype statements are lost after a CLEAR statement. In compiled programs, this information is not lost because these declarations are fixed at compile time.
Example

This example use the CLEAR statement to clear all program variables and to set aside 2,000 bytes on the stack for the program.

CLEAR , , 2000

See also: