BASIC

record.name

is the name of the record within the file. Multiple record names may be specified. An asterisk as the only record.name compiles all programs in the file. If no names are specified and the default select list is active, the list will be used to specify the programs to be compiled.

When using a select list or an asterisk to compile all programs, the default action of the BASIC command is to ignore records with a .H or .SCR suffix. This omits include records that use the conventional .H suffix (header files) or .SCR suffix (screen definitions). The $BASIC.IGNORE record described below allows developers to change the rules of which, if any, records are skipped when using a select list.

Unless the KEEP.OLD.OBJECT mode of the OPTION command is active, any old version of the object code is deleted before the compilation commences. This ensures that developers who accidentally miss a compiler error message will not continue testing with the previous version in the incorrect belief that it is the new version.

DEBUGGING

Include debugger control information in the compiled program. A program compiled in debug mode can be executed outside the debugger but will be slightly slower than when compiled without the DEBUGGING option.

CHANGED

Compile only if the program is not already in the output file or the date and time of modification of the source program record as given in the operating system directory entry is later than that of the compiled program. Used in conjunction with a select list or the * option, it enables all modified programs to be compiled with a single command. This option requires that file.name is a directory file.

NOXREF

Omit embedded cross reference tables in compiled program. This results in lower memory usage but run time error messages cannot identify source line numbers or variable names.

XREF

Generates a compiler listing record as for the LISTING option but includes a cross-reference table of all variables and their use. A line number in the cross-reference data will be followed by D on lines where the variable is declared, S on lines where the variable is set, and A if it is used as a subroutine or function argument.

The compiler output file, named as the source file but with a .OUT suffix, must be a directory file and will be created automatically if it does not already exist unless the file.name is a Q-pointer. The object code is stored in the output file using the same record name as the source. If a program listing is created, this is also placed in the compiler output file.

If all programs compile successfully, @SYSTEM.RETURN.CODE is set to the number of programs compiled. If any programs fail to compile, it will contain a negative error code.

Compiling a program signals an event to all QM processes to reload the object code. See the QMBasic CALL statement for full details.

Compiler options that you wish to use every time you run the QMBasic compiler can be placed in an X-type VOC record named $BASIC.OPTIONS. To apply these defaults only to programs stored in a specific file, place the $BASIC.OPTIONS record in that file. The compiler looks first in the source file (or the dictionary when compiling a C-type item) and then, if no record has been found, in the VOC.

The first line of the record holds the type code X. The second and subsequent lines of this record should contain compiler option keywords from the list below. The keywords allowed are:

CATALOGUE {LOCAL | GLOBAL {c}}

(American spelling allowed) Automatically catalogues programs after compilation using the program name as the catalogue name. The LOCAL and GLOBAL keywords may be used to specify that the program is to be catalogued in the given mode instead of in the private catalogue. When using GLOBAL, an optional prefix character, c, can be included. See the CATALOGUE command for more information. The NO.QUERY keyword can be added to suppress the query prompt that normally occurs if the program is already catalogued in some other mode. The $NO.CATALOGUE compiler directive can be used in specific program modules to override this action. Alternatively, the $CATALOGUE compiler directive in a program can set an alternative catalogue name or mode.

DEFINE name {value}

Defines token name in the same way as the $DEFINE compiler directive. The value may be a number or a quoted string. If omitted, the token is assigned a null string as its value.

MODE option.name

Sets the given compilation mode as described for the $MODE compiler directive. Multiple MODE lines must be used to set more than one option.

NOCASE.STRINGS

Compiles the program with case insensitive string operations. See the $NOCASE.STRINGS compiler directive for more details. This action is deprecated and replaced by MODE NOCASE.STRINGS.

NOXREF

Compiles the program with no embedded cross reference tables. This results in slightly lower memory usage but prevents QM producing detailed messages in the event of an error.

SEARCH filename.list

Specifies a comma separated list of file names where the compiler will look for include records if no file name is given in the $INCLUDE directive, in the order in which they will be searched. Use of the @ symbol as one of the names searches the file containing the program source record. If no SEARCH list is specified in the $BASIC.OPTIONS record, the default is to look in the file containing the program source record followed by SYSCOM and is equivalent to

Of the items listed above, only DEFINE, MODE, NOCASE.STRINGS and WARNINGS.AS.ERRORS are allowed in C-type items.

The default action of the BASIC command when using a select list or an asterisk to compile all programs is to ignore source records with a suffix of .H or .SCR. The $BASIC.IGNORE record allows developers to set their own rules controlling which, if any, records will be ignored. As with the $BASIC.OPTIONS record, the $BASIC.IGNORE record may be in the VOC or in the program file.

The first line of the record holds the type code X. The second and subsequent lines of this record contain pattern matching templates that are applied in turn to the source record id. If any of the templates match the source record id, the record is ignored. The default action of the BASIC command is equivalent to having a $BASIC.IGNORE record that contains:

Any record with an id that does not match any of the templates will be compiled. To compile all records, regardless of their name, create a $BASIC.IGNORE record that contains just the type code:

The QMBasic compiler can create a cross-reference of subroutine usage through an entire application. The compiler will automatically create a file named BASIC.CONCORDANCE if it does not already exist. Compiling all programs with either the CONCORDANCE option on the command line or via the $BASIC.OPTIONS record will then generate the concordance data.

The BASIC.CONCORDANCE file will contain a record for each compiled program. The record id in this file is the uppercase form of the name in the PROGRAM, SUBROUTINE, FUNCTION or CLASS statement or, if no such line is present, the uppercase form of the program source file name. Field 1 (named REF) of each record is a multivalued list of all the external modules referenced by the program. In the case of an indirect call, the name appears as the @ symbol as the compiler cannot determine the actual name.

Using this file, it is easy to use the query processor to find all references to a particular subroutine or other relationships. For example...

Recompiling a module with the CONCORDANCE option set will update the file. The only time it will be necessary to make manual changes to the file is if a source program is deleted and its corresponding concordance record can therefore also be deleted.

This command compiles the program in record PROG1 of the PROGRAMS file. A listing record is produced.

This sequence of commands compiles all programs in the BP file which have been updated since they were last compiled. Note that the compiler will omit all records with names ending with .H or .SCR, the two standard suffix codes for include records.