SharkBase Reference Guide - APPENDIX A

The Compiler

Unlike most database management languages, which execute a program one command at a time, SharkBase compiles its programs - that is, it processes all the commands before it begins to execute them. Compiling is a major reason why SharkBase runs faster than other DOS database languages. Most of the time, the compiler will be invisible to you. However, compilation presents some advantages and restrictions that are unique to SharkBase, and we’ll outline these in this appendix.

A.1. What Happens at Compilation

Before a program can be executed, SharkBase must perform two tasks:

First, the program itself must be translated into compile form. In compiling a program, SharkBase converts its commands into a code that is speedily executed by your computer. In command lines with macros, only the command verb is coded; such lines are converted into SharkBase code later, when they are executed.

Why Not a COM or EXE File?

Many compilers for computer languages produce a single file with the COM or EXE extension; such files can be run without the compiler’s presence. Why doesn’t SharkBase produce such compiled programs?

Most compilers are made up of two parts. First is the compiler itself, the program that does the translation. Second is the subroutine library; most compiled commands make a number of calls to this library.

At compilation, the compiled program is "linked" with the library (or with the part that is needed).

SharkBase, by contrast, does not link the compiled porgram to a library, since SharkBase itself remains active throughout the execution phase and can act as the library itself.

This has three major advantages:

1. The compiled programs can be far smaller, since none of the library is attached to each of them.

2. It is far easier to develop the user's application a small step at a time, since adding functionality to any one program probably has no effect on those already completed.

3. SharkBase has the compiler present at all times to evaluate and resolve macros during runtime, since macros are left uncompiled during compile-time. (Whenever it encounters a macro in a running program, SharkBase accesses the compiler, translates the macro, then continues execution).

Second, Sharkbase has to prepare the computer’s memory in order to keep track of information that the program uses and manipulates. The state of this memory space at any given time is called the environment.

Sharkbase always compiles a program before executing it. If you run a program in its text (PRG) form, SharkBase compiles it on the spot. The PRG file on disk is unaffected: if the program fails, you can still edit (or debug it) as needed.

Compiled Programs

You can store a program in compiled form on disk. The COMPILE command translates a named file with the PRG extension to a compiled program with the same filename, but with the extension CPL. This new, compiled file will load and begin execution more quickly. However, the compiled form in the CPL file can’t be edited directly. If you find an error in the program, edit the PRG file, then compile it again.

SharkBase always attempts to run the compiled version of a program first. It will run the PRG file only if it finds no compiled version on the disk.

You can also compile a list of programs; see the COMPILE command in the Shark Commands section.

In some ways, compiling is a "dry run" of the program: the compiler opens and closes the named data files, creates all of the memory variables (but types and values are not attached), sets up internal tables (stacks) for nested command structures, and tests expressions for validity (for form, not for variable types). The errors found at this stage are called compile-time errors.

It's important to remember that compiling a program is not exactly the same as executing it; rather, it is the preparation for speedy execution. Certain types of errors do not appear at compile time. These errors are called run-time errors. Most often they involve variables of the wrong type. Compile-time errors are always reported by SharkBase with the line number. Run-time errors report line numbers only if the line numbers are compiled into the program; this is accomplished with the SET LINE ON command (the default).

To understand the effect of the compiler on programs, it helps to know something about how the compiler reads the text of a progam and about how Sharkbase manages memory - its environment.

A.2. SharkBase Environment

The term environment refers to the current arrangement of memory, SharkBase’s "workspace." This is where SharkBase keeps track of all of the data files and variables being used, the program being executed, and other special settings.

The SET File

Sharkbase always runs under DOS, in what is left of the computer’s memory after DOS itself (and possibly some memory-resident programs and/or a network) are loaded. If total memoryis 640K, anywhere from 350K to 625K will be available to SharkBase. If not enough free memory is available, SharkBase cannot be run.

Sharkbase, however, allows high-memory to be limited to as little at 48K, and to allocate up to 32K for loading assembly~language modules assembled into binary files and executed from within Sharkliase Professional.

The DOS memory looks like this when fully loaded:

A. Top of DOS memory

1. External high memory (used by RUN commend)

2. BIN file space if any {BINSPACE=}

3. Internal high memory (MEMORY=)

4. Data space (643)

5. SharkBase (200K)

6. Memory—resident programs, if any (unload if necessary

7. Operating system (12-80K)

B. Bottom of DOS memory

The special files called SHARKSET and SHARKN.SET for the single-user and network versions of Sharkfiase respectively provide control over levels 2 and 3 (see these commands in the Reference Guide), while the FIELDS= command affects the allocation of memory within level 4. (NOEFFECTS is used to suppress screen and sound effects, and has no effect on the environment).

What is the Environment?

Sharkfiase takes control of all memory in levels 2 through 6, an area generally termed the "environment." Much of the environment remains constant, but we are concerned primarily with the items that can change.

Therefore, you can think of the environment, in part, as all data files that are currently open (with their respective fields) and the tile numbers assigned to them. Changing the set of open data files produces a different environment.

For example, these data file actions serve to establish and change the environment:

1. Opening a data file (with the USE command).

2. Assigning a file number to a data tile (SELECT, USE).

3. Closing a data file (CLOSE, CLEAR).

4. Changing the structure of a data file (MODIFY).

5. Opening or closing index files (USE, SET INDEX).

(To see a "snapshot" of the environment, give the STATUS command. This displays information about the current state of open data files, SET switches, and memory variables.)

Memory variables, too, are part of the environment, and the environment is affected when you create a new memory variable (with =, STORE, et al; see "Variables" in the Topical Reference) or release an existing one (RELEASE, CLEAR). The data-type and contents of the individual memory variables are not significant to the environment; what is important is the order in which they are created.

Sharkbase keeps track of the data files and memory variables by creating reference tables in memory. These tables are described in more detail later in this section.

Finally, there are specitic environmental commands: the SET commands (SET TO) and SET switches (SET. . .ON/OFF). They are used in conversational mode, in programs, and in the configuration file SHARK.CNF to customize SharkBase. For explanations of the individual SET controls, refer to the Shark Commands section.

The Configuration File

The configuration CNF file is a program that, if present, is automatically executed when you start SharkBase from DOS.

SHARKCNF can contain most commands. Its primary purpose, however, is to configure SharkBase’s default settings to your computer and to your applications. Typical commands in the configuration file are the SET commands and switches, in particular, SET DEFAULT, SET MEMORY, and SET FIELDS; values assigned to system variables and function keys, in particular, to :COl~/EANY; also, the structure FILES ENDFILES normally appears in this file.

A.3. SharkBase Memory Use

The table in Section A.2. illustrates how SharkBase uses memory (RAM) space: ShcrkBase itself utilizes about 200K of memory. To maximize speed, the EXE program is not overlayed so it all goes into memory at one time . . . an advantage of being kept "lean and mean".

Data Space

The following table illustrates the use of the 64K of data space reserved by SharkBase:

DOS work space (for Read buffers)

Data file table {Fields Table} Work space (about 25K) Includes: Program area Data Records (date file buffer) Indexes Relations Limit DOS etaok Internal data epace (fixed)

Data File Table

The data file table tracks all open data files. It includes an entry for each field of each data file in use, describing the field, and a pointer (a number indicating location in memory) to the data file buffer for the contents of the field.

Any time a data file is opened, a memory area, called a buffer, is set up for it, the size of one record. The size of the data file table is 320 fields, unless changed in the SET file by a FILES= command in SharkBase. For instance, the commands:

USE employee
USE#2 supplier
USE#3 invntory

set up a data file table like this:

  employee supplier  invntory  unused

Now if you close supplier:

the table becomes:
  employee  unused   invntory  unused

When the next file is opened, is goes into the vacant space if it has 17 or fewer fields, otherwise it goes after INVNTORY:

l>USE#2 order

yielding either

  employee  order   invntory  unused


  employee  unused   invntory   order   unused

Care must be taken to avoid creating too many "holes." As a suggestion, assign all files that never close to the lower file numbers (1, 2, 3, ). Then use the succeeding file numbers to put the transient files into use, in the order of their size (in fields), with the largest ones first.

If you run into an error message indicating that you’ve run out of space, then CLOSE ALL data files, and put the needed files into use again. This caution is necessary if you open and close data files more than once in a program, if you use commands that create files (COPY TO, TOTAL, SORT) or if you use commands that temporarily open data files (POST, APPEND FROM).

Data Records

An index file uses a buffer of about 256 bytes. Each relation established with SET RELATION, each filter set with SET FILTER, and each limit set with LIMIT or SCOPE commands, takes 128 bytes.

Program Space

Programs load and compile in this space. Certain other commands affect the amount of memory actually available for programs. The REPORT command needs about 5K, so programs that use REPORT must be 18K maximum. The number of bytes available in the program space is given by the SPACE() function and also by the STATUS command.

The Internal Data Space

The internal data space reserves all the memory Sharkflase needs for internal variables, stacks, and so on. The size of the internal Sharkflase data space is fixed by SharkBase; it may change from version to version. Since programs compile right on top of this space, all user programs may have to be recompiled whenever a new version of SharkBase is used.

The internal data space contains a number of important tables.

The Memory Variable Table

This table has 128 entries. It describes all the memory variables in use. For each variable, it contains a pointer (a number indicating location in memory) to the contents of the variable. The contents could be in the compiled text (some strings), in the memory variable storage table, or (for matrix variables) in high memory.

The Memory Variable Storage Table

This contains the contents of those memory variables not in the compiled text or stored as matrices in high memory. It is 4K in size.


Used during compilation and program execution, stacks are internal tables that keep track of the nesting structures IF and DO WHILE and DO commands. Various stacks are utilized by SharkBase. If too many levels of nesting are used, and one of these stacks runs out of room, an error message is issued.

Internal High Memory

The internal high memory usage is illustrated in the following table:
                 {External high memory)
       High—end of internal high memory
Matrix variables
Index buffers (16K—64K)
FILES table
screens 2, 3, 4 (4K each)
Temporary storage
Command lines
        Low~end of internal high memory
                           (Data space)

SharkBase uses 128K of high memory as internal high memory (unless MEMORY= is used in the SET file; see "External High Memory", below)

800 bytes are reserved for command line storage. Index buffers take a minimum of 10K; ordinarily, they take half of internal high memory, to a maximum of 64K.

The FILES table is created from the FILES ENDFILES structure.

Each matrix variable may occupy up to 64K of memory. There can be at most 20 matrix variables in use at one time.

The STATUS command displays the number of bytes left in high memory.

External High Memory

External high memory is essentially whatever is left over after SharkBase takes the amount it needs plus as much internal high memory and BINSPACE is requested or available, whichever is less. To maximize external high memory available to the RUN command, Sharkfiase users can reduce the amount of internal high memory requested; example MEMORY=64.