BASIC

Compiles a DataBasic program.

Syntax

BASIC file-specifier item-list {(options}

Syntax Elements

file-specifier The name of the file containing the DataBasic source code program. For details, see General Conventions.

item-list One or more item-ids, separated by blanks, or an asterisk (*) to compile all items not beginning with $, £, $$, ££, * or #.

Alternatively, item-list can be supplied by an immediately preceding list-generating command.

Options

C Prompts for the name of an alternative compiler to be used instead of the standard compiler installed on the database. See Using Alternative Compilers.

E Generates a program without end-of-line (EOL) opcodes. Option E reduces the size of programs by eliminating one byte from the compiled code for each line in the program. Because EOL is used to count lines, any run-time error messages indicate a line number of one. Do not use this option if debugging a program.

F Terminates the compilation when any error, even a non-fatal one, is encountered.

K Suppresses (kills) the output of asterisks during compilation.

L Outputs listing of the DataBasic program. Refer to the P option.

N Suppresses automatic paging of output.

P Sends DataBasic compiler error messages and other output to the printer.

R Creates both a deliverable (platform-independent) and an executable (platform-specific) item (see Generating Executable Code). This option is provided for compatibility with earlier versions of Reality.

S Suppresses the creation of the symbol map that is normally appended to the compiled item (do not use if debugging program).

X Outputs a cross reference of variables and labels used in the program - see The CSYM File for more details.

Operation

The BASIC command compiles a DataBasic program that was created using one of the Reality editors. It normally creates a new item containing the platform-independent deliverable code in the data section. The new item has the same name as the source item, but prefixed by a dollar or pound sign depending on the character in use (for example, compiling the item MY.ITEM will produce a deliverable item called $MY.ITEM). This deliverable item can be copied to other Reality systems and made available for use by simply cataloging it to generate an executable item – there is no need to copy the source code.

Generating Executable Code

An alternative mode of operation generates executable code instead of a deliverable item. This is placed in an item with the same name as that of the source, but in the dictionary of the file. There are several ways in which this mode can be selected:

You can set the EXEC.BASIC.OBJ environment option in your environment settings or using the SET-OPTION TCL command.
You can include the statement $OPTIONS EXEC.OBJ in your source code (either directly or in an included item).
You can use the (R option when compiling your code. In this case, both executable and deliverable items are generated. The deliverable item is placed in the data section with the source and has the same name as the source item, but prefixed by a dollar or pound sign.

A deliverable item can also be generated by including the statement $OPTIONS DEL.OBJ in your source code. This is only necessary if you are using the $OPTIONS EXEC.OBJ statement or the EXEC.BASIC.OBJ environment option.

Notes:

If the source item is in the dictionary of the file (for example, if the file concerned is a single level file), the executable item cannot be be given the same name as the source item. Instead, the item name is given the prefix $$ (or ££).
If you specify any of these options, you only need to catalog your program once. When you recompile, the executable item referenced by the command definition item is overwritten. With none of these options, you must recatalog to create a new executable item in the global POINTER-FILE.

Any deliverable and executable items produced by previous compilations are deleted.

Note: This feature is fully backwards compatible with earlier versions of Reality; all commands that access deliverable and/or executable items (RUN, DEBUG, etc.) support both current and previous compiler features.

Automatically Included Code

If the data section containing the source code contains an item called #AUTOINCLUDE, the code in this item will be automatically inserted at the beginning of each specified program module, following the PROGRAM or SUBROUTINE statement, if any. If the default data section of the file BASIC-COMPILERS in the SYSFILES account contains an item called #AUTOINCLUDE, the contents of this item will be inserted following the local auto-include item. See Including Common Code for more details.

Note: Local auto-include items should be used in preference to that in the BASIC-COMPILERS file.

Symbol Table

A symbol table is appended to the end of the compiled item.

The CSYM File

A file called CSYM must be present on the account before using the X option. If it is not already there, you must create it. X clears the CSYM file and then creates an item for each variable and label in the program. Each created item contains the line number(s) on which that label or variable is referred to. An asterisk (*) is appended to the line numbers where the variable value might change, such as an assignment statement (with the exception of function and subroutine parameters).

To list the contents of CSYM use the BREF command.

If the X option is used with an item-list mass compile, the X option will only be performed while compiling the first item in the item-list.

System Messages

If a DataBasic program is written incorrectly, compilation error messages are displayed as the program compiles. If the program does not compile successfully, the following message is displayed:

Line xxx [B100] Compilation aborted; no object code produced

If there are no errors in the program, it compiles successfully, with the following message:

Line xxx [B0] Compilation completed

Program Size

The size of the source code item is effectively unlimited. The maximum workspace limit of 16Mb is theoretically a limit on source code size.

Although, in theory, creation of a single large program gives maximum run time efficiency, it is recommended that a working limit of 4 or 8Kb is adopted, so that source code does not become unmanageable.

Viewing Program Headers

To display the time and date that a DataBasic program was compiled use the dictionary SYS.BASLIB (SYSFILES account) to list the file containing the program.

For example:

:LIST BP USING DICT /SYSFILES/SYS.BASLIB

Page 1 11:36:57 23 Jul 2004

Source......... Source................... Compile Compile.. Source...
File            Item                      Time    Date      Updated

SYSBP           ACCOUNTSCAN               11:41   03 Dec 03 03 Dec 03
SYSBP           SFM.SUB                   11:41   03 Dec 03 03 Dec 03
SYSBP           TL-DUMP                   11:41   03 Dec 03 03 Dec 03
SYSBP           TL-REDUAL-END             11:41   03 Dec 03 03 Dec 03

4 Items listed.

If you want to list an individual item, specify the name of compiled item (including the $ or £ prefix) and the dictionary items you require. For example:

:LIST BP '£ACCOUNTSCAN' ID-SUPP SOURCE.FILE SOURCE.ITEM COMP.TIME COMP.DATE SOURCE.UDATE USING DICT /SYSFILES/SYS.BASLIB

Page 1 11:38:36 23 Jul 2004

Source......... Source................... Compile Compile.. Source...
File            Item                      Time    Date      Updated

SYSBP           ACCOUNTSCAN               11:41   03 Dec 03 03 Dec 03

1 Item listed.

Note: To display the time and date that a specified cataloged DataBasic program was compiled use the PRINT-CATALOG command.

Example

:EDIT PROGRAMS TESTING
NEW ITEM
TOP
.I 
001 PRINT "THIS IS "
002 PRINT "A TEST"
003 END
004 					RETURN key pressed
TOP
.FI 
'TESTING' filed in file 'PROGRAMS'.

:BASIC PROGRAMS TESTING
***
Line 003 [B0] Compilation completed