Compiling a program Compilation switches Compile-time error messages The LINK-80 linking loader LINK-80 error messages Storing your program on disk Running your compiled program Runtime error messages Using M80 :COMPILING A PROGRAM Is your BASIC program now saved in ASCII format on your diskette? (To save your program in ASCII format when using the interpreter, add an "A" switch to the "SAVE" command, as shown in SAMPLE SESSION, Step 3: SAVE "[.]",A Return to CP/M command level and enter: BASCOM BASIC will return the prompt: "*", informing you that the BASIC Compiler is loaded and ready to accept a command. Now enter the command of the form: objfile,lstfile=source file where objfile is the relocatable object file, lstfile is the listing file, and source file is the BASIC source program file. A command to BASIC conveys the name of the source file to be compiled, and the names of the file(s) to be created. With CP/M filenames are up to eight characters long with a three-character extension. The default filename extensions supplied to CP/M are: REL Relocatable object file LST Listing file BAS BASIC source file MAC MACRO-80 source file FOR FORTRAN-80 source file COB COBOL-80 source file COM Executable command file If you have a multi-drive system, you can tell the compiler where to obtain or put the files you are working with by adding a drive number to each filename. For example: A:MYPROG.REL=B:TEST finds the program TEST.BAS on the diskette that is in drive B, compiles it, and puts the object in MYPROG.REL (on the diskette that is in drive A). If a drive is NOT specified, the object and listing files are placed on the diskette that is in the default drive. Either the object file or the listing file or both may be omitted. An object file is created only if the lstfile field is filled. Therefore, if you wish to omit either, simply leave its filename out of the command. Examples: TESTOBJ=TEST.BAS Compile the program TEST.BAS and put object in TESTOBJ.REL without producing listing file. TEST,TEST=TEST Compile TEST.BAS, put object in TEST.REL and listing in TEST.LST. ,=TEST.BAS Compile TEST.BAS but produce no object or listing file. Useful for checking for errors. RABBIT=TEST Compile the program TEST.BAS and put object in RABBIT.REL without producing listing file. :BASIC COMPILATION SWITCHES You can specify special parameters to be used during compilation by adding a switch to the end of the command string. Switches are always preceded by a slash, and more than one switch may be used in the same command. An example of the format would be: TEST,TEST=TEST/D/X The default switch settings used if you don't specify any switches are: /Z/4/T The available switches and their actions are as follows: SWITCH ACTION /E The /E switch tells the compiler that the program contains the ON ERROR GOTO statement. If a RESUME statement other than RESUME is used with the ON ERROR GOTO statement, use /X instead (see below). To handle ON ERROR GOTO properly, in a compiled environment, BASIC must generate some extra code for the GOSUB and RETURN statements. Therefore, do not use this switch unless your program contains the ON ERROR GOTO statement. The /E switch also causes line numbers to be included in the binary file, so runtime error messages will include the number of the line in error. SWITCH ACTION /X The /X switch tells the BASIC Compiler that the program contains one or more RESUME, RESUME NEXT, or RESUME 0 statements. The /E switch is assumed when the /X switch is specified. To handle RESUME statements properly in a compiled environment, the compiler must relinquish certain optimizations. Therefore, do not use this switch unless your program contains RESUME statements other than RESUME . The /X switch also causes line numbers to be included in the binary file, so runtime error messages will include the number of the line in error. /N The /N switch prevents listing of the generated code in symbolic notation. If this switch is not set, the source listing produced by the compiler will contain the object code generated by each statement. SWITCH ACTION /D The /D switch causes debug/checking code to be generated at runtime. This switch must be set if you want to use TRON/TROFF. The BASIC Compiler generates somewhat larger and slower code in order to perform the following checks: 1. Arithmetic overflow. All arithmetic operations, integer and floating point, are checked for overflow and underflow. 2. Array bounds. All array references are checked to see if the subscripts are within the bounds specified in the DIM state- ment. 3. Line numbers are included in the generated binary so that runtime errors can indicate the statement which contains the error. 4. RETURN is checked for a prior GOSUB. /Z The /Z switch tells the compiler to use Z80 opcodes. SWITCH ACTION /S The /S switch forces the compiler to write long quoted strings (i.e. more than 4 characters) to the binary file as they are encountered. This allows large programs with many quoted strings to compile in less memory. However, there are two disadvantages: 1. Memory space is wasted if identical, long quoted strings appear in the program. 2. Code generated while the -S switch is set cannot be placed in ROM. SWITCH ACTION /4 The /4 switch allows the compiler to use the lexical conventions of Microsoft 4.51 Disk BASIC interpreter. That is, spaces are insignificant, variables with imbedded reserved words are illegal, variable names are restricted to two significant characters, etc. this feature is useful if you wish to compile a source program that was coded without spaces, and contains lines such as FORI=ATOBSTEPC Without the /4 switch, the compiler would assign the variable "ATOBSTEPC" to the variable FORI. With the /4 switch, it would recognize it as a FOR statement. SWITCH ACTION /C The /C switch tells the compiler to relax line numbering con- straints. Whene /C is specified, line numbers may be in any order, or they may be eliminated entirely. Lines are compiled normally, but of course cannot be targets for GOTO's, GOSUB's, etc. While /C is set, the underline character causes the remainder of the physical line to be ignored, and the next physical line is considered to be a continuation of the current logical line. NOTE: /C and /4 may not be used together. /T Use 4.51 execution conventions /O (Newer versions only). Tells the compiler to construct a stand- alone program instead of one requiring presence of the BRUN.COM runtime module. This generates much bigger programs because all of the runtime routines must be included. :BASIC COMPILER ERROR MESSAGES The following errors may occur while a program is compiling. The BASIC Compiler outputs the two-character code for the err, along with an arrow. The arrow indicates where in the line the error occurred. In those cases where the compiler has read ahead before it discovered an error, the arrow points a few characters beyond the error, or at the end of the line. The error codes are as follows: FATAL ERRORS CODE ERROR SN Syntax Error. Caused by one of the following: Illegal argument name Illegal assignment target Illegal constant format Illegal debug request Illegal DEFxxx character specification Illegal expression syntax Illegal function argument list Illegal function name CODE ERROR SN Syntax Error. Caused by one of the following: Illegal function formal parameter Illegal separator Illegal format for statement number Illegal subroutine syntax Invalid character Missing AS Missing equal sign Missing GOTO or GOSUB Missing comma Missing INPUT Missing line number Missing left parenthesis Missing minus sign Missing operand in expression Missing right parenthesis Missing semicolon Name too long Expected GOTO or GOSUB CODE ERROR SN Syntax Error. Caused by one of the following: String assignment required String expression required String variable required here Illegal syntax Variable required here Wrong number of arguments Formal parameters must be unique Single variable only allowed Missing TO Illegal FOR loop index variable Missin THEN Missing BASE Illegal subroutine name OM Out of memory Array too big Data memory overflow Too many statement numbers Program memory overflow CODE ERROR SQ Sequence Error Duplicate statement number Statement out of sequence TM Type Mismatch Data type conflict Variables must be of same type BS Bad Subscript Illegal dimension value Wrong number of subscripts LL Line Too Long UC Unrecognizable Command Statement unrecognizable Command not implemented OV Math Overflow /0 Division by Zero DD Array Already Dimensioned FN FOR/NEXT Error FOR loop index variable already in use FOR without NEXT NEXT without FOR CODE ERROR FD Function Already Defined UF Function Not Defined WE WHILE/WEND Error WHILE without WEND WEND without WHILE /E Missing "/E" Switch /X Missing "/X" Switch WARNING ERRORS ND Array Not Dimensioned SI Statement Ignored Statement ignored Unimplemented command If the BASIC Compiler informs you of any of these errors, return to the source program for debugging and try again. If no errors were encountered during compilation, and if you so chose, you now have an object file containing machine readable code on your diskette. Also on your diskette is a listing file which contains the BASIC program statements along with the machine language generated by each statement. The next step in the process is loading and executing the program with LINK-80. :LINK-80 LINKING LOADER As demonstrated in SAMPLE SESSION, compiled BASIC object files are loaded into memory and executed using the LINK-80 linking loader. The loader has many uses. You may wish to simply load one compiled program and run it, or you may load several programs, subprograms, or assembly language subroutines at the same time. Programs may be loaded at user-specified locations, and program areas and data areas may be separated in memory. A memory image of the executable file produced by LINK-80 can be saved on disk and run at a later time. RUNNING LINK-80 At CP/M command level, enter: L80 This loads LINK-80, which will respond with: * . The loader exits back to CP/M if a CONTROL-C is typed after the asterisk. (The loader also exits back to CP/M after an /E switch or /G switch is executed. More on these switches later.) LINK-80 COMMAND FORMAT A command to LINK-80 is made up of the filename(s) of the file(s) to be loaded. For example, to load the compiled program MYPROG.REL, enter: MYPROG (It is not necessary to type the default extension .REL.) This loads the program but does not run it. Whenever LINK-80 loads a BASIC Compiler program, it automatically searches the BASIC library for the necessary routines and loads these as well. Therefore, BASLIB.REL must be on the default drive during the loading process. To run MYPROG, enter: /G This is the "go" or execute switch. LINK-80 prints two numbers and a BEGIN EXECUTION message. LINK-80 always returns to TRSDOS after a /G switch has been executed. As you probably have guessed, it is not necessary to perform these operations with separate commands. It is possible to type one command line that runs LINK-80, loads MYPROG.REL and executes it. To do this, enter: L80 MYPROG/G MORE COMMANDS AND SWITCHES LINK-80 provides other capabilities besides loading and executing programs, such as looking at output without saving the program or resetting the loader so that you can correct a mistake. Switches are used to inform LINK-80 that you wish to perform special tasks. Here is an example that loads and saves a program called TEST.REL. >L80 *TEST,TEST/N/E The first part of the command (TEST) loads the program called TEST.REL. The next part (TEST/N) saves a copy of the loaded program on disk in a file called TEST.COM. The last part (/E) causes LINK-80 to exit back to CP/M. THE /N SWITCH Take note of the /N switch. This switch saves a memory image of the executable file on disk. The default extension for the saved file is .COM, and this file is called a "command file". Once saved on disk, you need only type the filename at CP/M command level to run the program. The /N switch must immediately follow the filename of each file you wish to save, and it does not take effect until a /E or /G switch is done. The following example links several object files, saves the main program image and executes the program TAXES.REL. >L80 *SUB1,SUB2,TAXES/N,TAXES/G Two subroutines (SUB1) and (SUB2) and an object file (TAXES) are linked and loaded. The program is executed and the command file TAXES.COM is saved on disk. THE /R SWITCH Another handy switch is /R. It returns LINK-80 to it's initial state by "unloading" whatever you've loaded. Use it to reset the loader if you've made a typing mistake or loaded the wrong program. The /R switch takes effect as soon as LINK-80 sees it, so if you enter it at any time while LINK-80 is running, the loader will reset. For example: >L80 *INVEN1 */R (oops-- meant to load INVEN2) *INVEN2 (now only INVEN2 is loaded) SPECIAL SWITCHES For typical BASIC Compiler operation, only the above switches will be needed. Some users may find that their applications require more specialized capabilities. For this reason, the following switches are also provided with LINK-80. In these examples, all programs have been loaded at the default origins of CP/M. In special cases, the user may wish to specify the origins of the programs and data that are loaded. LINK-80 provides special switches to do this. /E:Name This is an optional form of the /E switch. Name is a global symbol previously defined in one of the modules. LINK-80 uses Name for the start address of the program. /G:Name This is an optional form of the /G switch. Name is a global symbol previously defined in one of the modules. LINK-80 uses Name for the start address of the program. /P and /D /P and /D allow the origin(s) to be set for the next program loaded. /P and /D take effect when seen (not deferred), and they have no effect on programs already loaded. The form is /P:
or /D:
, where
is the desired origin in the current typeout radix. (Default radix is hexadecimal. /O sets radix to octal; /H to hex.) LINK-80 does a default /P: (i.e., 100h). If no /D is given, data areas are loaded before program areas for each module. If a /D is given, All Data and Common areas are loaded starting at the data origin and the program area at the program origin. Example: */P:200,FOO DATA 200 300 */R */P:200-D:400,FOO DATA 400 480 PROGRAM 200 280 /U List the origin and end of the program and data area and all undefined globals as soon as the current command line has been interpreted. The program information is only printed if a /D has been done. Otherwise, the program is stored in the data area. /M List the origin and end of the program and data area, all undefined globals and their values, and all undefined globals followed by an asterisk. The program information is only printed if a /D has been done. Otherwise, the program is stored in the data area. /X If a filename/N was specified, /X will cause the file to be saved in INTEL ascii HEX format with an extension of .HEX. /Y If a filename/N was specified, /Y will create a filename.SYM file when /E is entered. This file contains the names and addresses of all Globals for use with Digital Research's SID and ZSID debuggers. SYSTEM LIBRARY SEARCHES Whenever a BASIC Compiler program is loaded, LINK-80 automatically searches the BASIC Compiler library for the routines it needs and loads them. If you gat an "Undefined" error, it means the compiler couldn't find something it needed to finish compiling the program. Usually this is the name of a subroutine that you forgot to load. If you are using the BASIC Compiler in conjunction with Microsoft's FORTRAN-80, you may also be referencing some of FORTRAN's library routines. For this reason, the /S switch is included in LINK-80 to force a search of particular library modules. For example: *FORLIB/S,TEST/G Unless you are using FORLIB (supplied with FORTRAN-80), you should not need the /S switch. :LINK-80 ERROR MESSAGES LINK-80 has the following error messages: ?No Start Address A /G switch was issued, but no main program had been loaded. ?Loading Error The last file given for input was not a properly formatted LINK-80 object file. ?Out of Memory Not enough memory to load program. ?Command Error Unrecognizable LINK-80 command. ? Not Found , as given in the command string, did not exist. %2nd COMMON larger The first definition of COMMON block /XXXXXX/ was not the largest definition. Reorder module loading sequence or change COMMON block definitions. %Mult. Def. Global YYYYYY More than one definition for the global (internal) symbol YYYYYY was encountered during the loading process. %Overlaying Program Area ,Start = xxxx Data ,Public = (xxxx) ,External = (xxxx) A /D or /P will cause already loaded data to be destroyed. ?Intersecting Program Area Data The program and data area intersect and an address or external chain entry is in this intersection. The final value cannot be converted to a current value since it is in the area intersection. ?Start Symbol - - Undefined After a /E: or /G: is given, the symbol specified was not defined. Origin Above (Below) Loader Memory, Move Anyway (Y or N)? After a /E or /G was given, either the data or program area has an origin or top which lies outside loader memory (i.e., loader origin to top of memory). If a Y CR is given, LINK-80 will move the area and continue. If anything else is given, LINK-80 will exit. In either case, if a /N was given, the image will already have been saved. ?Can't save Object File A disk error occurred when the file was being saved. :STORING YOUR PROGRAM ON DISKETTE Once it has been loaded by LINK-80, the object file is in a form that can be executed by any CP/M computer. You can save this compiled program on your own diskette so that it can be executed at a later time without using the BASIC Compiler at all. The /N switch (discussed in the LINK-80 section) is the switch that causes your object file to be saved. The default extension for the saved file is .COM and this file is called a "command file". :RUNNING YOUR COMPILED PROGRAM Your compiled program (previously saved on your own diskette) can now be executed any time you wish. When you are at CP/M command level the diskette on which you saved your program is inserted into a drive, simply enter: At this point, your program should execute and your output should appear on the screen. However, you may get a runtime error message. If you do, look it up in the following list, and debug your program as best you can before trying to store it on diskette again. :RUNTIME ERROR MESSAGES The following errors may occur while a compiled program is executing. The error numbers match those issued by the BASIC-80 interpreter. The compiler runtime system prints long error messages followed by an address, unless /D, /E, or /X is specified. In those cases the error message is followed by the number of the line in which the error occurred. NUMBER MESSAGE 2 Syntax error A line is encountered that contains an incorrect sequence of characters in a DATA statement. 3 RETURN without GOSUB A RETURN statement is encountered for which there is no previous, unmatched GOSUB ststement. 4 Out of Data A READ statement is executed when there are no DATA statements with unread data remaining in the program. NUMBER MESSAGE 5 Illegal function call A parameter that is out of range is passed to a math or string function. An FC error may also occur as the result of: 1. a negative or unreasonably large subscript 2. a negative or zero argument with LOG 3. a negative argument to SQR 4. a negative mantissa with a non-integer exponent 5. a call to a USR function for which the starting address has not yet been given 6. an improper argument to ASC, CHR$, MID$, LEFT$, RIGHT$, INP, OUT, WAIT, PEEK, POKE, TAB, SPC, STRING$, SPACE$, INSTR, or ON...GOTO 7. a string concatenation that is longer than 255 characters NUMBER MESSAGE 6 Floating overflow or integer overflow The result of a calculation is too large to be represented in BASIC-80's number format. If underflow occurs, the result is zero and execution continues without an error. 9 Subscript out of range An array element is referenced with a subscript that is outside the dimensions of the array. 11 Division by zero A division by zero is encountered in an expression, or the operation of involution results in zero being raised to a negative power. Machine infinity with the sign of the numerator is supplied as the result of the division, or positive machine infinity is supplied as the result of the involution, and execution continues. 14 Out of string space String variables exceed the allocated amount of string space. NUMBER MESSAGE 20 RESUME without error A RESUME statement is encountered before an error trapping routine is entered. 21 Unprintable error An error message is not available for the error condition which exists. This is usually caused by an ERROR with an undefined error code. 50 Field overflow A FIELD statement is attempting to allocate more bytes than were specified for the record length of a random file. 51 Internal error An internal malfunction has occurred in Disk BASIC-80. Report to Microsoft the conditions under which the message appeared. 52 Bad file number A statement or command references a file with a file number that is not OPEN or is out of the range of file numbers specified at initialization. NUMBER MESSAGE 53 File not found A RUN, CHAIN, KILL, or OPEN statement references a file that does not exist on the current disk. 54 Bad file mode An attempt is made to use PUT, GET, or LOF with a sequential or to execute an OPEN with a file mode other than I, O, R, D. 55 File already open A sequential output mode OPEN is issued for a file that is already open; or a KILL is given for a file that is open. 57 Disk I/O error An I/O error occurred on a disk I/O operation. It is a fatal error, i.e., theoperating system cannot recover from the error. 58 File already exists The filename specified is identical to a filename already in use on the disk. 61 Disk Full All disk storage space is in use. NUMBER MESSAGE 62 Input past end An INPUT statement is executed after all the data in the file has been INPUT, or for a null (empty) file. To avoid this error, use the EOF function to detect the end of file. 63 Bad record number In a PUT or GET statement, the record number is either greater than the maximum allowed (32767) or equal to zero. 64 Bad file name An illegal form is used for the filename with RUN, CHAIN, KILL, or OPEN (e.g., a filename with too many characters). 67 Too many files An attempt is made to create a new file (using OPEN) when the directory is full.