RomWBW/Source/Images/d_bascomp/u0/BASCOM.HLP

Introduction
Format notation
A sample session
Writing a Basic program to be compiled
Compiler-interpreter differences
New programming features
Second menu: Compiling, linking & loading, errors
:INTRODUCTION

The  Microsoft  BASIC Compiler is a highly efficient programming tool  that 
converts  BASIC  programs from BASIC source code into  machine  code.  This 
provides  much  faster  BASIC program execution than  has  previously  been 
possible.  It can make programs run an average of 3 to 10 times faster than 
programs  run under BASIC-80.    Compiled  programs can  be  up to 30 times 
faster  than interpreted programs if maximum use  of integer  variables  is 
made.
:FORMAT NOTATION

Wherever  the  format for a statement or command is given  throughout  this 
HELP file, the following rules apply:

    1.   Items in capital letters must be input as shown.

    2.   Items in lower case letters enclosed in angle brackets ( < >  ) 
         are to be supplied by the user.

    3.   Items in sqare brackets ( [ ] ) are optional.

    4.   All  punctuation  except  angle brackets  and  square  brackets 
         (i.e.,  commas,  parentheses,  semicolons,  hyphens,  and equal 
         signs) must be included where shown.

    5.   Items  followed  by  an ellipsis ( ...  ) may be  repeated  any 
         number of times (up to the length of the line).

    6.   Items separated by a vertical bar ( \ ) are mutually exclusive; 
         choose one.
:SAMPLE SESSION 

The  following instructions will take you step by step through the compila-
tion process, from typing in the program to running the compiled version of 
it.  

STEP 1: PRELIMINARIES

Load BASIC-80 (NOT included in the BASCOM package) from disk.  The  program 
will sign on and the letters

ok

will appear on the screen. Now enter:

          AUTO 100, 100

This  command  instructs BASIC-80 to automatically generate  line  numbers, 
beginning with line 100 and incrementing by 100 each time you press ENTER.

STEP 2: ENTER THE PROGRAM

You are now ready to begin typing in your BASIC program.  Anything that you 
know  runs  in BASIC-80 will do.  Alternatively,  just read in  a  BASIC-80 
program you already use.

STEP 3: SAVE THE PROGRAM

In order for the compiler to process it,  you must save your source program 
in ASCII format. To do so, enter: 

          SAVE "MYPROG",A

There  is  now a BASIC program called MYPROG.BAS on your diskette  that  is 
ready  to  be compiled.  (A program that is not yet compiled is called  the 
source file.)

Return to CP/M by typing SYSTEM.

STEP 4: CHECK FOR ERRORS

At  this point,  it is a good idea to check the program for syntax  errors. 
Removing syntax errors now will reduce the possibility of having to  recom-
pile later.  To do this, enter:

          BASCOM =MYPROG

This  command loads the BASIC Compiler and compiles the source file without 
producing an object or listing file.  If you have made any syntax errors, a 
two-letter code will appear on the screen.  If this happens, return to STEP 
1, use the BASIC-80 interpreter again, and correct the errors.

If no errors were encountered, you are ready to continue.

STEP 5: COMPILE SOURCE FILE

These  commands instruct the BASIC Compiler to compile MYPROG.BAS,  to  put 
the  object in a file named MYPROG.REL,  and to put the listing in  a  file 
named  MYPROG.LST.  (.REL  and .LST are default extensions supplied by  the 
BASIC Compiler.)

There  are  now a relocatable object file called MYPROG.REL and  a  listing 
file called MYPROG.LST on the disk.  The object file contains the  machine-
readable  code  generated by the compiler.  The listing file  contains  the 
BASIC  program statements along with the machine language generated by each 
statement. 

STEP 6: LOAD AND EXECUTE THE PROGRAM

The LINK-80 linking loader is used to produce an executable program. To use 
it, enter:

          L80 MYPROG,MYPROG/N/E

This command runs LINK-80,  which in turn loads the object file  MYPROG.REL 
into  the correct memory locations,  then writes it to disk as a .COM file. 
During this process (which can take some time),  runtime routines are drawn 
from the BASLIB.REL runtime library.

The  compiled program which you stored on your own diskette can be  run  at 
any time,  all by itself,  without using any part of the BASIC Compiler. It 
works just like a standard CP/M command file.  To execute, just enter:

          MYPROG

The program should then work just as it did in the interpreter .. only much 
faster.
:WRITING A BASIC PROGRAM TO BE COMPILED 

BASIC programs which are to be compiled are, for most part, written in just 
the  same  way  you have always written them to run with  the  interpreter. 
However,  there  are some differences between the statements  and  commands 
implemented  in BASIC-80 and those implemented in the BASIC  Compiler  that 
must be taken into consideration.

The  Compiler  interacts with the console only to read  compiler  commands. 
These specify what files are to be compiled.  There is no "direct mode", as 
with the MBASIC interpreter. Commands that are usually issued in the direct 
mode with MBASIC are not implemented on the compiler.  The following state-
ments and commands are not implemented and will generate an error message.

     AUTO      CLEAR*    CLOAD     CSAVE     CONT
     DELETE    EDIT      LIST      LLIST     RENUM
     SAVE      LOAD      MERGE     NEW       COMMON*
     SYSTEM
*
(Note: Newer releases of the compiler which include the BRUN runtime module 
do support CHAINing with COMMON and CLEAR with certain restrictions.)

:FEATURES USED DIFFERENTLY BY THE BASIC COMPILER

DEFINT/SNG/DBL/STR
The compiler does not "execute" DEFxxx statements;  it reacts to the static 
occurrence  of these statements,  regardless of the order in which  program 
lines are executed. A DEFxxx statement takes effect as soon as its  line is 
encountered.  Once the type has been defined for a given letter, it remains 
in  effect until the end of the program or until a different DEfxxx  state
ment with that letter takes effect.

USRn Functions
USRn  functions are significantly different from the interpreter  versions. 
The  argument  to  the USRn function is ignored and an  integer  result  is 
returned  in  the HL registers.  It is recommended that USRn  functions  be 
replaced  by  the CALL statement.  (See New BASIC Programming Features  for 
definition of CALL.)

DIM and ERASE
The DIM statement is similar to the DEFxxx statement in that it is  scanned 
rather than executed.  That is,  DIM takes effect when its  line is encoun-
tered.  If  the default dimension (10) has already been established for  an 
array variable and that variable is later encountered in a DIM statement, a 
DD (redimensioned array) error results.  There is no ERASE statement in the 
compiler,  so arrays cannot be erased and redimensioned. An ERASE statement 
will produce a fatal error.

Also  note  that  the values of the subscripts in a DIM statement  must  be 
integer constants;  they may not be variables,  arithmetic expressions,  of 
floating point values. For example,

     DIM A1(I)
     DIM A1(3+4)

are both illegal statements.

END
During execution of a compiled program,  an END statement closes files  and 
returns control to the operating system. The compiler assumes an END at the 
end  of the program,  so it is not necessary to insert an END statement  in 
order to get proper program termination.

FOR/NEXT
All FOR/NEXT loops must be statically nested with only 1 NEXT statement for 
each FOR statement.

ON ERROR GOTO/RESUME <line number>
If  a  program contains ON ERROR GOTO and RESUME <line number>  statements, 
the  /E compilation switch must be used.  If the RESUME  NEXT,  RESUME,  or 
RESUME  0  form is used,  the /X switch must also be  included.  

REM
REM statements or remarks starting with a single quotation mark do not make 
up time or space during execution, and so may be used as freely as desired.

STOP
The STOP statement is identical to the END statement. Open files are closed 
and control returns to the operating system.

TRON/TROFF
In order to use TRON/TROFF,  the /D compilation switch must be used. Other-
wise,  TRON and TROFF are ignored and a warning message is  generated.  
:NEW BASIC PROGRAMMING FEATURES

The  BASIC  Compiler  also  adds  new features  that  will  add  power  and 
efficiency  to  your programming.  Keep in mind when  utilizing  these  new 
features  that while they will compile with no problems,  you cannot run  a 
program  using  these  features with  your  interpreter,   since   BASIC-80
doesn't recognize them.

CALL Statement
The  CALL  Statement  allows you to call and transfer flow to  an  assembly 
language or FORTRAN subroutine.

The format of the CALL Statement is:

     CALL <variable name> [(<argument list>)]

where <variable name> and <ergument list> are supplied by you.

<variable name> is the name of the subroutine you wish to call.  This  name 
must  be  1  to 6 characters long and must be recognized by  LINK-80  as  a 
global  symbol.  (<variable  name> must be the name of the subroutine in  a 
FORTRAN  SUBROUTINE  statement or a PUBLIC symbol in an  assembly  language 
routine.)

<argument  list> is optional and contains the arguments that are passed  to 
the assembly language or FORTRAN subroutine.

Example:       120 CALL MYROUT (I,J,K)

CHAIN (or RUN)
The CHAIN and RUN statements both perform the same function: they allow you 
to load a file from diskette into memory and run it.  CHAIN (or RUN) closes 
all  open files and deletes the current contents of memory  before  loading 
the  designated program.  The format of the CHAIN (or RUN) statement is  as 
follows:

                      CHAIN <filename>
                             OR
                      RUN <filename>

where  <filename> is the name used when the file was saved.  (With CP/M the 
default extension .BAS is supplied.)

WHILE...WEND
The  WHILE...WEND  statement  is a conditional statement  that  executes  a 
series of statements in a loop as long as a given condition is true.

The format of WHILE...WEND is:

     WHILE <expression>
          -
          -
     <loop statements>
          -
          -
     WEND

where <expression> and <loop statements> are supplied by you.

As  long  as <expression> is true (i.e.,  not zero),  loop  statements  are 
executed until the WEND statement is encountered. BASIC then returns to the 
WHILE statement and checks "expression".  If it is still true,  the process 
is  repeated.  If  it is not true,  execution resumes  with  the  statement 
following the WEND statement.

WHILE/WEND loops may be nested to any level, as long as they are statically 
nested.  Each  WEND  will match the most recent WHILE.  An unmatched  WHILE 
statement causes a "WHILE without WEND" error, and an unmatched WEND state-
ment causes a "WEND without WHILE" error.

Example:
          090  'BUBBLE SORT ARRAY A$
          100  FLIPS=1 'FORCE ONE PASS THRU LOOP
          110  WHILE FLIPS
          115       FLIPS=0
          120       FOR I=1 TO J=1
          130            IF A$(I)>A$(I+1) THEN
                         SWAP A$(I),A$(I+1):FLIPS=1
          140       NEXT I
          150  WEND

Double Precision Transendental Functions
SIN,  COS,  TAN,  SQR,  LOG, and EXP now return double precision results if 
given  double  precision arguments.  Exponentiation with  double  precision 
operands will return double precision results.

Long Variable Names
Variable  names  may  be up to 40 characters long with  all  40  characters 
significant.  Letters,  numbers,  and the decimal characters are allowed in 
variable names,  but the name must begin with a letter.  Variable names may 
also  include  all  BASIC-80  commands,  statements,  function  names,  and 
operator names.

Expression Evaluation in the  BASIC Compiler
During program compilation,  when the BASIC Compiler evaluates expressions, 
the operands of each operator are converted to the same type,  that of  the 
most precise operand. For example,

          QR=J%+A!+Q

causes J% to be converted to single precision and added to A!.  This result 
is coverted to single precision and added to Q.

The  Compiler  is  more limited than the interpreter  in  handling  numeric 
overflow. For example, when run on the interpreter the following program

          I%=20000
          J%=20000
          K%=-30000
          M%=I%+J%-K%

yields 10000 for M%.  That is,  it adds I% to J% and, because the number is 
too large,  it converts the result into a floating point number. K% is then 
converted  to floating point nd subtracted.  The result of 10000 is  found, 
and is converted back to integer and saved as M%.

The Compiler,  however, must make type conversion decisions during compila-
tion. It cannot defer until the actual values are known. Thus, the compiler 
would generate code to perform the entire operation in integer mode. If the 
/D switch were set,  the error would be detected.  otherwise,  an incorrect 
answer would be produced.

In  order  to  produce  optimum efficiency in  the  compiled  program,  the 
compiler  may perform any number of valid algebraic transformations  before 
generating the code. For axample, the program

          I%=20000
          J%=-18000
          K%=20000
          M%=I%+J%+K%

could produce an incorrect result when run.  If the compiler actually  per-
forms the arithmetic in the order shown,  no overflow occurs.  However,  if 
the compiler performs I%+K% first and then adds J%, an overflow will occur.

The  Compiler  follows  the rules of operator  precedence  and  parenthetic 
modification of such precedence, but no other guarantee of evaluation order 
can be made.

Using Integer Variables To Optimize Speed
In order to produce the fastest and most compact object code possible, make 
use of integer variables. For example, this program

          FOR I=1 TO 10
          A(I)=0
          NEXT I

can  execute approximately 30 times faster by simply substituting "I%"  for 
"I".  It  is  especially advantageous to use integer variables  to  compute 
array  subscripts.  The  generated  code is significantly faster  and  more 
compact.

Maximum Line Length
The Compiler cannot accept a physical line that is more than 253 characters 
in length. A logical statement, however, may contain as many physical lines 
as  desired.  Use line feed to start a new physical line within  a  logical 
statement.
::BASCOM2.HQP











 a random file.
51        Internal error
	  An  internal	malfunc