TCL.COMPILE Verb: Access/TCL

TCL.COMPILE

Command TCL.COMPILE Verb: Access/TCL
Applicable release versions: AP, AP 6.1, R83
Category TCL (746)
Description The "compile" verb invokes the Pick/BASIC compiler and translates the specified source code into executable object code with case insensitivity.

Case "insensitivity" means that the variables "TOTAL", "Total" and "total" all represent the same symbol. A case "sensitive" state would treat these as three separate variables.

Each line of the source program is scanned for syntax errors during compilation, even after an error has been detected.

Releases prior to 6.1 print an "*" (asterisk) for every line of code. Releases 6.1 and later display a "." (period) for every 10 lines of code. This change allows compilation to proceed much faster.

If an error is encountered, the line with the error and the error message are displayed; no object code is produced. The "q" option prevents the messages from scrolling past on the terminal.

If the "o" option is used, FlashBASIC is invoked after the first stage of compilation is complete. When all stages are completed, and if no errors are found, the compiled form is saved and can be executed using the "run" verb. The program may also be "cataloged" with the "catalog" verb.

"itemlist*" consists of one or more source program names, separated by spaces. If no name is specified, or if an asterisk (*) is used, all programs in the file will be compiled.

Programs may be created and modified using UP. They can be compiled when exiting UP by using either the <ctrl>+xc command, which compiles and catalogs the program, or the <ctrl>+xr command, which compiles and runs the program. Any other editor may also be used.
Syntax compile file.reference itemlist* {(options}
Options a Displays object code generated by Pick/BASIC compiler.

b Turns on array bounds checking when used with the "o" option. Without this option in effect, situations such as "array subscripts out of range", which would formerly result in a "fatal" Pick/BASIC debugger abort, will ignore the condition, possibly resulting in a monitor halt (AP 6.0 FlashBASIC only).

c Compresses the object by suppressing the end-of-line (EOL) opcodes from the object code item. This option is designed to be used with debugged and cataloged programs. Because the EOL opcodes are used to count lines for error messages, any runtime error message in a program compiled with the "c" option will indicate the error is on line 0. Additionally, the "c" option removes the ability to single-step with the Pick/BASIC debugger.

d Prevents the run-time "d" option from entering the debugger.

e Lists only error lines encountered during the compilation of the program. The listing indicates line number in the source code item, the source line itself, and a description of the error associated with the line.

f When used with the "o" option, generates floating point arithmetic.

h Hides FlashBASIC object code from other users. In other words code is not shared.

i Lists lines from any included program as part of the listing. If used with the "l" option, the source program listing, the included lines are indicated by a "+" after the line number.

k Keeps a shared, FlashBASIC module loaded. See the "shpstat" program for more information about shared loading.

l Generates a line by line listing of the source program during compilation. Error lines with associated error messages are indicated. When the "l" option is used, "*"'s are not displayed. Each line of the listing takes the place of the "*".

m Generates a program "map" of the descriptor table and correlates source code lines to generated object code frames. Each variable in the program is listed along with its decimal offset.

n No pause; suppresses pause at end of page on terminal display.

o{level.number} Produces FlashBASIC native code for the host machine. This option may be followed by a number from 1 to 9, which indicates the FlashBASIC (optimization) "level". If not specified, the level defaults to 1, which gives a large performance increase while minimizing compile time and object size. Note that if any module in a program is compiled with the "o" option, then all modules in that program must also have been compiled with the "o" option. FlashBasic programs will NOT generate array bounds checking. Also, optimization levels higher than 1 increase object size by as much as 100% over that achieved with level 1, and increase compile time exponentially. Furthermore, levels above 1 yield relatively small performance increases for most applications. High levels also tend to use very large amounts of Unix swap space. If the system runs out of swap space, FlashBASIC retries with a lower level. Line numbers (for error messages) and the state of variables within the debugger are also not guaranteed when using a level greater than one. Finally, the exact behavior of a specific level above one is undefined and may be different on different platforms or releases. See the related subjects on FlashBASIC for more information.

p Routes all output generated by the compilation, except the cross-reference listing, to the printer, via the Spooler.

q Activates page mode on errors; if more than one screen-full of error messages display, this will prevent the first (and usually most important) error message from scrolling past without being able to read. (R83 only)

s Suppresses generation of symbol table. The symbol table is used exclusively by the Pick/BASIC debugger for reference; therefore, it needs to be kept only if the user wishes to use the debugger.

x Creates a cross-reference of all the labels and variables used in the Pick/BASIC program and stores this information in the "bsym" file, which must exist before using. The "x" option first clears data in the "bsym" file, then creates an item for every variable and label used in the program, using the variable or label name as the item-id. After creating the cross-reference items, attribute one contains the line numbers where the variable or label is referenced; each line number is a value. The line number where a label is defined, or where the value of the variable is changed is preceded by an asterisk (*). If the variable names and labels are in both upper and lower case, the "d-pointer" for the "bsym" file-defining item should not have the "s" option.

w Optimizes without source when used with the "o" option. This allows optimizing programs without source code. This option requires a list of the items in the dictionary level of the file to be active prior to use. Note that the normal dictionary object statistics are not updated when this option is used.

y (AP only) Allow multiple FlashBASIC compiles concurrently. Normally, each FlashBASIC compile attempts to set BASIC lock 49 to keep multiple compiles from dramatically slowing down the machine. The Y option avoids this logic.

y (R83 only) Provides compilation statistics, including: the start clock time in milliseconds, the size of the code in bytes, the size of the descriptor table, the size of the symbol table in bytes, the number of symbol table entries, and the end clock time in milliseconds.

On AP/Unix releases, default options may be stored in attribute 6 of the "compile" item in your master dictionary. For example, putting an "o" in this attribute makes all compiles in that account produce FlashBASIC code.
Example
compile dm,bp, term-type (lp

This compiles the "term-type" program and sends the listing to the 
printer.

compile bp j (oc

This creates a FlashBASIC native object module which may be run from Pick as if 
it were an interpreted Pick/BASIC program.  The "c" option is used 
primarily to reduce object size and compile time, both of which can be 
significantly greater when using FlashBASIC.

select dict bp.old

[404] 114 items selected from 114 items.

compile bp.old (ow

This creates FlashBASIC code for all the Pick/BASIC object pointers in 
"bp.old".  There is no need to have the source present.

ct md compile

001 VR
002 3]9
003 F
004 dm,bp, :ccompile
005 
006 o

 Notice that an "o" was placed in attribute 6. This verb, when 
invoked will always Flash compile programs. (see o option)
Purpose
Related filename.bsym
flash.basic
compile.time.date.stamp.ap
tcl.compile-run
compile.time.date.stamp.rp
basic.performance
flash.basic.error.logging
basic.debugger.edit
tcl.config.core
system.debugger.g
tcl.compile-catalog
basic.debugger.overview
access.c/options
access.c/bytes
access.c/flash
access.c/fid
access.c/size
access.c/date
access.c/time
access.c/port
access.c/user
access.c/acct
access.c/release
basic