BASIC

BASIC

Top  Previous  Next

 

The BASIC verb runs the QMBasic compiler.

 

 

Format

 

BASIC {file.name} {record.name...} {options}

 

where

 

file.nameis the name of the directory file holding the QMBasic source program. If omitted, the filename defaults to BP.

 

record.nameis 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.

 

optionsare as listed below.

 

 

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.

 

 

The following options are accepted by the BASIC verb

 

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

 

CHANGEDCompile 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 it enables all modified programs to be compiled with a single command.

 

CONCORDANCEGenerate concordance data (see below).

 

LISTINGGenerate a compiler listing record with a .LIS suffix.

 

NO.PAGESuppress pagination.

 

NO.QUERYSuppresses any queries that the compiler may generate such as replacement of a catalogued item, taking the default action.

 

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

 

XREFGenerates 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, will be created automatically if it does not already exist.

 

 

@SYSTEM.RETURN.CODE is set to the number of programs successfully compiled. It will contain a negative error code in the event of a fatal error.

 

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

 

 

The $BASIC.OPTIONS VOC Record

 

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.
CONCORDANCEGenerate concordance data (see below).
DEBUGGINGCompiles the program in debug 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.
INCLUDE {file} idInsert the named include record after processing the PROGRAM, SUBROUTINE, FUNCTION or CLASS statement.
LISTINGGenerates a listing record in the compiler output file.
MODE option.nameSets the given compilation mode as described for the $MODE compiler directive. Multiple MODE lines must be used to set more than one option.
NOCASE.STRINGSCompiles the program with case insensitive string operations. See the $NOCASE.STRINGS compiler directive for more details.
NOXREFCompiles the program with no cross reference tables. This results in slightly lower memory usage but prevents QM producing detailed messages in the event of an error.
NO.PAGE or NOPAGESuppress pagination.
SEARCH filename.listSpecifies 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

SEARCH @, SYSCOM

WARNINGS.AS.ERRORSCauses the compiler to treat warning messages as fatal errors.
XREFGenerates a listing record in the compiler output file, including a cross-reference table of all variables and their use.

 

Unrecognised keywords in this record are ignored.

 

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

 

 

The $BASIC.IGNORE VOC Record

 

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:

1: X

2: ...'.H'

3: ...'.SCR'

 

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:

1: X

 

 

Concordance Data

 

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

 

Show a simple list of what subroutines are called from each program

LIST BASIC.CONCORDANCE

 

Find all the programs that reference subroutine MYSUB

LIST BASIC.CONCORDANCE WITH REF = "MYSUB"

 

Show a list of which programs call each subroutine

LIST BASIC.CONCORDANCE WITH REF BY.EXP REF BREAK.ON "'OL'" REF @ID ID.SUP

 

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.

 

 

Examples

 

BASIC PROGRAMS PROG1 LISTING

 

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

 

 

SELECT BP

BASIC CHANGED

 

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.

 

 

See also:

CATALOGUE, DELETE.CATALOGUE, MAP