Flash!

An Integer Basic Compiler by Mike Laumer




For the Apple II or Apple II Plus 48K with DOS 3.3

---------------------------------------------------------------------

COPYRIGHTS.


This manual is copyrighted.  All rights are reserved.  This document
may not, in whole or part, be copied, photocopied, reproduced,
translated or reduced to any electronic medium or machine readable
form without prior consent, in writing from Laumer Research.

(C) COPYRIGHT 1982 by Laumer Research, 1832 School Road
    Carrollton, Texas 75006,    (214) 245-3927


ACKNOWLEDGEMENTS.


Thanks to my wife Margaret who let me spend thousands of hours of my
spare time on the FLASH! compiler project.  Also thanks to her for
sharing the good times and her support during the tough times.

Thanks to Bobby Deem for his first use of the compiler prior to Beta Test.

Thanks to Bob Sander-Cederlof for his ideas on programming techniques.

Thanks to Steve Wozniak of Apple Computer for creating a nice little
language which compiles to fast machine code.


TRADEMARKS.

The word FLASH! and the FLASH! logo are trademarks of
Laumer Research.

The word APPLE, and APPLESOFT BASIC are trademarks of
APPLE COMPUTER INC.

S-C Assembler II 4.0 and S-C Macro Assembler II are trademarks of S-C
Software Corporation.


DISCLAIMER.

LAUMER RESEARCH AND THE AUTHOR OF THIS PROGRAM SHALL HAVE THE
LIABILITY OR RESPONSIBILITY TO THE PURCHASER OR ANY OTHER PERSON OR
ENTITY WITH RESPECT TO ANY LIABILITY, LOSS OR DAMAGE CAUSED OR
ALLEGED TO BE CAUSED DIRECTLY OR INDIRE BY THIS SOFTWARE, INCLUDING,
BUT NOT LIMITED TO ANY INTERRUPTION OF SERVICE, LOSS OF BUSINESS OR
ANTICIPATORY PROFITS OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE
OR OPERATION OF THIS SOFTWARE.

---------------------------------------------------------------------

FLASH!
An INTEGER BASIC COMPILER for the APPLE II

Author - MICHAEL R. LAUMER 


FLASH!  REFERENCE MANUAL


COPYRIGHT (c) 1982 by LAUMER RESEARCH
All Rights Reserved

---------------------------------------------------------------------

COMMERCIAL LICENSING REQUIREMENTS.
                                  


The FLASH! compiler is intended as a consumer product only, and
purchase of FLASH! does not provide the right to make use of the
product in commercial applications.

Because all FLASH! compiled programs require the presence of the
FLASH! operating system (described as the runtime package in this
manual), commercial use of the compiled programs would be an
unauthorized duplication of the product of Laumer Research,
and~tberefore violate the copyright laws unless prior written
permission is obtas 1 ned from Laumer Research.

If you wish to use. FLASH! compiled programs in commercially marketed
products, please contact Laumer Research directly for information on
licensing.  In support of computer clubs, the distribution of
computer club software compiled with FLASH! is exempted
from the licensing requirements.



COMPILER UPGRADE INFORMATION.
                             

The FLASH! compiler is a product with ongoing product support.  As
such it may be improved at the discretion of Laumer Research bynew
releases.  If you should damage the compiler diskette or if you find
the revision of the compiler currently being sold is different from
the release of the compiler you have purchased you may write Laumer
Research requesting an upgrade.  You must have proof of purchase or
have registered the compiler with Laumer Research.  To receive the
upgrade send a check for $15.00 and the serial number of the compiler
disk which you purchased.  If you want the runtime source disk
upgraded an additional $15.00 and the serial number of the runtime
source disk must be sent.  The runtime source disk must have been
registered with Laumer Research or proof of purchase must be given to
receive an upgrade for it.

---------------------------------------------------------------------

TABLE OF CONTENTS.

INTRODUCTION                             1
HOW FLASH! COMPILES PROGRAMS             2
HOW TO COMPILE A                         4
DISK COMPILATION                         5
COMPATABILITY WITH INTEGER BASIC         6
HOW TO ANSWER THE PROMPT QUESTIONS       8
      SOURCE FILE                        9
      OBJECT FILE :                      9
    ASSEMBLY FILE :                      9
      CAN RAM CARD BE USED ?            10
    RUNTIME IN OBJECT FILE ?            10
       LANGUAGE EXTENSIONS ?            11
         SYMBOL TABLE LIST ?            11
    LINE NUMBER TABLE LIST ?            12
    ASSEMBLY LANGUAGE LIST ?            12
       PRINTER SLOT NUMBER :            12
            PROGRAM ORIGIN :            13
    START ADRS FREE MEMORY :            13
      END ADRS FREE MEMORY :            13
    READY TO BEGIN COMPILE ?            13
LANGUAGE EXTENSIONS                     14
LIST OF NEW STATEMENTS                  15
DEBUGGING COMPILED PROGRAMS             20
HANDY HINTS                             21
    restarting a program                21
    how to determine who's running      21
    hires page flipping                 21
    finding the origin dynamically      21
    how to pass parameters              22
A BUG IN INTEGER BASIC                  24
A BUG IN THE PROGRAMMER'S AID ROM       25
HOW TO ASSEMBLE THE ASSEMBLY FILE       26
RUNTIME PACKAGE NOTES                   29
DESCRIPTION OF RUNTIME ENTRY POINTS     30
GLOSSARY                                40
APPENDIX A (patch for .DA)              44
APPENDIX B (ASCII code tables)          46
APPENDIX C (FLASH! error messages)      49
    HARD ERRORS                         49
    SOFT ERRORS                         50
    CORRECTABLE ERRORS                  51
    INTERNAL ERRORS                     52
    DISK ERRORS                         53
APPENDIX D (Runtime error messages)     54
APPENDIX E (programs on the diskette)   57

---------------------------------------------------------------------

INTRODUCTION.


The FLASH! package contains the following items:

1.  A FLASH! diskette.
2.  The FLASH! reference manual.
3.  The FLASH! registration card.

BEFORE YOU DO ANYTHING ELSE YOU SHOULD FILL OUT THE REGISTRATION
CARD(S) AND MAIL IT IN AS SOON AS POSSIBLE.  IF YOU DO NOT REGISTER
THE COMPILER YOU WILL NOT BE ABLE TO ORDER CORRECTIONS OR UPGRADES TO
THE COMPILER OR THE SOURCE CODE OF THE RUNTIME PACKAGE SHOULD YOU
WANT TO WORK WITH THE ASSEMBLY OUTPUT FILES.

THE SECOND THING YOU MUST DO IS TO MAKE BACKUP COPIES OF THE COMPILER
WITH THE COPY PROGRAM PROVIDED ON YOUR APPLE II SYSTEM MASTER
DISKETTE.

FLASH! from Laumer Research implements all standard Integer BASIC
statements.  It also adds a good many more statements and functions
to Integer BASIC including Hires graphics and data statement
capability.

Compiled programs can expect an execution speed increase of 5 to 20
times depending on the instruction mix.  Indeed FLASH! compiled
programs execute 3 to 6 times faster than compiled APPLESOFT programs
do for applications which do not require floating point computations.
In addition the compiled programs can expect full runtime checks on
string and array bounds and checks on arithmetic overflows and
underflows.  These do add some time to the execution of a program but
they are absolutely necessary to the vast number of APPLE II users
who do not know how to debug assembly language code which they may
write, let alone strange code generated automatically by a compiler.
The TRACE and DSP statements normal to Integer BASIC are fully
processed and executed by FLASH!.

FLASH! requires a 48k APPLE II with a disk drive using DOS 3.3 and
optionally a RAM card.  FLASH! and its runtime package do not
directly require Integer BASIC on your machine.  However, in order to
edit Integer BASIC programs or to use the full capabilities of
FLASH!, you should have Integer BASIC in ROM or a Language System
Card or the equivalent.  The programs compiled by FLASH! can be run
on a 16k - 48k machine with or without a disk drive.

Programs compiled by FLASH! require the use of a runtime package
provided on disk.  The file "B.RTP" is necessary to run object
programs which do not have the runtime code put in the object file (a
user option on FLASH! prompts).  The compiled programs do not require
Integer BASIC to be able to execute.


- 1 -

---------------------------------------------------------------------

HOW FLASH! COMPILES PROGRAMS.


When FLASH! is compiling a program it can be interrupted by typing
control-C just as in BASIC.  FLASH! will abort the compilation and
close all disk files which are opened. Never use the reset key or you
could have your disk data clobbered.  This holds true for any program
you run which uses the disk.  FLASH! must be run on a disk which is
not write protected as the temporary file is written on the disk from
which FLASH! was run.

FLASH! has three phases of compilation.  The first phase or pass is
called the PARSER phase and it questions the operator for control
information, scans the BASIC program generating intermediate code and
builds tables for symbol names, line numbers, data line numbers, and
forward references for branches on IF and DATA statements.  The
second and third phase are on a disk overlay which is read into
memory when the PARSER phase is completed and no errors have been
detected in the PARSER phase.  The second phase is called the
ALLOCATE phase and it scans the intermediate code file in the RAM
card or disk file and defines the value of the forward references,
locations of lines and variables by generating but not storing
machine language code.  The third phase or CODE GEN phase is the same
as the ALLOCATE phase except that the object code is stored and the
assembly language listing and/or file is made.

The tables generated during the PARSER phase are dynamic and grow
downward from high memory adjusting their size from zero allocation
in blocks of 10 to 50 bytes depending on the particular table.
Exceeding table space should never be a problem with this technique
unless some truly heroic sized programs are compiled.  After the
PARSER phase the Integer BASIC source program in memory on a memory
compilation is discarded and the tables shifted upward to allow more
room for object code should the code be written directly to memory.

FLASH! itself was written in a combination of machine language and a
FORTH like extendible languge with the familiar computation and
return stacks but without a dictionary or FORTH compiler.  This
combination has made quicker development time for the implementation
of FLASH! and above all the debugging effort has been much easier
than with a straight assembly language system.  The first phase of
FLASH! uses standard threaded code FORTH.  The second and third phase
uses JSR FORTH code for extra speed.  The second and third phase
module contains the runtime package as well as complete code
generation routines and assembly language listing routines.




- 2 -

---------------------------------------------------------------------

In comparing FLASH! with other compiler products on the market you
will note the size of the runtime package is larger than on other
compiler systems.  This is because the APPLESOFT compilers are able
to utilize subroutines in the APPLESOFT ROM'S.  The ROM routines of
APPLESOFT are much easier to use from assembly language than those in
Integer BASIC.  Integer BASIC was written in a highly unstructured
manner.  The Integer BASIC ROM routines lack proper error returns in
the code, in most cases they simply jump to error handlers which jump
directly to the main interpretive loop.  In the FLASH! runtime package
the statement processing code is all new code optimized to support
compiled programs in a more efficient manner than the Integer BASIC
ROM routines.  Much of the dead wood is dropped from the code by doing
this, adding extra speed to the execution of FLASH! compiled programs.

During a FLASH! compilation a status line is kept on the bottom line
of the APPLE II screen.  If you use an 80 column card this will not
show as the information is written directly to the screen memory
buffer without using normal APPLE II monitor routines.  This also
means that it should not interfere with the 80 column card operation.
The status line shows from left to right:

1.  The number of bytes remaining to be scanned in the current phase.
    During the PARSER phase it is the size of the BASIC source program.
    During the ALLOCATE and CODE GEN phase it is the size of the
    intermediate code created by the PARSER phase.

2.  The name of the current phase of compilation.

3.  The number of symbols added to the symbol table by the PARSER
    phase.

4.  The number of lines processed by the PARSER phase.

5.  The current line number being processed.










- 3 -

---------------------------------------------------------------------

HOW TO COMPILE.


You are eager to learn to use FLASH! so lets walk you through a
simple compilation example.  First type into Integer BASIC the
following short program.

    10 FOR 1=1 TO 100
    20 PRINT I
    30 NEXT I
    40 END

Now put the FLASH! diskette into your disk drive and type the DOS
command "BRUN FLASH".  The disk will operate for a few seconds, then
questions will be presented for you to answer.  For now you can type
the return key on all questions and data fields and when the question
"READY TO BEGIN COMPILE ?" appears answer with a "Y".  FLASH! will
then begin compiling the short program in memory.  You may observe
the activity by watching the bottom line of your display.  Since you
have defaulted through the questions FLASH! is assuming a memory to
memory compilation using a disk file only for temporary storage.  If
you wish to stop the compilation for any reason simply type control-C
as you would to stop an Integer BASIC program.

Example of answering prompts:

    >BRUN FLASH
      SOURCE FILE
      OBJECT FILE
      CAN RAM CARD BE USED ? 
       LANGUAGE EXTENSIONS ?
         SYMBOL TABLE LIST ?
    LINE NUMBER TABLE LIST ?
    ASSEMBLY LANGUAGE LIST ?
    READY TO BEGIN COMPILE ? Y

When FLASH! has completed the compilation of your program the screen
will clear and the program will automatically execute providing that
you did not answer the object file question.  This memory to memory
compilation mode is useful on a surprising number of small programs
which have no demanding string or array requirements.  Programs that
compile into memory are stored after the second and third phase of
FLASH! and begin in the upper part of the hires page 2 buffer.  The
runtime package occupies memory before hires page 1.  Therefore.
programs which use hires graphics commands and are compiled directly
to memory should use only the hires page 1 buffer.  If you store the
compiled program in an object file and set your own origin, you can
use either hires screen buffer.





- 4 -

---------------------------------------------------------------------

DISK COMPILATION.


Before you compile the AUTO BREAKOUT program try running it under the
Integer BASIC interpreter to get a feel for how it operates and how
fast it executes.  When you have done that proceed with the disk
compilation instruction below.

To compile to or from disk use the AUTO BREAKOUT program provided on
the FLASH! diskette.  Type BRUN FLASH to start the compiler.  When
the "SOURCE FILE" prompt is given type in "AUTO BREAKOUT" and for the
"OBJECT FILE" type "B.AUTO BREAKOUT".  Type return on all the other
prompts.

example of answering the prompts

    >BRUN FLASH
      SOURCE FILE   AUTO BREAKOUT
      OBJECT FILE : B.AUTO BREAKOUT
    ASSEMBLY FILE :
      CAN RAM CARD BE USED ? 
    RUNTIME IN OBJECT FILE ?
       LANGUAGE EXTENSIONS ?
         SYMBOL TABLE LIST ?
    LINE NUMBER TABLE LIST ?
    ASSEMBLY LANGUAGE LIST ?
            PROGRAM ORIGIN :
    START ADRS FREE MEMORY :
      END ADRS FREE MEMORY :
    READY TO BEGIN COMPILE ? Y

FLASH! will read the source file, build intermediate code, allocate
memory for the program then generate machine language code and store
it in the object file.  When FLASH! is done you will see the prompt
for Integer BASIC or APPLESOFT on you screen and disk activity will
stop.

There will now be a new file on the disk "B.AUTO BREAKOUT" or what
ever name you gave it.  To run the program just use the DOS BRUN
command.  Try it now!  See how much faster compiled programs run?
And this is one of the slower demonstration programs!















- 5 -

---------------------------------------------------------------------

COMPATABILITY WITH INTEGER BASIC.


The FLASH! compiler was designed to maintain a high degree of
compatability with the Integer BASIC interpreter.  However due to the
different types of information available during the execution of a
compiled program and the execution of an interpreted program there
will be the following minor differences.

1.  The interpreter will allow an array or string of one element to
be used without a DIM statement.  FLASH! requires every string and
array to be specified in a DIM statement.  FLASH! will provide an
error message after the PARSER phase of compilation for each string
or array that has not been DIM'ed.

2.  A simple variable and an array with the same name will share the
sane memory location in the symbol table kept by the interpreter [A
and A(0) are the same].  FLASH! however will keep the variable in one
memory location and the first array element in a different location.
This is because simple variables are allocated at compile time but
arrays are allocated during run time.  Allocating arrays during
runtime prevents the user from changing all DIM statements to use
only constants as other compilers require.

3.  The interpreter will set the first element of an array to zero
when it is DIM'ed.  FLASH! will not.  Simple variables however will
be set to zero before a program executes.

4.  Programs compiled by FLASH! must have no imbedded machine
language in them and they must not use PEEK's or POKE's which depend
on the Integer BASIC page zero, such as locating the currently
executing line or modifing the symbol table as some of the
simulations of CHR$ do.  A FLASH! compiled program will not have a
symbol table when it is executing.

5.  Programs must not have any illegal statements in them.  Some
Integer BASIC programs have been modified in hex to run statements
allowable only in command mode. These statements such as DEL, HIMEM:,
LOMEM:, LOAD and SAVE can not be entered by normal program entry from
the keyboard and are treated as a "SYNTAX ERROR" during the PARSER
phase of a compilation.







- 6 -

---------------------------------------------------------------------

6.  The LIST command is ignored by the FLASH! compiler. This command
is allowed as a statement by Integer BASIC but has no meaning once
FLASH! compiles a program into object code.

7.  The FLASH! runtime package will save and restore the X register
when machine language routines are CALL'ed by the compiled program.
Integer BASIC requires the user subroutine to save the X register.

8.  The upper limit for string dimensions is not 255, but is limited
by the amount of free memory available. In addition a string can
contain any value from 0 - 255 ( $00 - $FF ).































- 7 -

---------------------------------------------------------------------

HOW TO ANSWER THE PROMPT QUESTIONS.
                                   


The prompt questions asked by FLASH! are listed below.  Not all of
them are asked however as several depend on the results of your
answers to the first questions and others like the RAM card question
are only asked if you have a RAM card in slot 0.


     SOURCE FILE :
     OBJECT FILE :
   ASSEMBLY FILE :
     CAN RAM CARD BE USED ?
   RUNTIME IN OBJECT FILE ?
      LANGUAGE EXTENSIONS ?
        SYMBOL TABLE LIST ?
   LINE NUMBER TABLE LIST ?
   ASSEMBLY LANGUAGE LIST ?
             PRINTER SLOT :
           PROGRAM ORIGIN :
   START ADRS FREE MEMORY :
     END ADRS FREE MEMORY :
   READY TO BEGIN COMPILE ?


The questions noted by a "?" symbol after them are to be answered
with a "Y" or "YES" for yes and with "N", "NO" or nothing to answer
no.  The only exception to this is the begin compilation question
which will not take a null answer to mean "NO".

The prompts noted by a ":" symbol after them are needing either a
file name or a number (decimal or hex).

All file names are entered in standard DOS format like this:

    ABC FILE,D1,S6,V20
    MY FILE,D2
    YOUR FILE


Numbers or addresses can be decimal or hex:
    i.e.    $4000   leading "$" for hex
            8192    no "$" for decimal

The information which follows explains each of the prompt lines in
much greater detail.








- 8 -

---------------------------------------------------------------------

SOURCEFILE  (BASIC File name)

This is the input file to FLASH!.  If no file name is given then the
source file is assumed to be in memory obtained with a LOAD command
before running FLASH!.  If no file is in memory an error is given and
you may type in a name.


OBJECT FILE :   (Binary file for machine code)

If no file name is given then the object code will be stored in
memory during the CODE GEN phase of the compilation.  If the code
becomes too big for memory an error will result informing you to use
an object file for the output.  The memory output mode allows small
BASIC programs to compile faster since the disk is not accessed for
the object output. When no file name is entered the program stored in
memory will execute automatically following the compilation provided
that no compilation errors occur.


ASSEMBLY FILE   (S-C Macro Assembler II file)

This prompt is asked only if you specified to write the object code
to a disk file.  If no assembly file name is given then there will be
no assembly language source file made.  A listing may still be made
however.

The file name given will have a ".A" appended to it and if the file
exceeds 8192 bytes in length the current file is closed and a new one
opened with the ".A" changed to a ".B" and then to a ".C" etc.
Assembly language source code is quite lengthy compared to the
generated object code.  With full comments included it is as much as
10-20 times the size of an object code file!

The assembly file is compatible with the S-C MACRO ASSEMBLER II,
which is an I file type storing each line of text with a byte count
at the beginning, followed by a 2 byte binary line number, the bytes
of text with sign bit off and a $00 byte at the end.  The text can
contain special tokens ($81-$BF) which provide blank compresion (1-31
blanks).

The assembly File can be assembled with the S-C Assembler II 4.0
providing that there are no DSP or NODSP statements which cause the
generation of the new assembler directive ".AT" to create an ASCII
string with the last byte's sign bit set.  The 4.0 assembler version
however. must have the patch to allow a list of data items on a
".DA" directive (see appendix A).



- 9 -

---------------------------------------------------------------------

CAN RAM CARD BE USED ?  (answer yes or no)

If you have a RAM card FLASH! will detect it providing that it is in
slot 0 (the normal slot for RAM cards).  Answer 'Y' or 'YES' if
FLASH! can use it for temporary storage.  If you are running Integer
BASIC in the RAM card and don't want it overwritten answer 'N' or
'NO' to the question.  If the RAM card becomes full or if you told
FLASH! to NOT use the card then FLASH! will use a special file
(FLASH! TEMP FILE) to store the intermediate code.  FLASH! should
normally delete this file when it is through with the compilation.
Compilation time is much quicker if you have a RAM card and tell
FLASH! to use it.  This is because the temporary file is written once
and read twice.  If the temporary file goes to the disk, it will be
very slow compared to memory I/O on the RAM card.

If your source program being compiled is not too large (less than
3000 bytes), then the language card can be used without the loss of
the language in the card because the 4k bank of memory in the card
that is unused by DOS is the first memory to be used by FLASH!


RUNTIME IN OBJECT FILE ?    (answer yes or no)

This prompt only appears if the object code was specified to go to a
disk file.  The runtime package can't be put into an object file if a
file was not given.  If 'NO' is input then the object code will use
the standard runtime package 'B.RTP'.  A small loader is placed at
the front of the object code to BLOAD the standard runtime package
("B.RTP").  FLASH! expects it to load and run at $800 thru $lBFF.
Answering 'NO' will save disk space since the runtime package is
several thousand bytes in length.  Using the runtime in the object
file does allow FLASH! to create a program which runs on an APPLE II
cassette based system or runs as a self contained system.














- 10 -

---------------------------------------------------------------------

LANGUAGE EXTENSIONS ?   (answer yes or no)

FLASH! has processing for all normal Integer BASIC statements.
Several new statements and functions have been added to the language
by the use of an extended REM statement.  These statements will be
ignored by FLASH! unless you ask for them to be compiled by answering
yes to this question.  Any REM statement with a period '.' after the
REM command is considered to be an extended statement. Blanks are
ignored unless enclosed in double quotes (") or single quotes (').
i.e.
    10 REM .HOME
    20 REM .    N O R M A L
    30 REM . DATA  123, $AE3F, "STRING l", 'STRING 2'
    40 REM .HGR HCOLOR=3   HPLOT 0,0 TO A+K, B

In addition the following arrays and strings become function calls
when the extensions are turned on:

    HEX$( e )   CHR$( e )   WEEK( e )


SYMBOL TABLE LIST ? (answer yes or no)

This command will cause FLASH!.to print out a symbol table showing
the memory addresses of the program variables as allocated by FLASH!.
The order of the symbols is the order of their occurrence in the
source program.  The symbol table will print at the end of the CODE
GEN phase and shows usage flags indicating the following information.

U - symbol never was assigned a value on an INPUT, READ, or
    assignment statement.  This will probably cause an error when the
    program is executed.

A - symbol is an array variable.

I - symbol is an integer variable.

S - symbol is a string variable.

* - symbol was assigned a value in an INPUT, READ or assignment
    statements but the value was never referred to in an expression.






- 11 -

---------------------------------------------------------------------

LINE NUMBER TABLE LIST? (answer yes or no)

This command will cause FLASH! to print out a symbol table showing
the memory addresses of each BASIC line that was compiled.  The order
of the line number table is from left to right in order of occurrence
in the source program.  The line number listing will print at the end
of the CODE GEN phase of compilation.


ASSEMBLY LANGUAGE LIST ?    (answer yes or no)

This command will cause FLASH! to print out assembly language source
code showing the actual code generated for each BASIC program line.
Line numbers are indicated in the listing by 'L.xxxxx' for an
assembly language label forward references are given labels of the
form 'F.xxxxx' and data statements have labels of the form 'D.xxxxx'.
The runtime package labels are in the form 'R.xxxxxxx'.  The program
variables use their own names except strings and arrays have '.S' or
'.A' appended to them to identify them separate from integer
variables.  The output assembly format is compatible with the S-C
MACRO ASSEMBLER II, and the assembly directives correspond to the S-C
MACRO ASSEMBLER II syntax.  With the exception of the DSP variable
table all statements can be assembled with the 4.0 version of the S-C
ASSEMBLER II with the patches for the ".DA" statement (see appendix
A) added to it.  The listing will print during the CODE GEN phase of
compilation and will include the hex addresses and object code as
well as complete symbolic labels and mnemonics.


PRINTER SLOT ?  (hex or decimal slot number)

This prompt appears if any listings were requested. If the number is
0 or not entered then the default is to use the screen for the
output.  FLASH! sends a PR#n command to DOS to turn on or off the
printer as necessary.  FLASH! produces paginated listings assuming 66
lines on a normal sized 11 inch sheet.  All listings print during the
CODE GEN phase of compilation.










- 12 -

---------------------------------------------------------------------

PROGRAM ORIGIN ?    (hex or decimal address)

This prompt is given only if an object file name was entered.  If no
address is entered then the address defaults to $800 or $1C00
depending on whether or not the runtime package is to be written to
the object file.  Use of this feature allows the user to skip over
memory areas such as the hires screen buffers.


START ADRS FREE MEMORY ?    (hex or decimal address)

This prompt is given only if an object file name was entered.  If no
address is entered the default will be the end of the program after
the static variable allocation. Free memory is the memory space to be
used for allocation of space for arrays and strings when a DIM
statement is executed.  Unlike most compilers FLASH! does not require
you to change all your DIM statements to use only constants and
appear at the beginning of the source code.  Actually executing DIM
statements allows a bit more source language compatability.


END ADRS FREE MEMORY ?  (hex or decimal address)

This prompt is given only if an object file name was entered.  If no
address is entered the default will be the current value of the himem
pointers.  Normally $9600 on a 48k machine.  If MAXFILE's is used in
the program, then you should set it to the maximum size specified by
the program before compiling the program in order to have the proper
default value.

Care must be used when specifying the free memory addresses. If you
specify the start of free memory to an address before the program
origin then you must not accept the default on the end address prompt
or the whole program will be included in the free memory area!


READY TO BEGIN COMPILE ?    (must answer with Y or N)

This prompt is provided to allow for the correction of any entry
error which may have been made to any of the previous prompts.
Answering "Y" to this question will begin the compilation and
answering "N" will loop the user back through all the prompts.  The
user then answers all questions again just as if FLASH! was restarted
from scratch.



- 13 -

---------------------------------------------------------------------

LANGUAGE EXTENSIONS.
                   


FLASH! supports a number of new statements that Integer BASIC does
not handle.  These statements are added by means of an "active" REM
statement and by answering "YES" to the "LANGUAGE EXTENSIONS ?"
question when a compilation is started.  Of course a program with the
extensions used in it can not be run properly using the Integer BASIC
interpreter and must be recompiled with FLASH! again to fix bugs in
your program.

Some of the extensions are provided automatically such as string
length and content, automatic hex on numeric INPUT statements.  These
do not need to be turned on when the program is compiled as they are
a permanent part of the runtime package.  The list of language
extensions follows:


1.  Strings can be longer than 255 characters up to the limit of free
    memory available.  Strings may contain all 256 possible characters in
    them.  (i.e. shape tables, or assembly language routines to poke).
    The ASC and CHR$ functions can be used to manipulated hexadecimal
    data in strings.


2.  On INPUT statements which input numbers, a hex value can be input
    by typing '$' before the number.  Expressions on extended REM
    statements can have hex numbers specified in the same manner.


3.  There are 3 new functions available.  These can be used in normal
    BASIC lines as well as extended REM statements. You must answer "Y"
    to the "LANGUAGE EXTENSIONS?" question for them to be recognized as
    functions instead of arrays or strings.

    WEEK (e)    peek at 16 bit value
    CHR$ (e)    give string value of 'e'
    HEX$ (e)    give 4 character hex value of 'e'


4.  There are 31 new statements available which can be used on
    extended REM statements.

    DATA     READ     RESTORE  WOKE     WAIT     HOME
    FLASH    INVERSE  NORMAL   MIXED    FULL     PAGEl
    PAGE2    HIRES    LORES    CLREOL   CLREOP   HCOLOR=
    HGR      HGR2     HBACK    HFIND    HPLOT    SHAPE=
    SCALE    ROT      DRAW     XDRAW    GET      TONE
    NOTE



- 14 -

---------------------------------------------------------------------

LIST OF NEW STATEMENTS.


Here is a complete list of the new statements which can be used on
extended REM statements and their description of operation and syntax
specifications.


HOME
Same as CALL -936; clears the text window and puts cursor to upper
left hand corner.

FLASH
Same as POKE 50,63; allows charaters printed to appear in the
flashing text mode.

INVERSE
Same as POKE 50,127; allows characters printed to appear in the
inverse text mode (black characters on a white field).

NORMAL
Same as POKE 50,255; allows characters to print as white characters
on a black field (the normal mode of the Apple II).

DATA  +1,-2.3,$4,+$5,-$6,$-7
DATA  l,2,>0l23456789ABCDEF, "STR", 'STR'
Define data to be read with the "READ" statement.  The data may be
numeric or string intermixed with each other.  The numbers can have
signs or not and can appear as decimal numbers or hex numbers.  The
strings can be defined three different ways: with double or single
quotes surrounding them or as a string of hexadecimal data denoted
with the ">" symbol before the string.

READ  A, A(e), S$, S$(e)
Similar to the input statement except the input is from DATA
statements stored in the program. You must take care to read numeric
data into integer variables or arrays and string data into string
variables.  If you mismatch your variables with the data, a "***
BAD DATA TYPE ERROR" will appear.

RESTORE e
The value of e must be a line number with a DATA statement on it.
The RESTORE statement will reset the data pointer to a particular
DATA statement.








- 15 -

---------------------------------------------------------------------

MIXED
Same as POKE -16301,0; allows mixed graphics and text to appear on
the screen.

FULL
Same as POKE -16302,0; allows the full screen to be used for
graphics.  No text will be displayed.

PAGE1
Same as POKE -16300,0; sets the screen display to the primary display
page.  If text or Lores graphics is displayed the screen buffer is
$400-$7FF.  For hires graphics the displayed buffer is $2000-$3FFF.

PAGE2
Same as POKE -16299,0; sets the screen display to the secondary
display page.  If text or lores graphics is displayed the screen
buffer is $800-$BFF.  For hires graphics the displayed buffer is
$4000-$5FFF.

HIRES
Same as POKE -16297,0; sets the display mode to the hires graphics
screen.  (note that the text mode must be cleared before graphics are
shown).

LORES
Same as POKE -16298,0; sets the display mode to the lores graphics
screen.  (note that the text mode must be cleared before graphics are
shown).

CLREOL
Same as CALL -868; clears the current line from the cursor position
to the end of the line as defined by the window parameters.

CLREOP
Same as CALL -958; clears the current line from the cursor position
to the end of the page as defined by the window parameters.

WOKE e,e
16 bit POKE, pokes 2 bytes at the given address.  This can be used
with negative numbers without getting a >255 error.

WAIT e
Waits for milliseconds specified by e.  Graphics displayed by FLASH!
are sometimes too fast for the eye to catch an must actually be
slowed down so they can be seen!  This statement can help provide
time delays to help slow down action.



- 16 -

---------------------------------------------------------------------

HCOLOR= e
Set hires color to 0-7.  The colors are available as shown in the
following table:

    0 - black 1                 4 - black 2
    1 - green (depends on TV)   5 - (depends on TV)
    2 - blue (depends on TV)    6 - (depends on TV)
    3 - white 1                 7 - white 2

HGR
Turn on hires page 1 with mixed text/graphics and clear screen to
black.  HGR or HGR2 must be used before using any of the other hires
graphics commands.  To flip to hires page 2 after using page 1
without clearing the screen, use the command:

    1000 POKE 144, 64  : REM  .PAGE2

HGR2
Turn on hires page 2 with full graphics and clear screen to black.
HGR or HGR2 must always be used before using any of the other hires
graphics commands.  To flip to hires page 1 after using page 2,
without clearing the screen, use the command:

    1000 POKE 144, 32  : REM  .PAGE1

HBACK
Fills the current hires screen with the current hires color.  If the
color is set to 0 then it will clear the hires screen.

HPLOT  e1,e2
Plot 1 point using current hires color.  "e1" is the x coordinate
(0-279) and "e2" is the y coordinate (0-191).

HPLOT  e1,e2 TO e3,e4
Draw a line using current hires color.  "e1,e2" is the starting x,y
coordinate pair and ue3,e411 is the ending coordinate pair.

HPLOT TO e1,e2
Draw a line from last point to specified point using the current
hires color.  "e1,e2" is the ending x,y coordinate.

HFIND
Used after DRAW or XDRAW to locate endpoint of the hires shape in
order to draw a line to it.





- 17 -

---------------------------------------------------------------------

SHAPE= e
Specify the start address of a hires graphics shape table.  See the
APPLESOFT II Programmers Reference Manual page 92 for a discussion of
shape tables.

SCALE= e
Set scale factor for a hires shape.  The value "e" is a multiplier
for the shape table movements.

ROT= e
Set rotation factor for a hires shape.  The amount of rotation is
given by the value of "e" between 0 to 255.  Every increment of 16
represents a rotation of 90 degrees with 16 angles possible between.
The amount of rotation is also dependent on the scale factor chosen.
A scale factor of 1 will let 4 rotation values of "0,16,32,48" to be
recognized.  A scale of 2 will allow 8 rotations to be recognized.
unrecognized rotation values will cause the shape to be DRAWn with
the orientation of the next smaller recognized rotation.

DRAW n AT e1,e2
Draw a shape number n in shape table at x,y coordinate given by
"el.e2".  The shape table is described on page 47 of the APPLE
Programmer's Aid #1 Installation and Operating manual and on page 92
of the APPLESOFT II Basic Programming Reference Manual.

XDRAW n AT e1,e2
Exclusive OR shape number n in hires shape table at x,y coordinate
given by "e1,e2".  The first time you use XDRAW for a shape at an x,y
coordinate the shape will be displayed using the current color.  If
you use XDRAW a second time at the same coordinate using the same
color the shape will be errased and the screen will be as it was
before the first shape displayed.  If the shape happens to overlap
some other graphics figure, the figure is restored when the second
time the shape is XDRAWn at the same x,y coordinate.

GET A$, B$(2)
This will read the keyboard for 1 input character.  Any character
code including an escape or return key can be obtained with this
command.  A one character string is read and assigned to the given
string.








- 18 -

---------------------------------------------------------------------

TONE e1,e2
This command will play a tone given by a value in el for a length of
time given by e2.  The smaller "e2" is the shorter the duration of
the tone will be.  The pitch is given by "e1" and may range from 0
through 255 with the lower values giving the higher pitched tones.

NOTE e1,e2
This command will play chromatic scale notes for the duration given
by "e2".  The notes specified by "el" can be as follows:

    e1   NOTE    FREQUENCY     e1   NOTE    FREQUENCY

     0 - G sharp   208         18 - D         588
     1 - A         220         19 - E flat    622
     2 - B flat    233         20 - E         660
     3 - B         247         21 - F         698
     4 - middle C  262         22 - F sharp   740
     5 - C sharp   277         23 - G         784
     6 - D         294         24 - G sharp   830
     7 - E flat    311         25 - A         880
     8 - E         330         26 - B flat    932
     9 - F         349         27 - B         988
    10 - F sharp   370         28 - C        1046
    11 - G         392         29 - C sharp  1108
    12 - G sharp   415         30 - D        1176
    13 - A         440         31 - E flat   1244
    14 - B flat    466         32 - E        1320
    15 - B         494         33 - F        1396
    16 - C         523         34 - F sharp  1480
    17 - C sharp   554         35 - G        1568
                               36 - G sharp  1660



















- 19 -

---------------------------------------------------------------------

DEBUGGING COMPILED PROGRAMS.
                            


Programs compiled by FLASH! can use the normal TRACE, NOTRACE, DSP,
and NODSP commands in the Integer BASIC language.  If you add only a
NOTRACE statement to the program FLASH! will generate calls to R.LINE
at the start of each BASIC line to set the line number.  Any error in
subsequent execution will be shown with the familiar "STOPPED AT
xxxxx" error message.  An alternate debugging method is to use the
"RETURN STACK" data printed when an error occurs to locate the nested
calls to BASIC and runtime package subroutines.  By looking at the
listing of the line number table which FLASH! can print, you can
identify the offending statement from a listing of your BASIC
program. If you don't see the problem right off, you can use the
symbol table listing produced by the compiler to identify values to
display using the APPLE monitor dump commands.

Line number tracing takes an extra seven bytes of object code and
slows down the execution of a compiled program, so if you are not
debugging a program it is recomended that you take out all DSP,
NODSP, TRACE, and NOTRACE commands from your program to keep the
compiler from producing the extra code for each line number.

Since BASIC can have expressions as operands to GOTO and GOSUB
statements a line number table may have to be included with the
generated object code.  FLASH! will not include it however if all the
control statements in the program are to constant line numbers.
























- 20 -

---------------------------------------------------------------------

HANDY HINTS.


1.  The compiled program can be restarted after a reset. When a
program is restarted which uses the standard runtime package, the
runtime package is not reloaded from the disk. The runtime loader
will load it once.  A flag is cleared to stop a reload from
occurring.  To restart a compiled program use one of the following
techniques:

If you are using the standard runtime package and the default origin
of $1C00 then type:
    >CALL 7168  if you are in BASIC.
    *1C00G  if you are in the APPLE monitor

If you did not make an object file then type:
    ]CALL 2560  if you are in BASIC
    *0A00G  if you are in the APPLE monitor

If you specified your own origin for the program then use that
address as the entry point.

2.  The following code will detect if a program is running as
compiled code or as Integer BASIC interpretive code.  It takes
advantage of the compiler separation of simple variables from array
variables.  A possible use might be to not run code if FLASH!
language extentions are u~ed and Integer BASIC is running the program.

    10 DIM QWE(2)
    20 QWE=l : QWE(0)=2 : IF QWE=l THEN 50
    40 PRINT "INTEGER IS RUNNING" : GOTO 60
    50 PRINT "FLASH! CODE IS RUNNING"
    60 ..........

3.  A POKE 144,32 and a PAGE1 command will allow you to switch the
hires display to hires page 1 without clearing the plots you may have
on page 2.  Similarly a POKE 144,64 and a PAGE2 command will allow
you to switch to hires page 2.

4.  To locate the current compilation origin address if the program
uses the standard runtime package use the following code.  One use is
to make sure a compiled program that uses hires statements is
origined above the hires screen buffer. This code only works if you
specify an origin on a exact multiple of 256 bytes ($100) and do not
include the runtime package in the object file.

       10 GOSUB 30000
       15 REM THE LINE ABOVE MUST BE
       16 REM THE FIRST LINE OF THE PROGRAM
       20 PRINT "PROGRAM ORIGIN IS $"; HEX$(A)
          ............................
    30000 REM. WOKE 768, WEEK(510)
    30010 POKE 768,0: A=WEEK(768) : RETURN

- 21 -

---------------------------------------------------------------------

5. It is possible to share some data between two separate programs
and chain them together by the use of the DOS "BRUN" command.  By
control over the start address for free memory the user can have
shared memory between programs.  Only strings and arrays can be shared
this way and there is a special problem with passing strings.  As
long as the arrays are allocated the same amount of memory in each
program and the free memory starts at the same address; the arrays
for all practical purposes are identical even though data is not
input to the array in the second program and the names of the arrays
are different.

When a DIM statement is executed the memory is allocated from the
free memory space.  The allocated memory is not cleared to zero when
allocated by a DIM statement.  Therefore when an array is DIM'ed it
will have the initial data of whatever happens to be in memory at the
time.  This differs a little bit from the Integer BASIC interpreter
which will zero only the zero'th element of the array when it is
executes a DIM statement.  So to pass or share an array between two
programs all you need to do is to DIM them to the same size and
specify the same free memory start address and DIM them in the same
order of occurance in each of the programs.

Unfortunately a string has not only a maximum length provided with a
DIM statement but also a current length maintained while the program
assigns data to it.  Data in the overlay or chain program can still
be obtained however with the following method.

    PROGRAM 1 - assume that we want to pass the values in the array
                "A" and the string "C$" in program 1 to program 2.

    10 DIM A(20), B$(100), C$(400)
    20 FOR 1=1 TO 20 : A(I) = I * 5 : NEXT I
    30 FOR 1=1 TO 100 : B$(I) = "A" : NEXT I
    40 FOR 1=1 TO 400 : C$(I) = "X" : NEXT I
    50 REM . WOKE 768, LEN(C$)
    60 PRINT CHR$(4), "BRUN B.PROGRAM 2"
    60 END








- 22 -

---------------------------------------------------------------------

    PROGRAM 2

    5 FREE = ...
    10 DIM X(20), Y$(100), z$(400)
    20 L=WEEK(768)
    30 ZPTR=FREE + (21*2) + (100)
    40 FOR I = 1 TO L
    50 Z$(I) = CHR$(PEEK(ZPTR+I-l))
    60 NEXT I
    70 .......


The variable "FREE" in the second program must be assigned the value
of the memory address of the common free memory area shared by the
programs.  The free memory must not span across from $7FFF to $8000
or overflows on arithmetic will result in the PEEK function on
statement 50 or the computation of the string address in statement 30.

The value of ZPTR computed in statement 30 will be the memory address
of the string C$ if the first program and Z$ in the second program.
To compute ZPTR you must add the free memory start address ("FREE")
to the number of bytes in each array and string defined before "Z$".
Arrays have a zero'th element and 2 bytes for each element.
Therefore, the array DIM'ed to 20 will have "(21*2)" byte of memory
allocated.  Strings have only one byte for each element and begin
with element number one.  Therefore the string DIM'ed to 100 will
have "(100)" bytes of memory allocated.  So the final address
computation is:

ZPTR = FREE + (21*2) + (100)

Note that the array and string names in the two programs are not
important.  Only their DIM size must be the same and the ORDER OF
OCCURRENCE in the DIM statements for each program must be identical.
This is similar in function to the COMMON statement in the FORTRAN
language.  The free memory address for each program must be specified
to the same memory address when the programs are compiled by FLASH!.
Simple variables can be passed with the WOKE and WEEK extended
language features of the FLASH! compiler to POKE and PEEK 16 bit data
into known memory locations which will remain intact during the
switch between programs.









- 23 -

---------------------------------------------------------------------

A BUG IN INTEGER BASIC.
                       

You may be interested to know of a very bad bug in the Integer BASIC
Interpreter.  The bug does not appear in the FLASH! runtime package.
The problem is very difficult to get to occur on purpose but if it
does occur your program will execute erratically.  The bug is in the
FOR loop execution.  When Integer BASIC starts up a FOR loop it
checks to see if the FOR loop variable is currently on the stack of
FOR loops.  If the variable is found on the stack, then the whole
stack of FOR loops is shuffled to delete that entry from the stack.
The FOR loop stack is accually 10 separate stacks in Integer BASIC
and they are at memory locations $140-14F, $150-15F, $160-16F,
$170-17F, $180-18F, $190-19F, $1A0-1AF, $1B0-1BF, $1C0-1CF, and
$1D0-1DF.

These contain; the FOR loop variable in the $140,150 stacks, the
upper limit value in the $1C0,1D0 stacks, the step value in the
$160,170 stacks, the line address of the statement with the FOR loop
start in it (FOR) in the $180,190 stacks, and the offset following
the FOR loop statement to begin execution at when looping back from
the NEXT statement is in the $1A0,1B0 stack.  All stacks get shuffled
but the $1A0,1B0 stack only has the $1A0 stack shuffled twice!!  And
the MSB of the return address does not get shuffled at all!

This bug can cause a bad loopback to occur if each FOR loop shuffled
is not in the same page of memory as the inner loop beneath it on the
stack.  Most of the time it works because the page addresses are the
same or because FOR loops are not branched out of and the NEXT
statement will drop the loop from the stack when the loop falls
through the NEXT statement.

This explains some strange problems which occasionally defy debugging
and disappear when you change the program a little bit.  The
offending code is at memory locations $F288-$F2DF with the bad
instructions being:

    F2CE- B9 A1 01   LDA  $01A1,Y
    F2D1- 99 A0 01   STA  $01A0,Y
    F2D4- B9 A1 01   LDA  $01A1,Y
    F2D7- 99 A0 01   STA  $01A0.Y

If the following two instruction changes are made the problem becomes
fixed.

    F2D4- B9 B1 01   LDA  $01B1,Y 
    F2D7- 99 B0 01   STA  $01B0,Y

If you use a RAM card and run Integer BASIC in it then you could
patch the code to run all programs correctly.  What a difference two
bytes will make!


- 24 -

---------------------------------------------------------------------

A BUG IN PROGRAMMER'S AID ROM.


There is another bug located in the programmers aid ROM in the XDRAW
hires graphics subroutine.  It is located at $D29A-D2F8 in memory.
The offending instruction is at $D2E1:

    D2E1- 20 D9 D0   JSR $D0D9

If you run Integer BASIC in a RAM card you can make the following
instruction change.  The XDRAW subroutine can then be used, even
though the calling seguence is not described in the manual (because
it doesn't work).

    D2E1- 20 C1 D0   JSR  $D0C1

The XDRAW graphics routine is important for drawing a shape and later
erasing it allowing the screen to be completely restored to its
previous value before it was XDRAWn.  The routine is used just as
with the DRAW subroutine except that to erase a shape previously
plotted use the same scale, rotation, color and x,y position and call
XDRAW.  The shape will then disappear from the screen even if it was
plotted over the top of existing shapes and lines.  An alternate
entry XDRAW1 will allow linking of shapes together just as DRAW1 does
with the DRAW routine.  The entry points for the Integer BASIC
programmers aid XDRAW subroutine(s) are:

    10 XDRAW = -11449 : XDRAW1 = -11452

FLASHL will of course allow you to use the XDRAW command with an
active REM extended statement.  And it does not have the problem that
the programmers aid ROM does.  The XDRAW routine in FLASH! will work
without a patch.

      (This bug is corrected in Applesoft's hi-res routines)














- 25 -

---------------------------------------------------------------------

HOW TO ASSEMBLE THE ASSEMBLY FILE.
                                  

This section is for those users who have purchased the runtime source
code option.  The FLASH! compiler can be used without the assembly
file features.  The assembly file features provide more capability to
those users who enjoy a little machine language programming.

WARNING - DO NOT ATTEMPT TO MODIFY THE COMPILER RUNTIME PACKAGE BY
CHANGING THE RUNTIME SOURCE CODE MODULES AND ASSEMBLING OVER THE FILE
"B.RTP".  This is because FLASH! must "know" the addresses of the
runtime subroutine entry points to generate correct code to call the
runtime package routines.  Changing the runtime package does nothing
to the tables built into FLASH! which define the addresses of the
runtime package routines.  Also the runtime package is an actual
module built into FLASH!.  This module is in the CODE GEN phase and
not the "B.RTP" file.  Therefore, a change will not affect in memory
compilations nor will it affect compilations which have the runtime
code written into the object file.

One acceptable method of modification to the runtime package is to
write an assembly file with the compiler and assemble it with your
own modified version of the runtime package. An alternate method of
modification is to create your own version of the standard runtime
package by applying patches to the original runtime code file
"B.RTP".  You should backup all of the original copies of the source
code and the binary object file "B.RTP" before you attempt to work
with the runtime package in this manner.

The compiler assembly file can be assembled with the S-C Assembler II
4.0 if you have purchased the Runtime Package Source code.  Even
further improvements in execution time can be realized by recoding
the inner loops of your program. All compilers generate ineffcient
code.  A good assembly language programmer can always make some
improvement in the coding produced by any automatic program.  The
6502 machine language is somewhat badly organized to produce really
good assembler code since 8 bits are too much of a limiting factor
for most computations, you really need at least 16 bits to do any
serious programming.  This results in almost all of BASIC operations
being a call to a runtime package subroutine, otherwise a program
would be very large if 16 bit operations were performed inline in the
generated code with complete error checking.







- 26 -

---------------------------------------------------------------------

Therefore, with a little effort in recoding some of the code you will
be able to get another twofold to fourfold increase in speed.  To
obtain an Assembly Language file just answer the "ASSEMBLY FILEW
prompt with the name of the file you want to be created.  FLASH! will
write assembly language files using the name you provide appending a
'.A' through a '.Z' on the end of the file name to handle large
assembly files.  New files with the next higher letter will be
created automatically by FLASH! when the current assembly file
exceeds 8192 bytes in length.  This multiple file technique will
prevent a file too large for the assembler to load from being
created.  When the compilation is done you can use the S-C Assembler
II to assemble the file(s) created with the runtime package.

Programs with multiple source modules are most efficiently assembled
with the S-C Assembler II 4.0 by the use of an assembly control file.
If your assembly file did not assemble with the runtime package in
the object file you can use a control file similar to the one below
to assemble your compiler produced code.  You should delete any of
the .IN, .OR and .EN directives produced by the compiler in the
assembly output files.

    .OR $1C00                   standard program origin
    .TF B.MYFILE,D2             binary object code file
    .IN R.STD EQUATES,D1        equates for runtime
    .IN R.RUNTIME LOADER,D1     loads 'B.RTP' at $800 
    .IN MY.ASSEMBLY.FILE.A      modified FLASH! assembly output file
    .IN MY.ASSEMBLY.FILE.B      rest of assembly program
    .EN                         end of assembly.



Even though the compiler will put ".IN", ".OR" and ".EN" directives
in your assembly file you should edit these out into an assembly
control file.  This is because the include statements can only be one
level deep in the S-C Assembler II 4.0 and the module which has the
include statements in it remains in memory when the include files are
loaded from disk.  So the assembly control file should be as small as
possible when the includes are performed.










- 27 -

---------------------------------------------------------------------

The method is similar if you include the runtime package in your
object file.  A similar assembly control file can be built and used
as shown below.  You can even leave out modules which are not
referenced such as the DSP ASSIGNMENTS module and the HIRES modules
if you do not use the statements in your source code.  Note that the
UJMP L.START~ was moved out of the first assembly file!

    .OR $4000   special origin
    JMP L.START go to program start point
    .IN R.EQUATES               runtime package routines
    .IN R.DATA 
    .IN R.MATH
    .IN R.LOGIC
    .IN R.FUNCTIONS
    .IN R.ERRORS
    .IN R.STRINGS AND ARRAYS
    .IN R.GOTO/GOSUB/LOOPS
    .IN R.I/O ROUTINES
    .IN R.LORES
    .IN R.LANG EXT
    .IN R.HIRES1
    .IN R.HIRES2
    .IN R.HIRES3
    .IN R.DSP ASSIGNMENTS
L.START
    .IN MY.ASSEMBLY.FILE.A      modified FLASH! assembly output file.
    .IN MY.ASSEMBLY.FILE.B      more of assembly code.
    .IN MY.ASSEMBLY.FILE.C      still more assembly code.
    .EN






















- 28 -

---------------------------------------------------------------------

RUNTIME PACKAGE NOTES.
                      

1.  The X register is maintained at runtime and contains the current
stack pointer.  The runtime package preserves this register during
calls to external routines in a variable 'R.SP'.  The stack pointer
is = $20 if the stack is empty and goes to 0 as data is pushed to the
stack.  The stack pointer is always pointing to the top item of the
stack as long as the stack is not empty.

2.  Runtime routines which process expressions may have data either
on the stack or in the A and Y registers with the low byte in A and
the high byte in Y.

3.  The names of the runtime routines for the assembly language
listing adopt a convention as follows if they process expressions.

For unary operations such as negate, PDL, RND etc.

The name is "R.xxxx0" if the operand is in the A and Y registers.

The name is "R.xxxx1" if the operand is on the stack.

For binary operation such as +, ~, SCRN, POKE etc. The name is
"R.xxxx1" if the first operand is on the stack and the A and Y
registers contain the second operand value.  The name is "R.xxxx2" if
both operands are on the stack.  The second operand is on top.  The
first operand is always on the stack.

For the ternary operations such as VLIN, HLIN etc. The name is
similar to the binary operators except that the names have "2" and
"3" appended to the names and there are 3 operands instead of 2. The
first two operands will always be on the stack.

4.  Assigned variables have the following descriptions:

    * Integer variables have a 2 byte value at the symbol address.

    * Array variables have a 4 byte descriptor with the first two
      bytes being the address of the array and the next two bytes
      being the size of the array in bytes.

    * String variables have a 6 byte descriptor with the first 2
      bytes being the address of the string data, the next 2 bytes
      are the maximum size of the string in bytes, and the next 2
      bytes are the current length of the string.



- 29 -

---------------------------------------------------------------------

DESCRIPTION OF RUNTIME ENTRY POINTS.
                                    

The most commonly used routines in the runtime package are the stack
manipulation routines.

R.PSH - A,Y registers hold a 16 bit number.  This routine pushes it
        on the stack.

R.PUL - pulls a 16 bit number from the stack into the A,Y registers.


The following routines are binary operator routines.  The stack holds
the first operand el, and the A,Y registers hold the second operand
e2.  The operand on the stack is replace with the result of the
operation.

R.ADD1  - Compute e1 + e2
R.SUB1  - Compute e1 - e2
R.MUL1  - Compute e1 * e2
R.DIV1  - Compute e1 / e2
R.MOD1  - Compute e1 MOD e2
R.EXP1  - Compute e1 ^ e2
R.AND1  - Compute e1 AND e2
R.OR1   - Compute e1 OR e2
R.EQ1   - Compute e1 = e2
R.NE1   - Compute e1 <> e2 or e1 # e2
R.LT1   - Compute e1 < e2
R.GT1   - Compute e1 > e2
R.LE1   - Compute e1 <= e2
R.GE1   - Compute e1 >= e2
R.SCRN1 - Compute SCRN ( e1, e2 )


The following routines are binary operator routines.  The stack holds
the first operand e1 and the second operand e2 on top.  The result of
the operation replaces both operands on the stack.

R.ADD2  - Compute e1 + e2
R.SUB2  - Compute e1 - e2
R.MUL2  - Compute e1 * e2
R.D1V2  - Compute e1 / e2
R.MOD2  - Compute e1 MOD e2
R.EXP2  - Compute e1 ^ e2
R.AND2  - Compute e1 AND e2
R.OR2   - Compute e1 OR e2
R.EQ2   - Compute e1 = e2
R.NE2   - Compute e1 <> e2 or e1 # e2
R.LT2   - Compute e1 < e2
R.GT2   - Compute e1 > e2
R.GE2   - Compute e1 >= e2
R.LE2   - Compute e1 <= e2
R.SCRN2 - Compute SCRN( e1, e2 )


- 30 -

---------------------------------------------------------------------

The following routines take one operand from the stack and replace it
with the result of the operation.

R.NEG1  - Compute  - e1
R.NOT1  - Compute NOT e1
R.ABS1  - Compute ABS( e1
R.SGN1  - Compute SGN( e1
R.PDL1  - Read paddle number e1
R.RND1  - Compute RND( e1 )
R.PEEK1 - Get 16 bit value at address e1
R.WEEK1 - Get byte at address e1


The following routines have one operand in the A,Y registers.  The
result is determined and is pushed to the stack.

R.NEG0  - Compute  - e1
R.NOT0  - Compute NOT e1
R.ABS0  - Compute ABS( e1 )
R.SGN0  - Compute SGN( e1 )
R.PDL0  - Read paddle number e1
R.RND0  - Compute RND( e1 )
R.PEEK0 - Get 16 bit value at address e1
R.WEEK0 - Get byte at address e1

The following routines take an operand e1 from the stack and do not
put anything back.

R.CALL1   - Perform CALL e1
R.WAIT1   - Wait for e1 milliseconds
R.HCOLOR1 - Set hires color to e1
R.SHAPE1  - Set hires shape table address to e1
R.SCALE1  - Set hires shape scale factor to e1
R.ROT1    - Set hires shape rotation to e1
R.COLOR1  - Set lores color to e1
R.PRNTN1  - Prints out decimal value of e1
R.PRNTCN1 - Tabs to next field then prints out decimal value of e1
R.PRSLOT1 - Perform PR* e1
R.INSLOT1 - Perform IN* e1
R.VTAB1   - Perform VTAB e1
R.TAB1    - Perform TAB e1
R.REST1   - Perform RESTORE e1







- 31 -

---------------------------------------------------------------------

The following routines use a value in the A,Y registers. The stack is
not used for obtaining an operand and no result is left on the stack.

R.CALL0   - Perform CALL e1
R.WAIT0   - Wait for e1 milliseconds
R.HCOLOR0 - Set hires color to e1
R.SHAPE0  - Set hires shape address to e1
R.SCALE0  - Set hires scale factor to e1
R.ROT0    - Set hires shape rotation to e1
R.COLOR0  - Set lores color to e1
R.PRNTN0  - Prints out decimal value of e1
R.PRNTCN0 - Tabs to next field then prints out decimal value of e1
R.PRSLOT0 - Perform PR# e1
R.INSLOT0 - Perform IN# e1
R.VTAB0   - Perform VTAB e1
R.TAB0    - perform TAB e1
R.REST0   - Perform RESTORE e1

The following routines have 2 operands on the stack and the third
operand e3 is in the A,Y registers.  No result is returned to the
stack.

R.VLIN2  - Perform VLIN e1, e2 AT e3
R.HLIN2  - Perform HLIN e1, e2 AT e3
R.DRAW2  - Perform DRAW e1 AT e2, e3
R.XDRAW2 - perform XDRAW e1 AT e2, e3


The following routines have 3 operands on the stack.  No result is
returned to the stack.

R.VLIN3  - perform VLIN e1, e2 AT e3
R.HLIN3  - Perform BLIN e1, e2 AT e3
R.DRAW3  - perform DRAW e1 AT e2, e3
R.XDRAW3 - Perform XDRAW e1 AT e2, e3


The following routines have 2 operands on the stack.  No result is
returned to the stack.

R.POKE2  - Perform POKE e1, e2
R.PLOT2  - Perform PLOT e1, e2
R.HPLOT2 - Perform EPLOT e1, e2
R.HLINE2 - Perform HPLOT TO e1, e2
R.TONE2  - Perform TONE e1, e2
R.NOTE2  - Perform NOTE e1, e2
R.WOKE2  - Perform WOKE e1, e2



- 32 -

---------------------------------------------------------------------

The following routines have 1 operand on the stack (e1) and an
operand in the A,Y registers (e2).

R.POKE1  -  Perform POKE e1, e2
R.PLOT1  -  Perform PLOT e1, e2
R.HPLOT1 -  Perform HPLOT e1, e2
R.HLINE1 -  Perform HPLOT TO e1, e2
R.TONE1  -  Perform TONE e1, e2
R.NOTE1  -  Perform NOTE e1, e2
R.WOKE1  -  Perform WOKE e1, e2


The following routines do not fit a common pattern.

R.INIT - Perform runtime initialization.  Clear variable areas set
         runtime constants, hook into DOS for error processing.

R.JF0 - A,Y register has a logical value.  If value is true modify
        the 6502 return address by three to skip over a false jump
        command.  Otherwise return to execute the false jump to the
        false part of the IF statement.

R.JF1 - Stack holds a logical value.  If it is true add three to the
        6502 return address to skip over a false jump command to execute
        the true part of an IF statement.  Otherwise return into the
        jump command to execute the false part of the IF statement.

R.NES - Stack has two strings s1 and s2, see if they are not equal.
        A string is a pointer on the stack with a length below it.
        A logical true or false left on the stack.

R.EQS - Same as R.NES but tests for equal strings.

R.LINE - Set current line number to the value in the A,Y registers.

R.ASC - A string s1 is on the stack.  Take the first byte and leave
        it on the stack as a number.

R.END - Runtime clean up before returning to DOS or monitor.

R.PRTC - Perform a print tab, print nothing but spaces to the next
         tab position.

R.PRTS - A string s1 is on the stack, print its value.

R.PRTCS - Tab to the next tab position and print the string value of
          s1 on the stack.

- 33 -

---------------------------------------------------------------------

R.INP.STR0- A,Y registers have a string descriptor pointer read a
            line and assign it to the string.

R.INP.STR1- A,Y registers have a string descriptor pointer the stack
            has an offset into the string.  Read a line and assign
            it to the proper string position.

R.INP.VARB- A,Y registers have a variable address. Read a new line,
            convert all numbers for input, and assign the first input
            value to the variable.

R.INP.VAR - A,Y registers have a variable address. Assign the next
            value to the variable.

R.INP.ARYB- A,Y registers have an array descriptor pointer, and the
            stack has the array index.  Read a new line convert all
            the numbers for input, and assign the first input value
            to the array element.

R.INP.ARY - A,Y registers have an array descriptor pointer, and the
            stack has its index. Assign the next input number to the
            array element.

R.DIMA - A,Y registers have an array descriptor pointer, the stack
         has the dimension size for the array.  Assign (e1+l)*2 bytes
         of space to the array.

R.DIMS - A,Y registers have a string descriptor pointer, the stack
         has the dimension size for the array.  Assign (e1) bytes
         to the string.

R.STR.CON - Byte after JSR is number of bytes in string.  String
            follows the byte count. Skip over the string on return,
            put the string address and length on the stack.

R.STR0 - A,Y registers have a string descriptor pointer, leaves a
         string on the stack.  The top of the stack will be the pointer
         to the string characters and the second item on the stack will
         be its length.





- 34 -

---------------------------------------------------------------------

R.STR1 - A,Y registers have a string descriptor pointer, the stack
         has a position into the string.  The result will be the
         string character pointer modified, by the position, and
         beneath it the length of the string less the position offset,
         so the true length of the remainder of the string is the result.

R.STR2 - A,Y registers have a string descriptor pointer, the stack
         has two operands to specify a substring starting character
         position and ending character position.  This routine computes
         the true string character pointer and length and leaves them
         on the stack.

R.ASG.ARY - Three values are on the stack.  The value to assign to an
            array element is on top.  The array descriptor pointer is
            beneath it, and the index to the array element is on the
            bottom.  The routine assigns the value to the array element.

R.GET.ARY - A,Y registers contain an array descriptor pointer, the
            stack contains the array element index.  The value of the
            array element is left on the stack.

R.STRN0 - A,Y registers contain a string descriptor pointer, a one is
          pushed to the stack followed by the descriptor pointer.
          Used to set up a string assignment.

R.ASG.STR - Top of stack has a string character pointer and length.
            Beneath it is a string descriptor for the destination string
            and on the bottom is the position to assign the string to.

R.ASG.VAR - A,Y registers contain the variable address, the stack
            contains the value to be assigned.

R.GOTO1V - A,Y have a line number, Search the line number table for
           the line address and jump to the line.

R.GOTO1 - Stack has the line number, otherwise is sane as R.GOTO1V.




- 35 -

---------------------------------------------------------------------

R.GOSUB1V - A,Y have a line number to GOSUB to, search the line
            number table for the address and perform the GOSUB function.

R.GOSUB1 - Stack has a line number1 otherwise is same as the
           R.GOSUB1V function.

R.GOSUB0 - A,Y registers have the address of a subroutine to GOSUB
           to.  This routine counts GOSUBS so the FOR/NEXT loops don't
           get clobered on the top of the 6502 stack. The 6502 harware
           stack is used for several purposes, if the gosubs just did
           a JSR and they went too deep or got into an infinate loop
           the stacks would get destroyed.  This routine protects the
           runtime environment.

R.RETURN - Return to the previous GOSUB.

R.POP - Drop a return address from the BASIC return stack.

R.NEXT - A,Y registers have the FOR loop variable address.  performs
         the BASIC NEXT statement.

R.FOR - The stack has a step value (e1), a to value (e2), a from
        value (e3) and the for loop variable address.  This routine
        sets up the FOR loop stacks and maintains them.

R.FOR.1 - pushes a one for the step value, otherwise is identical to
          the R.FOR routine.

- 36 -

---------------------------------------------------------------------

R.FOR.DSP - Same as R.FOR except the variable value is printed after
            assignment takes place.

R.FOR.DSP.1 - Same as R.FOR.l except the variable value is printed
              after assignment takes place.

R.NEXT.DSP - Same as R.NEXT except the variable value is printed
             after assignment takes place.

R.ASG.DSP.VAR - Stack has variable address of a DSP descriptor for an
                integer variable.  routine assigns the value on the
                stack to the variable and then prints the value after
                assignment takes place.

R.ASG.DSP.STR - Stack has a string pointer and length and a string
                desctrptor below. assign the string then print its value.

R.INP.DSP.VAR - Stack has a variable DSP descriptor pointer.  Perform
                an input operation assign the value, then print the
                variable's value.

R.INP.DSP.VARB- Perform a new line input operation otherwise same as
                R.INP.DSP.VAR

R.INP.DSP.STR0- Read a string on a new line assign the value to the
                string whose descriptor is on the stack then print
                its value.

R.INP.DSP.STR1- Same as R.INP.DSP.STRO except that the sting
                assignment is to an offset of the assignment destination
                string.














- 37 -

---------------------------------------------------------------------

R.RDV - performs READ of a simple variable.
        i.e.    READ A

R.RDA - performs READ of an array value.
        i.e.    READ A(e1)

R.RDS0 - performs READ of a string value.
         i.e.    READ A$

R.RDS1l - performs READ of string with offset.
          i.e.    READ A$(5)

R.GET0 - Gets 1 character and assigns to the staring descriptor on
         the stack.
         i.e.  GET A$

R.GET1 - Gets 1 character and assigns to the string on the stack with
         offset below.
         i.e.  GET A$(5)

R.CHR0 - A,Y registers contain the operand e1, otherwise is same as
         R.CHR1.

R.CHR1 - Stack has value e1 a character to convert into a string, the
         string character pointer and length of 1 is left on stack.

R.HEX0 - A,Y registers have a number e1 to convert into a string of 4
         hex digits.  The string character pointer and length of 4 is
         left on the stack.

R.HEX1 - e1 is operand on the stack, otherwise is the same as the
         R.HEX0 routine.



















- 38 -

---------------------------------------------------------------------

The following routines need no data from the stack and return no
results onto the stack.

    R.TEXT   - Throw screen to text page 1.

    R.GR     - Throw screen to lores with 4 lines of text.

    R.HGR    - Throw screen to hires page 1 with 4 lines of text.

    R.HGR2   - Throw screen to hires page 2 with full screen graphics.

    R.HBACK  - Fill current hires screen with current hires color.

    R.HFIND  - Locates last position of a plotted hires shape so that a
               line can be drawn to it.




Several statements are executed in a compiled program as inline code.
The statements which are performed by inline code are:

    TRACE,  NOTRACE,  DSP,      NODSP,   GOTO
    LEN,    FLASH,    INVERSE,  NORMAL,  PRINT a blank line


Since the runtime package must support line number tracing the GOSUB,
FOR/NEXT LOOP handling will save and restore the current line number
even if there are no line numbers being sent to the R.LINE routine.



















- 39 -

---------------------------------------------------------------------

GLOSSARY.


address - A computer memory is made up of memory cells each of which
can contain a number.  Each memory cell can be called upon by a
unique number or address which will always refer only to that
particular memory cell.

algorithm - A series of steps which may be performed by a program or
other process, which will produce a given result.

ASCII - This is an acronym for the American Standard Code for
Information Interchange.  A standard set of numerical values which
most computers recognize as a set of characters.  This provides a
common reference for makers of computers, and peripherals, such as
keyboards, printers, or video text displays.

assembler - A program which converts assembly language to machine
language.  An assembler is sometimes called an assembly language
compiler.  The process of converting the assembly language to machine
language is known as assembling.

assembly file - A file which contains assembly language source code
which can be assembled by an assembler.

assembly language - A symbolic form of representing a computer
machine language.  The assembler allows more freedom to the
programmer by automatic handling of code relocation and addressing
references by labels.

backup - The process of making a copy of a program or data against
the possibility of its loss.

binary - A number system based upon powers of two.  A number may only
use the digits 0 and 1.  110 in binary, for example, is 0 units
digit, 1 twos, and 1 fours, or 6 in decimal.

bit - Acronym for binary digit.  A bit is the the smallest unit of
storage information in a computer and is represented by a 0 or 1.  A
byte is made of 8 bits of data which together can represent 0 through
255.

buffer - An area of memory used to hold data as it is being processed.

bug - A programming error.  Faulty operation of a program.

byte - The smallest unit of addressable memory on most computers.  A
byte can usually contain a number from 0 to 255 or one character
denoted by a number code such as ASCII.



- 40 -

---------------------------------------------------------------------

carriage return - A control character which indicates to a printer or
video display an end of one line and the start of another.

code - Executable instructions to the computer, usually in machine
language.

compile time - The time when a compiler program is executing and is
translating source code into object code.

compiler - A program which translates another computer program in a
human oriented form termed 'source code' to a form more easily
processed by a computer termed 'object code'.  The result may be
machine language or like PASCAL an intermediate code form such as
P-CODE.  The principal advantage to use of a compiler is faster
execution of computer programs.  The process of converting the source
code into object code is called compilation.

control characters - A special ASCII code which is used to perform
some unique function on a peripheral, but will not generate a
printable character.

decimal - A number system based upon the powers of ten. Digits range
from 0 to 9.

entry point - The memory address or symbolic address of a subroutine
or program starting point.

file - A named collection of data on a diskette or other mass storage
medium.  A file can contain data or programs.

forward reference - When a program is being parsed a reference to a
statement number or code segment not yet parsed is called a forward
reference.

hard error - An error in the computer which prevents the computer
from completing a process.

hexadecimal - A number system based upon the powers of sixteen.  The
digits range from 0 to 9 and A to F, where A is 10, B is 11. ... ,
and F is 15.  lAC is 1 256's, 10 16's, and 12 units, or 428 in
deciaml.

integer - A whole number with no fraction associated with it.  In
Integer BASIC an integer may range from -32768 to +32767.

label - A symbolic name associated with a memory address in assembly
language.  A label in assembly language is similar in function to a
statement number in BASIC.



- 41 -

---------------------------------------------------------------------

load point - The address where an machine language program begins to
be stored in memory when it is read into memory.

machine language - Computer instructions stored in memory as a
sequence of numbers.

null - Empty, having no length or value.  A null string is one which
contains no characters.  Also means the control character $00 which
is ignored by a printer.

object code - The result of a compilation or assembly which is
executable machine language instruction code.

object file - A file which will store the object code produced by a
compilation or assembly.

opcode - Short for operation code.  A numeric value which represents
an instruction to the computer.  Its assembly language equivalent is
called a mnemonic.

origin - The address at which object code will run.

page - A block of memory which contains 256 bytes.  The addresses of
each memory location all have the same high byte value.  Page 3 is
the range of memory from $0300 through $03FF.

parse - The process of interpreting character string data, such as a
command with expressions as operands.

patch - A small section of code or data which will fix a problem or
add a new feature to a program.

PROM - Acronym for programable read only memory.  This is
manufactured in a blank state and data is programmed into it with a
PROM programmer machine.

prompt - A question or other string which lets a user know that input
is expected.  A ">" character is the prompt for Integer BASIC.

pseudo-opcode - In assembly language this refers to commands given to
an assembler which do not produce data or machine language code when
assembled by an assembler.

RAM - Acronym for random access memory.  This is memory which can be
both read and written to.

register - A special location in a microprocessor in which special
operations are performed.  The 6502 microprocessor used by the APPLE
II has 5 registers; the A, X, Y, S, and P registers.  Registers are
used by machine language programs to access data and perform
arithmetic.


- 42 -

---------------------------------------------------------------------

release - A version of a distributed piece of software.

ROM - Acronym for read only memory.  This is memory which can only be
read and not written to.  A ROM is manufactured with the data already
programmed into it.

runtime - The time when the object code produced by a compiler is
executed.

runtime package - A collection of subroutines which aid and support
the object code produced by a compiler.

sign bit - The bit in a byte which determines the sign of a number.
The sign bit is usually the leftmost bit of the most significant byte
of a number.

soft error - A error usually caused by a progamming bug. These errors
can usually be corrected.  If it occurs during compilation the
compiler will continue execution to tell the user of any more errors
in the program.

software - Computer programs and data which can be executed.

source code - The original program as entered by a programmer is the
input for a compilation or assembly.

source file - A file which contains the original program as entered
by a programmer and isthe input for a compilati6n or assembly.

stack - A data structure which can be thought of as a coin changer to
which coins can be pushed into the top and also retrieved from the
top.  In a program the coins are data and the coin changer is the
stack.  Putting data on the stack is a push and taking data from the
stack is a pull.

subroutine - A program whose function is required repeatedly during
execution, and is therefore called by a main program or other
subroutines in several places.

table - A collection of data entries, having a similar format.
Entries in the table can be found by a "lookup" subroutine.  The
catalog on a disk is an example of a table.

tokens - A set of codes which are used to represent something other
than straight text in computer programs or text data.  A token in
BASIC can represent the keyword "print" for example by a one byte
value instead of the 5 bytes the ASCII codes for "print" would
usually take.

zero page - The first 256 memory location of a 6502 microprocessor's
memory.  Zero page therefore. is the memory from $0000 through $0OFF.


- 43 -

---------------------------------------------------------------------

APPENDIX  A.


Patch for listed expressions with the '.DA' directive.

This information is intended to be of use to the FLASH! owners who
have also purchased the runtime source code disk.  If you do not have
the source code disk this information may not be of use to you.  If
you do not have the S-C Assembler II version 4.0 then this patch will
not work.  If you have an earlier version of the S-C Assembler then
you can write S-C SOFTWARE, P. 0. BOX 280300, DALLAS TEXAS 75228 or
call (214) 324-2050 for information on how to upgrade to a newer
version.  If you own or upgrade to the S-C Macro Assembler then this
information is not needed.

The FLASH! compiler when creating an assembly output file will use
two features that are not standard to the S-C Assembler II 4.0.  The
features are generated for the following rare Integer BASIC
statements.  When a DATA statement is used or a GOTO or GOSUB with an
expression for the line number is used, FLASH! will create a table
for the line numbers and data statements numbers.  These tables will
contain a '.DA' directive with two expressions per line.  The S-C
Assembler II 4.0 will assemble only the first expression and will
ignore the second value causing an incorrect assembly of data.  When
a DSP or NODSP command is used in an Integer BASIC program FLASH!
will use a new directive '.AT' available in the new S-C Macro
Assembler II but not in earlier versions.  This will assemble a
string of text bytes with the last byte having the sign bit set.  To
assemble this directive split the code into the following form:

    .AT /ABCDEF/    S-C Macro Assembler directive

    .AS /ABCDE/     S-C Assembler II 4.0 equivalents:
    .AS -/F/

The '.DA' directive as shown in the standard S-C Assembler II 4.0
will only allow 1 expression on each directive.  This patch will
allow you to use a list of expressions on a directive.  Note that
this makes the '.DA' directive compatible in syntax with the new S-C
Macro Assembler II.

    .DA 1                   standard format

    .DA  1,10,100,1000      allowed after patch is applied.

If you have one of the earliest copies of the S-C Assembler II 4.0,
it may have some different addresses.  Check it out before you apply
the patch: at $20D4 you should find three JMP instructions, as
indicated in the comments here in lines 1210 through 1230.  If you
find those JMP's, go right ahead and make the patches.  Of course, if
you have already added code to the assembler you may have to put this
patch somewhere else.


- 44 -

---------------------------------------------------------------------

If you do not find those JMP instructions at $20D4, but you do find
them at $20B1, then you need to change a few addresses in the patch
code.  Change the following lines as indicated:

                    1170 PSDA   .EQ $2092
                    1190        .OR $20B1

This file is on the runtime source code disk and is named
'PATCH.FOR.DA', both binary target files are also on the runtime
source code disk.

                    1000 *                                        
                    1010 *   PATCH.FOR.DA
                    1020 *                                        
                    1030 *
                    1040 *   TO  INSTALL THIS PATCH:
                    1050 *   1.  BLOAD ASMDISK 4.0
                    1060 *   2.  BLOAD PATCH.DA.l
                    1070 *   3.  BLOAD PATCH.DA.2
                    1080 *   4.  BSAVE ASM 4.l,A$1000,L$14FB
                    1090 *----------------------------------------
    00DB-           1100 EXP.VALUE .EQ $DB
                    1110 *----------------------------------------
    128B-           1120 GNC    .EQ $128B
    l9FA-           1130 EMIT   .EQ $l9FA
    188E-           1140 CMNT   .EQ $188E
    20B5-           1150 PSDA   .EQ $20B5
                    1160 *----------------------------------------
                    1170        .OR  $20D4      REPLACES:
                    1180        .TF PATCH.DA.1
    20D4- 4C B0 24  1190        JMP BOTH.BYTES  (JMP $19B2)
    20D7- 4C C7 24  1200        JMP LOW.BYTE    (JMP $194D)
    20DA- 4C B5 24  1210        JMP HIGH.BYTE   (JMP $19D7)
                    1220 *----------------------------------------
                    1230        .OR $24B0       PATCH AREA
                    1240        .TF PATCH.DA.2
                    1250 BOTH.BYTES
    24B0- A5 DB     1260        LDA EXP.VALUE
    24B2- 20 FA 19  1270        JSR EMIT
                    1280 HIGH.BYTE
    24B5- A5 DC     1290        LDA EXP.VALUE+1
    24B7- 20 FA 19  1300 ALL    JSR EMIT
    24BA- 20 8B 12  1310        JSR GNC
    24BD- C9 2C     1320        CMP #',         COMMA?
    24BF- F0 03     1330        BEQ MORE
    24C1- 4C 8E 18  1340        JMP CMNT        FINISHED
    24C4- 4C B5 20  1350 MORE   JMP PSDA
                    1360 LOW.BYTE
    24C7- A5 DB     1370        LDA EXP.VALUE
    24C9- 18        1380        CLC
    24CA- 90 EB     1390        BCC ALL         ...ALWAYS




- 45 -

---------------------------------------------------------------------

APPENDIX B.


FLASH! and INTEGER BASIC character code table:

INTEGER BASIC character codes are offset from APPLESOFT codes by 128.

The CHR$ function should use the following character codes to perform
logical string operations.  The FLASH! print routine will add 128 to
characters < 128 before printing so that 'PRINT CHR$(7)' will still
perform as expected (print a bell character)

    DEC - ASCII decimal code
    HEX - ASCII hexadecimal code
    CHAR - ASCII character name
    n/a - not available on standard APPLE II keyboard.


    DEC  HEX  CHAR  WHAT TO TYPE

    128  80   NULL   cntrl @
    129  81   SOH    cntrl A
    130  82   STX    cntrl B
    131  83   ETX    cntrl C
    132  84   ET     cntrl D
    133  85   ENQ    cntrl E
    134  86   ACK    cntrl F
    135  87   BEL    cntrl G
    136  88   BS     cntrl H (left arrow)
    137  89   HT     cntrl I
    138  8A   LF     cntrl J
    139  8B   VT     cntrl K
    140  8C   FF     cntrl L
    141  8D   CR     cntrl M (RETURN)
    142  8E   SO     cntrl N
    143  8F   SI     cntrl O
    144  90   DLE    cntrl P
    145  91   DC1    cntrl Q
    146  92   DC2    cntrl R
    147  93   DC3    cntrl S
    148  94   DC4    cntrl T
    149  95   NAK    cntrl U (right arrow)
    150  96   SYN    cntrl V
    151  97   ETB    cntrl W
    152  98   CAN    cntrl X
    153  99   EM     cntrl Y
    154  9A   SUB    cntrl Z
    155  9B   ESCAPE ESC
    156  9C   FS     n/a
    157  9D   GS     cntrl shift M
    158  9E   RS     cntrl ^
    159  9F   US     n/a


- 46 -

---------------------------------------------------------------------

    DEC  HEX  CHAR  WHAT TO TYPE

    160  A0  SPACE   space
    161  A1    !        !
    162  A2    "        "
    163  A3    #        #
    164  A4    $        $
    165  A5    %        %
    166  A6    &        &
    167  A7    '        '
    168  A8    (        (
    169  A9    )        )
    170  AA    *        *
    171  AB    +        +
    172  AC    ,        ,
    173  AD    -        -
    174  AE    .        .
    175  AF    /        /
    176  B0    0        0
    177  B1    1        1
    178  B2    2        2
    179  B3    3        3
    180  B4    4        4
    181  B5    5        5
    182  B6    6        6
    183  B7    7        7
    184  B8    8        8
    185  B9    9        9
    186  BA    :        :
    187  BB    ;        ;
    188  BC    <        <
    189  BD    =        =
    190  BE    >        >
    191  BF    ?        ?




















- 47 -

---------------------------------------------------------------------

    DEC  HEX  CHAR  WHAT TO TYPE

    192  C0    @        @
    193  C1    A        A
    194  C2    B        B
    195  C3    C        C
    196  C4    D        D
    197  C5    E        E
    198  C6    F        F
    199  C7    G        G
    200  C8    H        H
    201  C9    I        I
    202  CA    J        J
    203  CB    K        K
    204  CC    L        L
    205  CD    M        M
    206  CE    N        N
    207  CF    O        O
    208  D0    P        P
    209  D1    Q        Q
    210  D2    R        R
    211  D3    S        S
    212  D4    T        T
    213  D5    U        U
    214  D6    V        V
    215  D7    W        W
    216  D8    X        X
    217  D9    Y        Y
    218  DA    Z        Z
    219  DB    [        n/a
    220  DC    '        n/a
    221  DD    ]        ] (SHIFT M)
    222  DE    ^        ^
    223  DF  underline  n/a



















- 48 -

---------------------------------------------------------------------

APPENDIX C.


COMPILER ERROR MESSAGES.


HARD ERRORS - These errors will stop the compilation.

COMPILE STOPPED BY OPERATOR
A control-C was typed.

COMPILE STOPPED BY ERRORS
Errors prevent a machine language program from being created.

FREF BUFFER OVERFLOW
The table which holds forward branches overflowed. This might occur
if you have more than 16 DATA statements or IF statements in one
line.  This would be a rare occurance in a user progran.

PROGRAM TOO BIG
SYMBOL TABLE OVERFLOW
There are just too many lines and variables to compile the program.
If you were performing a memory compilation try using a source file
to compile the program.

BAD PROGRAM STRUCTURE
MAYBE MACHINE CODE IS IN THE PROGRAM
When the PARSER phase of compilation obtains a line of source code to
compile it checks it for the end of line token "$01" at the end of
the line and if the token is not found the line is assumed to be bad.
The check prevents the compiler from crashing because a section of
machine code has been appended to the BASIC program.

OBJECT CODE ENCOUNTERS I/O AREA
Occurs during CODE GEN phase, if the program counter reaches $C000
for the generated code.

OBJECT CODE TOO BIG FOR RAM OUTPUT USE AN OBJECT FILE.
The code, symbol tables and the CODE GEN phase cannot all be in
memory at the same time.  By useing an object file for output a
larger program can be compiled.

PROGRAM TOO LARGE TO COMPILE SYMBOL TABLE OVERFLOW
The ALLOCATE and CODE GEN phase overlapped the symbol tables made by
the PARSER phase.  (there is more free memory available during the
PARSER phase than during the ALLOCATE phase so compile can't be
continued).



- 49 -

---------------------------------------------------------------------

SOFT ERRORS - (FLASH! continues with next numbered line), FLASH! will
list the line so the user can note the error.

VALUE >32767
In an active REM statement a number was too big to compile.

ARRAY OR STRING ALREADY DIM'ED
Can only DIM arrays and strings one time in a FLASH! program.

SYNTAX ERROR
Something is wrong with the statement listed, FLASH! doesn't
recognize something.  The error is probably in an active REM
statement since Integer BASIC will check syntax as the lines are
typed into a program.


The following soft errors will not list the source line because they
occur after the lines are PARSED and are no longer convienently
available for listing.

xxx$ IS NOT DIM'ED
String is not dimensioned.  FLASH! requires all strings to be
dimensioned.  INTEGER BASIC will allow a one character string without
a DIM statement.

xxx IS NOT DIM'ED
Array is not dimensioned.  FLASH! requires all arrays to be
dimensioned.  INTEGER BASIC will allow a one element array without a
DIM statement.

BAD LINE NUMBER #xxxxx in LINE #xxxxx
A GOTO or GOSUB used a line number that is not in the program.


















- 50 -

---------------------------------------------------------------------

CORRECTABLE ERRORS - These errors are detected during input of the
parameters to FLASH! before the PARSER phase begins.  The user is
allowed to retype the input line after the error occurs.

ORIGIN NOT >= $1C00!
MUST BE HIGHER THAN RUNTIME PACKAGE LOAD AREA.
    ERROR   RETYPE LINE
The runtime package ocupies $800 - $1BFF and the origin must be
higher than the load area for 'B.RTP'.  This error only occurs if you
do not include the runtime package in the object file and you used an
origin lower in memory than $1C00.

ORIGIN NOT >= $800 !!
    ERROR   RETYPE LINE
FLASH! will not compile code below this address.

NO PROGRAM IN MEMORY FILE NAME REQUIRED
    ERROR   RETYPE LINE
FLASH! must have an input file or no code can be generated.  The
memory does not contain a program so there is nothing to compile.

DUPLICATE FILE NAME!
FLASH! detects that you have given the current prompt file name the
same as the source file or object file name.  Note that in the case
of the assembly file, FLASH! tests for the file name plus ".A"
through ".Z" tacked on the end.  For example: an object file of
"ABCD.Z" and assembly file name of "ABCD" will cause the error to
occur when you type the assembly file name.

On any input error such as not answering Yes or No or null to a
question; or a bad address, slot number, drive number, volume number
or a bad file name syntax the following error message will result.

ERROR    RETYPE LINE












- 51 -

---------------------------------------------------------------------

COMPILER INTERNAL ERRORS - These errors should never occur unless
some unknown bug exists in FLASH! or a memory error exists or FLASH!
has been read incorrectly from disk.  If you can cause any of these
errors repeatably to occur please contact Laumer Research with the
problem.  FLASH! has been extensivly tested but bugs show up where
you least expect them to especially after extensivly testing for
those bugs (Murphy's Law)!  FLASH! stops on encountering any of these
errors.

ERROR 00 AT $xxxx
Return stack underflow

ERROR 01 AT $xxxx
Return stack overflow

ERROR 02 AT $xxxx
Data stack underflow

ERROR 03 AT $xxxx
Data stack overflow

ERROR 04 AT $xxxx
Multiply overflow

ERROR 05 AT $xxxx
Divide by zero

<0>
Disk error

<1>
Disk error

<2>
Disk error (bad call type)

<3>
Disk error (bad sub-call type)

INT ERR 1
FLASH! has internal checks for illegal conditions which could occur
because of a bug in the compiler, most of the checks occur in the
ALLOCATE or CODE GEN phase.

INT ERR 2
Something is wrong in the ALLOCATE or CODE GEN phase.

xx  - BAD TOKEN
Bad intermediate code file.  If you were using a RAM CARD it may have
a memory error.




- 52 -

---------------------------------------------------------------------

DISK ERRORS - These errors may occur during compilation.  The
compiler will stop execution.


WRITE PROTECTED
FLASH! needs to write a file to a disk and it finds that the output
disk is write protected;  Use a non-write protected disk.  (note: the
temporary file created by FLASH! is written on the compiler disk
therefore you should not write protect the compiler disk).

END OF DATA
Something strange happened to the temporary file used by FLASH!  This
error should never appear.

FILE NOT FOUND
You gave FLASH! a bad source file or FLASH! cannot locate the
temporary file.

VOLUME MISMATCH
The disk volume given does not match the actual volume in the drive.

DISK I/O ERROR
A bad spot exists on the disk use another diskette or reformat the
one in use.

DISK FULL
No more free space on the diskette.  Use a diskette with more free
space.

FILE LOCKED
FLASH! cannot write into the object or assembly language file because
it is locked.




















- 53 -

---------------------------------------------------------------------

APPENDIX D.


FLASH! RUNTIME ERROR MESSAGES.


Errors detected at runtime will print similar to the example shown
below.  The return stack addresses can be used with a LINE NUMBER
TABLE LISTING to locate the offending line if the program did not
have line number trace code created by FLASH!. If you still have
trouble locating the line just put in a 'NOTRACE' statement anywhere
in the program and recompile it. FLASH! will then create line number
code to store the line number each time a new line is executed.  When
the error condition is recreated the runtime package will print out
'STOPPED AT xxxx' just as if Integer BASIC had found the error! The
line number trace code adds 7 bytes to the code size for each
numbered line in the program so the program will be larger than it
was before and this will be reflected by different addresses printed
in the return stack information.

You should note that the addresses on the return stack will be the
address-1 of the return point because that is what the JSR opcode
puts on the stack.

Example of a BASIC program which would cause an error. source code

    10 GOSUB 20
    20 GOSUB 30
    30 GOSUB 40
    40 GOSUB 50
    50 VTAB 99  : REM  WILL CAUSE RANGE ERROR

runtime error messages

    *** RANGE ERROR

    STOPPED AT 50       (only if DSP, NODSP, TRACE, or NOTRACE used.)

    RETURN STACK        (6502 stack contents.)
    5D99                (return adrs for VTAB call)
    0000                (line # 40 if line # code created)
    5D92                (return adrs for GOSUB 50)
    0000                (line # 30 if line # code created)
    5D8B                (return adrs for GOSUB 40)
    0000                (line # 20 if line # code created)
    5D84                (return adrs for GOSUB 30)
    0000                (line # 10 if line # code created)
    5D7D                (return adrs for GOSUB 20)





- 54 -

---------------------------------------------------------------------

>32767  ERROR
Math overflow on +, -, * or /.

*** TOO LONG ERROR
Too many characters on input line.

*** SYNTAX ERROR
Bad number format on input line.

*** MEM FULL ERROR
Free space all used up. cannot execute an array or string DIM.

*** STRING ERROR
Bad string index or null string on the ASC function was used.

*** BAD BRANCH ERROR
Bad line number in a GOTO or GOSUB expression.

*** 16 GOSUBS ERROR
Too deeply nested subroutines.

*** BAD RETURN ERROR
Tried to return when not in a subroutine.

*** 16 FORS ERROR
FOR loop nested too deeply.

*** BAD NEXT ERROR
Can't find the matching FOR command.

*** >255 ERROR
Many basic routines will check their operands to see if the data is
out of range and error with this message.  i.e. TAB, VTAB, POKE,
SCRN, PDL, PR#, IN#, COLOR=, VLIN, HLIN etc.


*** RANGE ERROR
Array index too large or parameter too big.  i.e. VTAB, TAB, SCALE=,
ROT=, HCOLOR=, HPLOT, XDRAW, DRAW etc.

*** DIM ERROR
String or array not DIM'ed before it was used in the program. Also
DIM array larger than 32767.

*** STRING OVFL ERROR
Attempt to overflow the string length.

*** DIV BY 0 ERROR
Division by zero occurred.






- 55 -

---------------------------------------------------------------------

*** DIM 2ND TIME ERROR
Tried to DIM an array or string twice and the size was not same as
the first DIM.  FLASH! is forgiving if you DIM to the same size by
mistake.

*** BAD STACK PTR ERROR
If line number code is generated then the stack pointer gets checked
every time a new numbered line begins execution.  This message
generally means that bad code was generated by FLASH! or that one of
the runtime routines has a bug in it.

*** END OF DATA ERROR
Tried to READ more data than there was in DATA statements in the
program.

*** BAD DATA TYPE ERROR
Tried to READ a string as a number or a number as a string.

*** NO DATA ERROR
A RESTORE command was used in a program that has no DATA statements
coded.































- 56 -

---------------------------------------------------------------------

APPENDIX E.


PROGRAMS ON THE DISKETTE.

HELLO - The greeting program for Applesoft based Apples.

APPLESOFT - The greeting program for Integer BASIC based Apples.

FLASH - A fast loader program for the FLASH! compiler.  It loads
        FLASH! from the disk using fast, direct track and sector I/O.
        FLASH! is stored on tracks 18-26 of the diskette.

B.RTP - The standard FLASH! runtime package.  Do not tamper with this
        file!

AUTO BREAKOUT - An Integer BASIC demo which will play the breakout
                game by itself!  This is a fascinating executive
                pacifier.

RODS COLOR PATTERN - A Integer BASIC demo for FLASH!.  Uses lores
color graphics.

SIEVE - A benchmark program which computes prime numbers using the
        sieve of Erastothenes.

PENTOMINOES - A nice little program which will fit a set of little
              colored shapes into a rectangle which you can control
              the size of.  For more information on this look for
              the book "POLYOMINOES" by Solomon Golomb in your local
              library.

BIT BIN - Another demo program which shows the effects of speed up to
          basic generated sounds.











- 57 -

---------------------------------------------------------------------

MAZE FLASH VERSION - This program demonstrates hires graphics
                     commands.  This will not run under Integer
                     BASIC because of the use of special FLASH!
                     language features not in Integer BASIC.  When
                     compiled by FLASH! this program requires an
                     origin of $4000 or more because of the use of
                     hires page 1.


MAZE INTEGER VERSION - This program runs only under Integer BASIC
                       because of the use of PROGRAMMER'S AID ROM
                       routines

CUBIC - A sharp little 3 dimensional Tic-Tac-Tee program.  Will run
        under Integer BASIC or FLASH!.  Must have an origin of $2000
        or more when compiled by FLASH!.

CUBIC DATA 1C00.lFFF - Binary data required by the CUBIC game.  Loads
                       into memory at $1C00 through $lFFF.

B.AUTO BREAKOUT - Compiled demo of AUTO BREAKOUT.

B.RODS COLOR PATTERN  - Compiled demo of RODS COLOR PATTERN.

B.SIEVE - Compiled demo of SIEVE.

B.PENTOMINOES - Compiled demo of PENTOMINOES.

B.BIT BIN - Compiled demo of BIT BIN.

B.MAZE - Compiled demo of MAZE FLASH

VERSION.B.CUBIC - Compiled demo of CUBIC.

- 58 -

---------------------------------------------------------------------



































Laumer Research
1832 School Road
Carrolton, Texas 75006
(214) 245-3927

---------------------------------------------------------------------