LONG: Memory Management in QuickBasic & Basic Compiler

Programmers may want to understand how Microsoft QuickBasic and Microsoft Basic Compiler arrange memory in order to write programs that make efficient use of system resources. The QuickBasic language provides a variety of data types and modular code constructs that allow you to manage the data and code of your programs.

This article covers the following topics:

1. Code management
   
   
   1. Modular programming
   2. What goes at the module level in a support module
   3. COMMON, COMMON SHARED, SHARED, DIM SHARED
2. Data management
   
   
   1. $DYNAMIC and $STATIC metacommands
   2. Huge arrays

Appendix A contains a code example to illustrate the topics covered in this article.

Appendix B explains the .MAP file created when the Appendix A program example is linked. You can use the LINK map to determine how close each module is to approaching the 64K code limit and how close the .EXE program's static variables are getting to the 64K limit in the DGROUP.

Appendixes C and D describe in detail the memory mapping for running programs in the following three different environments: the QB.EXE editor, a compiled .EXE program using the run-time module, and an .EXE compiled with the stand-alone option.

Definitions

A "module" is defined as an individual source file containing Basic procedures.

"Module-level code" is defined as the statements within a module that are outside a SUB...END SUB, FUNCTION...END FUNCTION, or DEF FN..END DEF definition block.

A "support module" is a source file, separate from the main module, that contains additional SUB or FUNCTION procedures.

CODE MANAGEMENT

Modular Programming

Modular programming deals with splitting programs into separate modules (i.e., separate source files containing SUB or FUNCTION procedures). The reasons for doing this are the following:

1. Once you have written a block of code as a module, it can easily be incorporated into future projects.
2. Debugging is easier. Problems can be located much more quickly and can be contained in a specific area of the program.
3. The compiler (BC.EXE) and the environment (QB.EXE) have a 64K code limitation per module. A modular style of programming allows you to create programs larger than 64K, since every module, even though it is part of one program, can be up to 64K in size.

If a program is large, it may be necessary to break it up into several modules. This is easily accomplished by breaking SUB or FUNCTION procedures out of the main module and placing them in support modules. These modules are then compiled separately with BC.EXE and LINKed with the main module as in the following example.

Consider a program Main.BAS, which is broken into three modules:

1. MAIN.BAS (which calls external procedures)
2. MODULE2.BAS (which contains SUB and/or FUNCTION procedures)
3. MODULE3.BAS (which contains SUB and/or FUNCTION procedures)

The three modules are then each compiled separately to produce the following object files:

1. BC MAIN.BAS; ----> MAIN.OBJ
2. BC MODULE2.BAS; ----> MODULE2.OBJ
3. BC MODULE3.BAS; ----> MODULE3.OBJ

To produce the executable (.EXE) program, the following command line is used: Main.EXE is the finished executable program. When you compile in QuickBasic's environment (QB.EXE), the environment automatically compiles each module and LINKs them together to produce the same .OBJ files and finished executable program.

To make an .EXE program from the QB.EXE environment, do the following:

1. Choose the Run menu.
2. Choose the Make EXE File... option.
3. Choose the Stand-Alone EXE File option to create a stand-alone file. If this option is not selected, the program requires that the BRUN4x.EXE run-time module be present at run time.
4. Press the ENTER key.

The QuickBasic environment gives you an easy way to do the following operations, which are described further below:

1. Create a new Module for SUBs
2. Edit SUBs and Modules
3. Delete SUBs
4. Move SUBs from one Module to another Module

In QB.EXE, to create a separate module (source file) for SUBs, do this:

1. Choose the File menu.
2. Choose the Create File... option.
3. Enter the name for the module.
4. Press the ENTER key.

A file will then be created with the name you specified, and it will be in memory with the other module(s). To save all of the loaded modules, do the following:

1. Choose the File menu.
2. Choose the Save All option.

When the modules are saved together, QuickBasic creates a file (with the extension .MAK) that keeps track of the main module and the other modules that are used by the main. To load all the modules in at once, do the following:

1. Choose the File menu.
2. Choose the Open Program... option.
3. Select the main module of program as the file to be opened.

To view and select SUBs for editing, do the following:

1. Choose the View menu.
2. Choose the SUBs... option.
3. Highlight the module or SUB that you want to edit.
4. Tab down to Edit in Active, or Edit in Split.
5. Press the ENTER key.

To delete a SUB, do the following:

1. Choose the View menu.
2. Choose the SUBs... option.
3. Highlight the SUB you want to delete.
4. Tab down to the Delete option.
5. Press the ENTER key.

To move a SUB to a different module, do the following:

1. Choose the View menu.
2. Choose the SUBS... option.
3. Highlight the SUB you want to move.
4. Tab down to the Move option.
5. Press the ENTER key.
6. Select the module you want the SUB to be in.
7. Press the ENTER key.

For more information about using the QB.EXE environment, please see the "Microsoft QuickBasic: Learning to Use" manual for version 4.50, or see the "Microsoft QuickBasic 4.0: Learning and Using" manual for versions 4.00 and 4.00b and the Basic compiler versions 6.00 and 6.00b.

What Goes at the Module Level in a Support Module

A support module, when compiled, produces an object (.OBJ) file that is LINKed with a main module to create an executable file. The module-level code of the main module is the only code directly executed by QuickBasic. The module-level code of the support modules cannot be CALLed, RUN, or CHAINed. This module-level code of the support modules is used only for:

1. Event- or error-trapping handlers
2. Metacommands
3. TYPE definitions, DIM, and COMMON SHARED statements

You can place ON Event GOSUB and ON ERROR GOTO trapping statements within SUBprogram procedures [where ON Event means ON KEY(n), ON COM(n), ON TIMER(n), etc.]. However, the line or line label that is the target of the event or error trap's GOTO or GOSUB must be at the module-level code in the same module as that SUBprogram. This is because QuickBasic doesn't allow GOSUBs or GOTOs from a SUBprogram to other modules or SUBprograms, and QuickBasic allows only ON Event GOSUB and ON ERROR GOTO statements to jump from a SUBprogram to the module-level code.

The compiler metacommands (REM $INCLUDE, REM $STATIC, and REM $DYNAMIC) can also be used at the module level. REM $INCLUDE pastes extra source into the module at compile time. REM $DYNAMIC and REM $STATIC declare subsequent arrays as $DYNAMIC (allocated at run time) or $STATIC (allocated at compile time).

You can use TYPE...END TYPE, DIM, and COMMON SHARED statements in the module-level code. Variables and arrays can be shared between modules using the COMMON SHARED statement at the module level.

COMMON, COMMON SHARED, SHARED, and DIM SHARED

The SHARED statement gives a SUB or FUNCTION procedure access to variables declared at the main module level of that module (without passing them as parameters). It does NOT give access to variables declared in support modules.

The COMMON statement makes variables available at the module level between modules. The SHARED attribute for the COMMON statement (i.e., COMMON SHARED) is required to share the variables with SUBprograms or FUNCTIONs. The list of variables in the COMMON and COMMON SHARED statements must match in type in the COMMON and COMMON SHARED statements in each module.

When using the COMMON (or COMMON SHARED) statement, static and dynamic arrays are dimensioned differently. Static arrays in COMMON must be DIMensioned BEFORE the COMMON statement in all the modules with that COMMON statement. Dynamic arrays in COMMON must be DIMensioned AFTER the COMMON statement in just the main module and should not be DIMensioned in any support modules.

There are two differences between using the SHARED statement and the DIM SHARED statement:

1. To make a variable accessible by all the SUBprograms in a module, use DIM SHARED at the module level.
2. To share a module level variable with a specific SUBprogram, put the variable in a SHARED statement in the SUBprogram. The SHARED statement goes directly after the first line of the SUBprogram.

DATA MANAGEMENT

$DYNAMIC and $STATIC Arrays

The default setting for storing arrays is REM $STATIC, which stores all arrays in DGROUP (the default data segment). For any Basic .EXE program, DGROUP is limited to 64K. If you are using static arrays, you can get more memory in DGROUP by making the arrays dynamic, which moves them into the far heap. To make an array dynamic, DIMension the array after the metacommand REM $DYNAMIC, or DIMension the array with a variable in its subscript.

All dynamic arrays are stored on the far heap except arrays of variable- length strings. Strings, variable-length string arrays, and simple variables are always stored in DGROUP. To store strings in the far heap, you must DIMension a dynamic array of fixed-length strings. DIMensioning strings as fixed length in dynamic arrays helps to free up storage space that they otherwise could have taken in DGROUP, which is limited to 64K.

Huge Arrays

Huge arrays are arrays that are larger than 64K. When using huge arrays, you must invoke the QB.EXE editor and BC.EXE compiler with the /AH option. The huge array must be DIMensioned as a dynamic array, either with a variable in the array subscript or with the preceding metacommand REM $DYNAMIC. The /AH option allows dynamic arrays of user-defined types, fixed- length strings, and numeric data to occupy all of available memory.

The number of bytes in a single element of a huge array should preferably be a power of 2, in order to avoid wasted memory and to enable arrays to be larger than 128K, as explained below.

Space is allocated for a huge array contiguously in the far heap, with the restriction that no single array element (or record) is allowed to be split across a 64K boundary. If a record size is not a power of 2, the array is allocated at an offset high enough, relative to the array's base segment address (returned by the VARSEG function), such that no array element is split across the boundary at exactly 64K above the base segment. The value returned by the VARPTR function for the first element of the array then indicates both the offset of the array, and also the size of a gap created in far heap. This gap fragments the far heap, and is wasted, unused memory. The size of the gap is equal to (65,536) MOD (array record size). [In the worst case, the gap can be up to (array record size) minus 1 in size.]

A "Subscript out of range" error occurs when allocating a huge array larger than 128K if the array elements have a size that is not an even power of 2. Arrays larger than 128K must have an element size that is a power of 2 (2, 4, 8, 16, 32, 64, etc.), since arrays are stored contiguously and no single array element is allowed to be split across a 64K boundary.

The final major aspect of QuickBasic memory management is that QuickBasic attempts to make efficient use of memory, which may cause variable-length strings, variable-length string arrays, and dynamic arrays to move around in memory from statement to statement at run time. (Other variables have a fixed location determined at EXE load time.) In addition, if you perform a CHAIN statement, then any data passed in a COMMON block may move. This means that the results of the VARPTR, VARSEG, VARPTR$, or SADD function should always be used immediately after that function is invoked.

APPENDIX A: SAMPLE PROGRAM

This sample program demonstrates the topics covered in this article. This program gives an example of ways to DIMension arrays, and to pass variables between modules and SUBprograms. The program consists of two modules, each which defines one SUBprogram.

Main Module (EXAMPL1.BAS)

Support Module (EXAMPL2.BAS)

APPENDIX B: LINK .MAP FILE EXPLANATION

Below is a .MAP file created when the program example in Appendix A is linked. The .MAP file from a successful link shows how close a module's code segment is approaching the 64K code limit, and how close the static variables for the entire .EXE program are to approaching the 64K limit in the DGROUP. To generate a listing map of a program, include a map filename in the third argument of the LINK command, as in the following example: Notes for the link .MAP shown further below are as follows:

1. EXAMPL1_CODE is the code segment for EXAMPL1.BAS.
2. EXAMPL2_CODE is the code segment for EXAMPL2.BAS.
3. The code segment of each module has to be less than 64K. When the code segment is getting close to 64K, break the module into two or more modules. To find the length of a code segment, look under the Length column. For example, the length of the code segment for EXAMPL1.BAS is 15A hex bytes, which is 346 in decimal notation.
4. FAR_MSG is the far management group that holds text of error messages. This is NOT the far heap. The far heap is allocated at run-time.
5. According to the Origin section at the bottom of the link map, DGROUP starts at 06DC:0, which is the paragraph address 06DC hex, with an offset of 0. This is the same as the byte address 06DC0 hex (since a paragraph contains 16 bytes). Thus, in this example, DGROUP starts where BR_DATA starts.
6. DGROUP ends at the Stop address of the STACK.
7. To find out how large the program's DGROUP is, take the Stop address of the stack and subtract from it the Start address of the first data element in the DGROUP. For example, the size of the program's DGROUP is 7F9F hex minus 6DC0 hex, which equals 11DF hex (4575) bytes.
8. All addresses in the .MAP are only relative to the start of the .EXE program. The absolute load address is determined by DOS only at run time. The VARSEG and VARPTR statements can be used in your program at run time to display the absolute addresses of the variables.

EXAMPLE.MAP

APPENDIX C: WHERE QuickBasic 4.00, 4.00b, AND 4.50 STORE THEIR ARRAYS

There is one difference in array storage between programs run as compiled .EXE files and programs run within the QuickBasic versions 4.00, 4.00b, and 4.50 environment (QB.EXE). In the QB.EXE environment, an array that is static, not in COMMON, and not composed of variable-length strings, is stored in the far heap (instead of DGROUP, as in .EXE programs).

This changes memory management in your program, depending on where you run your program.

Thus, in programs run within the QuickBasic 4.00, 4.00b, or 4.50 environment (QB.EXE), arrays are stored as follows:

1. All $STATIC arrays in COMMON are stored in DGROUP and can be referenced with near addresses.
2. All arrays of variable-length strings are also stored in DGROUP and can also be referenced with near addresses.
3. All other arrays are stored as far objects and require far addresses. This includes $STATIC arrays that are not in a COMMON statement, and these arrays can move in memory like $DYNAMIC arrays.

In QuickBasic 4.00, 4.00b, and 4.50 programs that are run as compiled .EXE files, arrays are stored as follows:

1. All $STATIC arrays are stored in DGROUP and can be referenced with near addresses.
2. All $DYNAMIC arrays of variable-length strings are also stored in DGROUP and can also be referenced with near addresses.
3. All other $DYNAMIC arrays are stored as far objects.

APPENDIX D: MEMORY MAPS

This appendix contains one general memory map and three detailed run-time memory maps.

General Memory Diagram

The following diagram summarizes how QuickBasic compiled programs are loaded into memory at run time: The following Figures 1, 2, and 3 describe in more detail the arrangement of code and data in memory at run time.

Figure 1

The first figure (below) shows the run-time memory map when the program is executed within the QB.EXE version 4.x environment: Figure 1 (above): The Memory Map for QB.EXE 4.x Environment

Figure 2

This second figure (below) shows the run-time memory map as it appears when the run-time module BRUN4x.EXE is used with the separate compilation (Make EXE File...) method: Figure 2 (above): The BRUN4x.EXE Run-Time Module Memory for an .EXE

Figure 3

This third figure (below) shows the run-time memory map when the stand- alone library (BCOM4x.LIB) option is used with the separate compilation (Make EXE File...) method: Figure 3 (above): The Stand-Alone (BCOM4x.LIB Library) Memory for an .EXE