Compiling Programs

Compiling a BASIC program converts the source code into a list of binary instructions called object code.

The TCL run command initiates a program called an interpreter that reads these instructions one at a time and executes the desired actions. Taking this interpretive approach allows swift translation from the BASIC source, platform independence, small object size, and reasonable performance.

If better performance is desired, the BASIC compiler can produce FlashBASIC, or native assembly code from a standard BASIC object. This FlashBASIC code can subsequently be run in the D3 environment in the same manner as a regular BASIC program with the exception that FlashBASIC code runs significantly faster.

Using the o option with the TCL compile or basic commands invokes FlashBASIC. When complete, the native code produced is appended to the standard interpreted object code. Because FlashBASIC generates independent code, the code does not need to be recompiled when moved to a different platform.

Producing FlashBASIC without Source

FlashBASIC can be used on an application lacking source code by using the w option when compiling. Therefore, an applications vendor does not need to ship source code or a new version of the object code. Customers equipped with FlashBASIC can compile their current applications as is. However, it is suggested that future applications be shipped with a BASIC program, Proc, or macro, that automatically produces the FlashBASIC code at the customer’s site.

Shipping FlashBASIC code is only recommended when a vendor wishes the code to run on a single platform, and when media size is not an issue.

Compiler Options

For a description of the various compiler options, see compile Command.

Performance Tips


Source code is compiled to a tokenized object code which is then interpreted when run.

For UNIX: Source code can be compiled in the traditional way, or it can be optimized or flashed.

For Windows: Source code can also be compiled in the traditional way, or it can be optimized or flashed. In this sense, though, the source code is compiled to an optimal tokenized object code which is then interpreted when run. This object code runs considerably faster than the original tokenized object code, but not as fast as the assembly language code of the C compiler.

FlashBASIC and BASIC Differences

This topic describes the differences between FlashBASIC and BASIC.

Platforms Supported

FlashBASIC is supported on AIX, Linux, and Windows.

Mixing FlashBASIC and Interpreted Code

If a mainline program is compiled with the o option, all of its subroutines must also have been produced with the FlashBASIC compiler.


FlashBASIC code is never run when called directly from a dictionary definition.

chain statement

The FlashBASIC chain statement can be used freely to transfer control to other programs, but variables are not restored if a run statement with the i option is attempted later. This restriction is the same for FlashBASIC applications that are involved in any way with the chain statement.

% calls

FlashBASIC currently supports calling C routines, but not assembly routines with the percent call. See the various FlashBASIC % functions.

FlashBASIC code allows a maximum of 62 parameters on an external subroutine call.

rnd() function

Calls the host operating system’s random C function.

FlashBASIC Debugger

The FlashBASIC debugger does not:

  • support logical conditions on breaks.

  • allow any arguments on the g command.

  • actually do anything when it displays object verifies with the $ command.

  • allow continuing after an abort.

  • patch variables in the debugger after a warning message.

  • allow the use breakpoints when in the break off state.


If using the (f option, all arithmetic operations use the host machines arithmetic.

Parameter Passing

FlashBASIC passes parameters by reference, rather than with copy-restore (except for constants and expressions that are passed by copy). This can cause problems in some cases. For example, if a subroutine is called with the statement call x(y, y(10)), where y is an array, and within that subroutine y(10) is modified, the current interpreter can restore the value differently than in the compiler.

FlashBASIC allows a maximum of 62 arguments on subroutines.

FlashBASIC does not complain when the number of parameters passed does not equal the number of parameters contained in the subroutine. However, this is not supported and can cause subsequent program failure and data corruption.


Array bounds checking is absent in FlashBASIC by default, but can be invoked with the b option when compiling. Use this feature with caution, because it can destroy other program data due to application bugs.

Named Commons

FlashBASIC and non-FlashBASIC do not share the same named common space.

Named Common variables

Named Common variables are not shared between FlashBASIC and BASIC programs run during the same logon session.


In FlashBASIC, variables are assigned a data type at assignment time: string or numeric. If the value assigned to the variable is a non-numeric literal, only the string flag is set. If the value assigned is a numeric literal, both flags are set. If any numeric operation is performed successfully upon the variable, the string flag is set off and the numeric flag is set on.

When two variables are compared, their type flags are checked for compatibility. If both fields have their string flags set, the computer performs a string compare ("001" # "1"). If both fields have their numeric flags set and neither has a string flag set, a numeric compare ("001" = 1) is performed.

It is important to note that this behavior can be controlled by the use of "+0" to normalize numeric variables and force numeric compares; while ":' '" concatenates a space, forcing the numeric flag off and forcing string compares.

Retrieval Lock error messages

When running a BASIC program that opens a Q-pointer that points to an md with a retrieval lock, if the user’s key does not match the retrieval lock key:

For BASIC: The system displays the message access protected.

For FlashBASIC: The system displays fn.q is not a file name.

readt statement

If a readt is attempted without a device attached, BASIC takes the else clause with system(0) = 1, but FlashBASIC attempts the read.

abort statement

If a subroutine encounters an abort statement, processing returns to the calling program.

open statements (Windows Only)

For BASIC: The open statement try to open the requested file in the VME.

For FlashBASIC: The open statement will first try to open the requested file in the FSI, then try to open the requested file in the VME.

match statements

Invalid match patterns may produce different results between FlashBASIC and BASIC programs.

Assignment Statements

Assignment statements in flash-compiled BASIC programs do not interrogate the values assigned to the variables. As a result, "Variable has not been assigned to value: zero used" messages will not be reported on the same lines as they would have been in a non-flash-compiled program.

Using pick functions as parameters in % function calls

For BASIC: Supported

For FlashBASIC: Not Supported

Shared memory segment

Files names greater than 55 characters in length and file and program names with a combined length greater than 62 characters are not uniquely identifiable in a shared memory segment. Additionally, if a program name is not the same in both attribute 0 and attribute 4 of a cataloged subroutine, performance will be degraded.

Number of concatenations allowed in a single statement.

The maximum number of concatenations allowed in a single statement when flash-compiling is 253.

return to statement

If the return to statement is used incorrectly in FlashBASIC it will be treated as a return. In non-Flash, it will abort.

User Exits

Some user exits may function differently in FlashBASIC vs. non-Flash. For example:

  • The u8f user exit will produce different results in FlashBASIC and non-Flash.

Error Logging

This topic describes how to record compiling errors when using FlashBASIC. Errors encountered during runtime are logged to the DM,RUNTIME-ERRORS file. These errors can be displayed by using the TCL command LIST-RUNTIME-ERRORS

When compiling FlashBASIC programs with the o option, the compiler automatically logs all compilation errors if a data section called $log is present in the user's BASIC program file. The log is updated only when errors occur. Each log entry's ID is the same as the ID of the item being compiled.

The first attribute of the entry consists of the time and date that the error occurred as well as the phase of compilation where the error occurred. Other attributes can contain additional undefined information can contain UNIX error messages.

For UNIX: Not supported

For Windows: FlashBASIC runtime errors can be logged to the Windows event log. This feature is set from the FlashBASIC tab of the D3 Device Manager (see the D3 System Administration Guide for more information).

A Windows event log entry has the following format:

Runtime error <err> @ <progname>:<lineno>



FlashBASIC error message item-ID.


Item-ID of the FlashBASIC module.


Source line number.

Additional information can also be logged in the Data section of the Windows event log (accessible through the Event Detail dialog box in the Windows event viewer). For example:

Runtime error B12 @ myprog:15

B12 is a file has not been opened error, occurring in module myprog at line 15.


To enable logging for a file called bp, type:

create-file bp,$log 7

Compiling using the o option now logs errors into the bp,$log file. These can be displayed by typing any of these commands:

ct bp,$log

list-item bp,$log

sort-item bp,$log


There are three methods for increasing performance:

Replacing dynamic arrays with dimensioned arrays is especially effective when an item is read from a file and extensively manipulated afterwards. If the number of attributes in the item is known, the matread statement can be used to read the dynamic string into a dimensioned array. If the size is not known or subject to change, read the item into a dynamic array and use the dcount function to get the number of attributes, redimension a dimensioned array to the desired size, and assign the dynamic array to the dimensioned array. For example:

equ am to char(254)

read xx from "big.item"

size = dcount(xx,am)

dim stat(size)

stat = xx

Another way to increase speed is using named commons to store data that must be used between various applications. If named commons are used for this purpose, all applications involved must be compiled with either the interpreter or with FlashBASIC.

If an application performs large amounts of screen output, it is suggested that screens be built as large strings at the beginning of the program. This way, a screen refresh prints the string variable.



print x

BASIC Symbolic Debugger

The BASIC symbolic debugger facilitates the debugging of new BASIC programs and the maintenance of existing BASIC programs. The BASIC debugger requires sys2 privileges and has these general capabilities:

The BASIC debugger can be entered at execution time when:

When the BASIC debugger is entered, it indicates the source code line number to be executed next and prompts for commands with an * asterisk.

See Also

# Command, Access Query Language, basic Command, BASIC/FlashBASIC Debugger, C Functions Overview, call Statement, common Statement, compile Command, Creating User-Defined C Functions, down Command, execute Statement, run Command, term Command, up Command, \ Command