BASIC

Compiles a DataBasic program.

Syntax

BASIC file-specifier item-list {(options}

Syntax elements

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

item-listOne 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 default compiler. (The default compiler is the one specified in the current operating environment or, if none, the one identified by the BASIC*DEFAULT synonym entry in the BASIC-COMPILERS system file.)

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.

I Generates an implicit list of item-ids for items that generate compilation errors.

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).

V Shows the name of the compiler to be used by BASIC command, and its version. This is either the default compiler or an alternative compiler specified by the C option.

Available compilers are identified by entries in the BASIC-COMPILERS system file; if necessary the V option resolves any synonyms.

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:

Note

  • 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 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.

History

The DataBasic history feature provides a mechanism to log history data to allow reporting and analysis of the usage of DataBasic programs, subroutines and external user functions. You create a separate HISTORY data section in your source files, and this section is used by the system to log the history usage of the code whenever it is complied and catalogued.

When any local source item is compiled and catalogued, a history log item with the same DataBasic program name is automatically written to the HISTORY data section of the source file (if such a section exists). Any previous history item is overwritten. The log item comprises the attributes shown in the following table (compilation is logged in attributes 1-7, cataloguing is logged in attributes 8-14).

Attribute

Description

1

Date of successful compilation (internal format)

2

Time of successful compilation (internal format)

3

PLID of successful compilation

4

ID of user requesting compilation

5

Account of successful compilation

6

Location of source (filename - including the data section, if appropriate)

7

Source item ID

8

Date of successful catalog (internal format)

9

Time of successful catalog (internal format)

10

PLID of successful catalog

11

ID of user requesting catalog

12

Account of successful catalog

13

Location of executable object (filename)

14

Executable item ID

Note

By default, nothing is logged; the user has to enable compile/catalogue history logging by adding the HISTORY data section.

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