norge.freeshell.org (192.94.73.8)/192.94.73.8.tar/192.94.73.8/pub/computers/cpm/alphatronic/BASCOM.ZIP/BASCOM.HLP

Text File | 2000-08-07 | 15KB | 379 lines

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