💾 Archived View for mirrors.apple2.org.za › archive › apple2.caltech.edu › 8bit › dev › lisa › lisad… captured on 2024-12-17 at 23:25:35.
-=-=-=-=-=-=-
DOCUMENTATION FOR LISA V3.2
===========================
copyright 1983, Randall Hyde
copyright 1983, LazerWare
All Rights Reserved
Here it is -- LISA v3.2 addendum documentation. This doc file assumes that
you've got access to a LISA v2.6 manual. If you don't, call HAL Labs to get
one. Since this file was uploaded from an Apple Lisa running the 7/7 office
system, it has some peculiar characters in it. When you see the following,
make the appropriate changes:
G --> "<<"
H --> ">>"
I --> "..."
There may be other weird characters, but these three are used all over the
place.
Note, the copyright notice in this documentation can be ignored. Feel free
to (non-commercially) distribute this program to your friends. Ignore
notices of support provided by Lazerware or Randy Hyde in this doc. Support
for the product can be obtained from HAL Labs at (714) 780-3328.
So, without futher ado...
LAZER'S INTERACTIVE SYMBOLIC ASSEMBLER VERSION 3.2
A PRIMER FOR ADVANCED LISA V2.6 USERS
This short manual is intended to describe the additional features of the LISA
v3.2 assembler and the ALE (Advanced LISA Editor) program over the LISA v2.6
interactive assembler. This manual is not intended for beginning or even
intermediate LISA users. It assumes that the reader is quite familiar with
the features of LISA v2.6 and has mastered most of the features of that
product. If you've just begun learning 6502 assembly language or this is
your first experience with the LISA interactive assembler, please take the
time to master the use of the LISA v2.6 assembler before attempting to use
the v3.2 release.
This release includes several versions of the LISA macro assembler. Versions
for the standard NMOS 6502, CMOS 65C02, and CMOS 65C802 chips are provided.
These three assemblers are further broken down into three additional versions,
one for 64K Apple // systems, one for 128K (minimum) Apple //e and Apple //c
systems, and one for (older) Apple systems with a minimum of 80K installed.
Unlike most other assemblers now available for the Apple, LISA v3.2 is capable
of running on any Apple which supports ProDOS.
MEMORY REQUIREMENTS
Since ProDOS occupies the primary 16K language card bank, LISA v3.2 had to be
relocated elsewhere. For 128K (or larger) Apple //e and Apple //c systems,
LISA v3.2 and the ALE programs reside in the auxilliary memory bank. On the
older Apple ][ systems which do not support the auxiliary memory bank, two
16K language cards, a 32K card, a 64K card, or a 128K card (available from
various manufacturers) is required for proper operation of the LISA v3.2
assembler.
For smaller systems with only 64K, a special, limited, version of LISA v3.2
is available. The ALE program will not run on a 64K Apple ][ system. For
128K Apple //e and //c systems or Apple ][ systems with 96K or greater, a one
key command can be used to quickly switch between the LISA assembler and the
ALE editor (context switching is accomplished in about a second).
If you are using a standard 128K Apple //e or Apple //c, or the 64K version
of the assembler, you will be able to use LISA 'right out of the box'. If
you intend to use an 80K (or greater) Apple ][, you will need to run a
configuration program to install the assembler on your system; consult the
appendices for more details. Backing up LISA v3.2 Unlike many software
companies, Lazerware supplies its programs on copyable floppy disks. To
protect your investment, you should immediately make a working copy and a
backup copy from the diskettes supplied by Lazerware. To keep the cost of
this package down we copy information on both sides of the floppy diskette.
Although both sides are usually good, only one side is guaranteed by the
manufacturer.
You should make copies of the disks supplied by Lazerware as quickly as
possible and then never again use these diskettes (except in some extreme
emergency). This will help avoid the loss of important program files on the
diskette. While on the subject of disk copying, we freely encourage you to
make as many copies of this program as you feel necessary for yourself.
But please, don't make copies for all your friends as well. Treat this
software like a book. You can carry it from location to location (machine
to machine), but you can only use it in one location at a time.
Likewise, you can loan it to your friends, but while they're using you can't
(if you loaned your friend a book, you wouldn't be able to read it at the same
time s/he was). If you're using this program in a work environment, the same
rule applies: anyone can use it on any machine, but only one person can be
using it at any time. This package is priced so low that even the smallest
companies can afford additional copies if multiple work stations are required.
Lazerware provides extremely low-cost multiple station licenses for schools
and companies requiring more than five workstations.
RUNNING LISA V3.2
If you want to run under the ProDOS operating system, you will use the LISA
v3.2 assembler. LISA v3.2 runs under the ANIX v2.x operating system. ANIX
v2.x isn't actually a stand-alone operating system, but rather a shell for the
ProDOS operating system.
Other than the fact that ANIX v2.x reserves memory locations $9400...$BEFF
for its own use, ANIX v2.x is ProDOS (plus several enhancements). Since
the ANIX v2.x reference manual is quite large (and very expensive to
reproduce), a small ANIX primer is supplied at the end of this document.
Advanced users, who wish to take advantage of ANIX's power, may purchase a
copy of the ANIX manual directly from Lazerware.
LISA v3.2 requires a minimum of 64K RAM. For serious development, a minimum
of 80K is required. If you are running LISA v3.2 on an Apple //e, you should
install the extended memory card to boost that machine's capacity to 128K.
Since Apple //c systems are shipped with 128K, LISA v3.2 will run just fine on
these systems. If you are using an older Apple ][ or Apple ][ Plus system (or
an Apple ][ compatible system) you should install at least 80K of memory
before using the LISA v3.2 assembler.
LISA v3.2 requires this additional memory because, like LISA v2.6, LISA v3.2
normally sits in the language card area of the Apple //. Unfortunately, ProDOS
also resides in this area of memory. To resolve this conflict, LISA v3.2 uses
a special set of bank selection routines in page three which allow ProDOS and
LISA v3.2 to co-reside in (separate) 16K language card banks. A special
relocated version of LISA is available for 64K Apple systems. The 64K LISA
sits down in the lower 48K. In addition to reducing the amount of RAM avail-
able for source files and symbol tables, the 64K version doesn't provide the
LISA debugger/monitor program. You will have to use the Apple monitor with
the 64K LISA.
Apple ][ and Apple ][ Plus 80K versions require an additional 16K of bank
switchable memory to hold the assembler (since ProDOS always loads into the
primary 16K card bank). The additional 16K of memory can be installed in
a variety of ways. You can install two language cards into your Apple,
you can install a 32K card (like the Saturn 32K card manufactured by Titan
Systems, the RAMPLUS+ card manufactured by Mountain Computer, or the 32K
cards manufactured by Microtek and MPC), or you can install certain
high-capacity 64K and 128K cards manufactured by various companies including
Titan Systems, Legend Industries, Prometheus, STB, and Omega.
Note: any high-capacity card which is addressed like multiple 16K cards can be
used.
Certain high-capacity boards (like Apple's Megabyte memory expansion card,
the SVA 256K card, and the Synetix semiconductor RAM disk) do not meet
this criterion. With a high-capacity memory card, ProDOS loads into the
standard 16K bank and LISA loads into (one of) the alternate 16K bank(s).
Since there are several different bank selection schemes used by various
manufacturers, LISA v3.2 must be customized for the particular card you are
using (in extremely rare situations, you may be required to write your own
short bank selection routine). Installation details are covered in an
appendix at the end of this manual.
Once LISA v3.2 is loaded into an alternate language card bank (be it the
auxiliary memory bank on an Apple //e or Apple //c, or into an alternate
16K bank on an Apple ][ or Apple ][ Plus), the assembler almost behaves the
same regardless of which machine is executing the program. Since most LISA
v3.2 users will be using a 128K Apple //e or Apple //c, this document
will assume such is the case.
To run LISA v3.2, boot the LISA master disk type one of the following
program names after the ANIX "=" prompt:
If you wish to run the 64K version, type:
LISA.64K -To execute the LISA program.
LISAC02.64K -To execute the 65C02 version of LISA.
LISAC802.64K -To execute the 65C802 version of LISA.
ALE is not currently available for 64K users.
If you wish to run the full version, You must first install the appropriate
memory manager code by running SETUP.LISA (on the LISA.CONFIG disk). After
configuring LISA for your machine, you can execute LISA using one of the
ANIX commands:
LISA -To execute the LISA program.
LISAC02 -To execute the 65C02 version of LISA.
LISAC802 -To execute the 65C802 version of LISA.
ALE -To execute the Advanced LISA Editor program.
ALEC02 -To execute ALE for the 65C02.
ALEC802 -To execute ALE for the 65C802.
If your Apple has 96K (or more) RAM installed, the SETUP.LISA program will
merge LISA and ALE into a single file (LISA, LISAC02, or LISAC802).
CREATING A WORKING DISK
Due to the wide variety of Apple systems, there are a large number of files
provided on the LISA release disk. To create a working disk for your system,
only a few files are required.
For 64K systems, you only need:
PRODOS, ANIX.SYSTEM, LISA.64K (or LISAC02.64k/LISAC802.64k), and,
optionally, SETUP.LISA64K and DS.
For 80K, or greater, systems you will need:
PRODOS, ANIX.SYSTEM, LISA (or LISAC02/C802), ALE (or ALEC02/C802),
SETUP.LISA, and, optionally, DS. SETUP.LISA will be required to
configure your LISA system.
If you have installed more than 80K in your Apple II (e.g., a 128K Apple //e
or Apple //c) ALE and LISA will be merged into a single file.
THE LISA V3.2 EDITOR
With a few minor differences and three omissions (the FIND, APPEND, and LOB
commands), the LISA v3.x editor is used identically to the LISA v2.6 editor.
There's also an additional program, ALE (advanced LISA editor), which provides
several new editing commands including find, search and replace, several new
listing options (including listing forwards and backwards in the file), block
move and copy commands, a built-in hex calculator, several reference charts
(including the ASCII character set and all of the ProDOS equates), plus other
features. On 128K Apple //e and Apple //c systems and on 96K (or greater)
Apple ][ systems, a single keystroke command will automatically switch between
the assembler and ALE programs so that the extended editor will always be
available. For major editing tasks, the ALE program is a big improvement over
the LISA v2.6 editor.
One of the major differences between the LISA v2.6 editor and the LISA v3.2
editor is how screen editing is handled. Screen editing under LISA v3.x is
handled by the ANIX operating system. If you want to change the screen editing
keys for LISA v3.2/ANIX v2.x, the ANIX v2.x SETUP.ANIX program is used. ANIX
v2.x is shipped prepared for an Apple //e or Apple //c keyboard. If you own
an older Apple ][ system you will probably want to change a few of the screen
editing assignments with the SETUP.ANIX program.
Once you run the LISA v3.x program, you will be greeted with a LISA v3.x
sign-on message and the exclamation mark prompt. At this point, all of
the LISA v2.6 editor commands except Append, LOB, Find, control-P, Read,
and Write operate almost exactly as before. Append, LOB, and Find are not
implemented in LISA v3.x (Find has been moved into the ALE program, there's
no need for LOB, and Append can be simulated with Read and Write);
control-P (the user command) is implemented with the LISA v3.x "U" command;
and Read and Write are implemented a little differently. Finally a new
command, "SYS", has been added which will return control to the ANIX
operating system.
Within the LISA v3.x assembler/editor, the following commandls concerning these
commands.
The following commands have (very) minor differences between the LISA v2.6
command and the corresponding LISA v3.x command:
LOad Syntactically, the LISA v3.x LOad command is used exactly like
LISA v2.6 LOad command. The only difference is the syntax for
the filename accepted by the operating system. LISA v3.2 allows
only ProDOS/ANIX v2.x filenames after the load command.
SAve Same filename restrictions as LOad.
LEn The length command displays some additional information in addition
to the length of the file.
CTRL-D In LISA v2.6, control-D is used to preface a DOS 3.3 command. In
LISA v3.2, CTRL-D marks an ANIX v2.x command. Consult the appro-
priate ANIX reference document for more details.
The Read, Write, and CTRL-P commands perform the same functions as before,
they're just implemented a little differently. CTRL-P behaves exactly like
its LISA v2.6 counterpart, it jumps to location $E009 ($5C09 on 64K systems)
where a JMP instruction which transfers control to a user-written command.
The difference between the LISA v2.6 and LISA v3.x user commands is that LISA
v3.x uses the "U" symbol to execute the user command rather than CTRL-P. The
Read and Write commands are used exactly like their LISA v2.6 counterparts,
except the syntax for the filenames has changed a little. First of all, the
filename must be a valid ProDOS filename, secondly, the ">" symbol must pre-
cede the filename in the Write command and the "<" symbol must precede the
filename in the Read command. E.g.:
R <MYFILE.TXT
W 5,25 >YOURFILE.TXT
R 65 <YOURFILE.TXT
W >TEXT.VERSION
Two new commands, which don't have a LISA v2.6 counterpart, have been added
to the LISA v3.x assembler: CTRL-P (actually an ANIX command) and SYS.
Whenever control-P is encountered at the beginning of a line, ANIX will
turn on the printer device (which is usually the interface card in slot
one). The printer will remain on until control-P is once again pressed at
the beginning of an input line. The SYS command jumps into ANIX (at the
warmstart entry point). SYS should be used to quit the assembler. The
"RUN 300" (warmstart) and "RUN 303" (coldstart) commands can be used to
restart LISA v3.2 from the ANIX "=" prompt.
THE ASSEMBLER
While the current editor is actually inferior to the LISA v2.6 editor (it
doesn't support the Find, LOB, or Append commands), the assembler is
another story. The LISA v3.x assembler is three times faster, contains
tons of new features, and LISA v3.x uses a much better tokenizing scheme
which reduces the amount of memory required to hold the source file by 25%.
If you don't go crazy with comments in your source file, you can easily
enter over 3,000 lines of text into the LISA v3.x default source file
buffer. LISA v3.x supports several new instructions, assembler directives,
and pseudo-opcodes. A list of the new instructions includes:
.ME .WE IF1 IF2 EXP NOX
NLC CND ADD SUB WHL .MD
FZR LCL RLS INP CON SET
ANX SBT CHN RVS MSG ZRO
Gone are the Sweet-16 instructions (you can use macros to emulate Sweet-16 if
you really need these instructions), LET (replaced by SET), DCM (replaced by
ANX), ICL (replaced by CHN), ASC (substitute BYT), and ENZ instructions. The
65C02 version of LISA v3.x does not support the Rockwell-only BBS, BBR, SMB,
and RMB instructions found in the LISA v2.6 XPO assembler.
A couple of instructions behave a little differently. The "=" assembler
directive is identical to the SET (LET) directive. In LISA v2.6 the "="
directive was the same as EQU. The HEX pseudo-opcode, although still
functional, is converted on input to a BYT pseudo-opcode by the editor.
This makes the listing easier to read. PHS and DPH work properly in
this version of the assembler. All zero page variables (defined with the
EPZ directive) must be declared before they are used; see the description of
FZR.
Finally, as promised in the LISA v2.6 manual, symbols may only contain
alphanumerics, periods, and underscores; and the order of evaluation for
expressions has been changed. All expression are evaluated from left to
right. Also, many of the LISA v2.6 operators and constant formats have
changed; see the section on address expressions for more details.
MACROS
A macro is a single assembly command used to replace several LISA
instructions. A single macro, for example, can replace several 6502
instructions and LISA pseudo-opcodes. In certain circumstances, a macro
definition can help you create a program with fewer bugs since the number of
bugs in a program is proportional to the number of lines of code.
Unfortunately, the overzealous use of macros can actually introduce
several new bugs since macros tend to hide several instructions and their
possible side effects from the programmer. Macros were included with LISA
for two reasons: to make LISA v3.x a more marketable product (few people
will purchase an assembler without macros, even if they really have no use
for macros) and to ease the task of converting assembly language source
listings from other assemblers to LISA. Expert assembly language
programmers rarely use macros since they tend to make programs harder to
read and less efficient.
Macros are defined with the .MD (macro definition) and .ME (macro end)
directives. .MD must be followed with a single LISA symbolic name limited
to seven characters in length. All of the assembler statements between the
MD statement and the .ME statement will be stored in the LISA symbol table
and recalled as necessary for the macro definition. Since the macros are
stored in the symbol table, avoid placing comments in macro definitions
since comments will quickly eat up available memory. An example of a
macro definition is:
.MD SAVEREGS
PHA
TXA
PHA
TYA
PHA
.ME
This macro, when invoked, outputs the five instructions:
PHA
TXA
PHA
TYA
PHA
Since LISA checks the validity of all mnemonics entered into the system, a
special character must be used to mark a macro. Currently, all macro calls
must be prefaced with a slash character ("/"). For example, a subroutine
which uses the previously defined macro to save all the registers is:
SUBRTN /SAVEREGS
LDX #0
LOOP DEX
TXA
STA $1000,X
TAY
STA $2000,Y
BNE LOOP
/RESTREG ;Complement to SAVREGS
RTS
The macro lead-in character is user definable. The ASCII code for this
character can be changed with the SETUP.LISA program. While almost any
character can be used, you should not use an alphanumeric or a period.
A macro may have up to ten optional parameters. Currently LISA v3.x only
allows address expressions as parameters. String parameters will be allowed
in a later version. Parameters for a macro appear in the operand field of
the macro invocation separated by commas. The ten parameters are accessed
within the macro definition using the symbols "?0", "?1", "?2", I, "?9".
The "?0" symbol returns the value of the first parameter, the "?1" symbol
returns the value of the second parameter, etc. As an example, consider the
macro definition:
.MD MOVWORD
LDA ?0
STA ?1
LDA ?0+1
STA ?1+1
.ME
An invocation of the form: "/MOVWORD LOC1,LOC2" generates the code to copy
the 16-bit value at location LOC1 to the two bytes starting at location
LOC2. This invocation of the macro would expand into the instruction
sequence:
LDA LOC1
STA LOC2
LDA LOC1+1
STA LOC2+2
Each occurrence of ?0 is replaced by "LOC1" and each occurrence of ?1 is
replaced by "LOC2".
Two additional macro parameter values, "? " and "?:GexprH", may be of
interest to you. The "? " symbol returns the number of parameters
actually present. You can use this token to test for an exact number of
parameters. In the previous macro definition, the macro is expecting
exactly two parameters. You could rewrite the macro to test for exactly
two parameters with the code:
.MD MOVWORD
.IF ?# <> 2
PAU
.EL
LDA ?0
STA ?1
LDA ?0+1
STA ?1+1
.FI
.ME
The ".IF" directive compares the actual number of parameters passed to
MOVWORD with two, if the number of parameters is not equal to two, then
the assembler encounters the PAU instruction and stops, printing the pause
error message. If the number of parameters is exactly equal to two, then
the LDA/STA instructions are assembled (also see MSG below). With certain
macro definitions, you may want to allow a variable number of parameters.
If a variable number of parameters are desired, you will need some method
of accessing the individual parameters using a variable index.
The "?:GexprH" token can be used to access a parameter using an expression
to select the desired parameter. For example, "?:2" selects the third
parameter. "?:5" selects the sixth parameter (remember, the first
parameter is ?0). Note that these two usages perform the same operations
as "?2" and "?5". The real advantage of this form of parameter passing is
that the value following the colon can be any expression. If X is a label
declared as a value between zero and nine, "?:X" returns the value of the
Xth parameter. If X was declared with the SET or "=" pseudo-opcode, the
value of X can be changed during program assembly.
A parameter of the form "?:GexprH" uses the complete expression following
the colon to select the parameter. For example, if the label X is
currently equal to zero, the expression "?:X" returlus one. Therefore, if you
wish to modify the
parameter's value, the "?:" token must appear as the last token in the
address expression.
E.g., If X=1 and the second parameter is $1000, then "1+?:X" returns $1001
while "?:X+1" returns the value of the third parameter (if it is present).
The "?:GexprH" and "? " operands are extremely useful in conjunction with
while loops. The while loops can be used to easily process a variable
number of parameters within a macro. See the explanation of WHL below.
During assembly, LISA v3.x, by default, will expand the macro and list
all of the lines which compose the macro. Such lines are prefaced with a
plus sign ("+") to denote a macro expansion. To disable macro expansion
listing, the NOX (for NO eXpand) can be used. To turn macro expansion
back on, the EXP (for EXPand) pseudo-opcode is used. All macros between
an NOX directive and a EXP (for EXPand) will not be expanded.
While on the subject of macros, LISA v3.x has a couple of built-in
macros not found in LISA v2.6. The ADD macro is an ADC instruction which
emits a CLC opcode prior to outputting the ADC instruction code. The SUB
macro is a SBC instruction which emits a SEC instruction prior to
outputting the SBC opcode. Local Labels Consider for a moment the
macro definition:
.MD INC16
INC ?0
BNE >0
INC ?0+1
^0:
.ME
This looks like a very straight-forward macro used to increment a sixteen-bit
memory location. Unfortunately, there is a big problem with this macro.
Consider the code segment:
LDA TSTINC
BEQ >0
/INC16 POINTER
LDA #0
STA TSTINC
^0:
If TSTINC is zero, control will be transferred to the first "^0" label in
the file. The first "^0" label encountered will be the "^0" label inside
the INC16 macro. Therefore, the program will jump to the LDA 0 instruction
rather than past the STA TSTINC instruction. This, of course, can create
some very hard to find bugs.
To alleviate this problem, LISA v3.x supports a special form of local
label: the symbolic local label. Local symbolic labels are allocated and
deallocated with the LCL (local) and RLS (release) assembler directives.
Whenever "LCL GlabelH" is encountered in the source file during assembly,
LISA v3.x "temporarily" forgets that the specified label was already
defined. The label is marked as undefined in the symbol table and assembly
continues. When "RLS GlabelH" is encountered, the current definition is
lost and the original definition is restored. There is a current
restriction to LCL/RLS pairs with the same symbolic label: they may not be
nested. If a nested LCL is encountered, LISA v3.x terminates the previous
local definition before beginning the current one. The INC16 macro
definition, recoded to take advantage of symbolic local labels, is:
.MD INC16
LCL I16LBL
INC ?0
BNE I16LBL
INC ?0+1
I16LBL:
RLS I16LBL
.ME
This macro definition will work fine as long as you do not include the
/INC16 macro invocation inside another piece of program code which redefines
the I16LBL label using LCL and RLS. Should this occur, the value of I16LBL
would revert to its original value and an error would be given when the
next RLS pseudo-opcode was encountered. The following is an example of
such a situation:
I16LBL: EQU 5
LCL I16LBL
I16LBL EQU 4
/INC16 WORDVAL
BYT I16LBL ;Uses the value 5 rather than 4.
RLS I16LBL ;Generates an error.
An error is generated because the local label I16LBL is automatically
released by the occurrence of the LCL pseudo-op in the INC16 macro, then
the RLS pseudo-opcode in the macro releases the label to its original value.
The RLS pseudo-op in this program segment attempts to release a label
which isn't currently a local label, hence an error is generated. In
practice, this situation rarely occurs, but you should look out for it.
Note that you are not restricted to defining local labels within macros,
you can also define local labels within your main program code. This lets
you define blocks of local labels in a fashion similar to the Pascal or "C"
programming languages. Keep in mind, you are limited to one level of
nested local labels. Conditional Assembly and the While Loop LISA v3.x
supports nested ".IF" statements. This lets you include ".IF" directives
within macros without having to worry about the macro invocation appearing
inside an ".IF" directive somewhere else. Nested ".IFs" are also useful
within the body of your programs. The severe limitation of one level ".IF"
statements in LISA v2.x has been removed from LISA v3.x.
LISA v3.x also supports two new conditional assembly instructions: IF1 and
IF2. The code between "IF1" and the corresponding .EL or .FI is assduring pass
two.
WARNING! Do not include any instructions which modify the program counter
(i.e., that generate object code) inside these directives. Doing so will
generate a "phase error".
A phase error occurs when more or less bytes of code are generated in
one pass of an assembly than in the other pass. For example, consider:
ORG $800
IF2
BYT 0,1,2,3,4,5,6,7
.FI
LABEL JMP LABEL
The BYT pseudo opcode is ignored during pass one since it is surrounded by
the "IF2" and ".FI" pseudo-opcodes. Since, during pass one the BYT statement
is totally ignored, LISA thinks that the LABEL symbol is encountered at
address $800. Without the "IF2/.FI" directives, LISA would encounter eight
bytes of data before the occurrence of "LABEL" and would have assigned the
value $808 to it. Since the "IF2" pseudo-op is present, the JMP instruction
assembles into a JMP $800 instruction rather than a JMP $808 instruction.
The assembler will print an error message if a phase error occurs during
assembly.
The WHL assembler directive can be used to set up loops within the
assembling code. This feature can be used to repeat certain sections of
code or to process macro parameters when you have an unknown number of
parameters. The WHL directive expects a single address expression in the
operand field. The code between the WHL and the corresponding .WE (While
End) is repeatedly assembled until the address expression after the WHL
directive is zero. A short macro which generates a split address list for
up to ten addresses is:
.MD SPLITADR
X=0
WHL X < ?#
BYT ?:X
X=X+1
.WE
;
X=0
WHL X < ?#
HBY ?:X
X=X+1
.WE
.ME
This macro generates a table of bytes for each parameter present, and then it
generates a table of high-bytes for each parameter present.
WARNING! The WHL loop can get you into a lot of trouble if you're not
careful. In particular, you can generate some nasty infinite loops if you
omit code which tweaks the address expression following the WHL mnemonic or
if the expression never evaluates to false. Such a situation will cause
the system to hang during assembly. If an assembly appears to take an
abnormally long time, perhaps you've created an infinite WHL loop
somewhere. The WHL directive should be used only by expert programmers
with extreme caution.
Normally, LISA v3.x lists the code between .IF, IF1, or IF2 and the .EL
or .FI regardless of whether the code was assembled or not. Likewise,
when the WHL expression evaluates to zero, LISA v3.x will list the code
between the WHL and the .WE even though it isn't assembled. To shorten
the assembly listing down a little bit, the NLC (No List Conditionals) and
CND (list CoNDitionals) assembler directives can be used. These directives
(respectively) disable and enable the listing of unassembled code within
the .IF, IF1, IF2, and WHL conditional directives.
NEW STRING DIRECTIVES
LISA v3.x supports two new string directives: RVS and ZRO. Both directives
must be followed by a single string. These directives handle special
requirements of certain programs. The RVS pseudo-opcode emits the characters
in the string in the reverse order that they appear within the string.
This directive is useful if you want to access the data within a string
using a loop counter which decrements to zero (or to minus one). Simply
load an index register with the length of the string minus one and index
into the string, this will access the first character of the string
following the RVS pseudo-op:
RVS "ABC"
..generates the code $C3, $C2, $C1 (C, B, A). The ZRO pseudo-opcode emits
the specified string followed by a zero byte. This directive is quite useful
when working with zero terminated strings.
MISC. ASSEMBLER DIRECTIVES
The CON (constant) directive is currently a synonym for EQU. However, in
future versions of LISA v3.x, a label defined with the CON directive will
only be allowed within immediate expressions or within an address expression
for a pseudo-opcode. You should not use CON to define variable names. The
intent of the CON directive is to help make your programs more readable.
The CON directive instantly identifies a label as a constant, not a variable
in memory or the entry point of some subroutine. By using CON for constants
and EPZ/EQU for variables and entry points, you can make your programs much
easier to read and understand. Most 6502 assembly language programmers
define all of their zero page labels at the beginning of the program before
they are encountered within an address expression. This geography is
considered good programming style. Although there is probably no reason why
you cannot always define a zero page label (using the EPZ pseudo-opcode)
before the label is encountered within a program, a special pseudo-opcode,
FZR, is included in LISA v3.x's repertoire to allow you to state that a
symbol is zero page without defining its value before it is used.
This pseudo-opcode is especially useful when converting certain LISA v2.6
programs to LISA v3.x.
The FZR (Forward Zero page Reference) assembler directive is used to define a
zero page label without assigning a value to it. LISA v3.x is a two-pass
assembler (LISA v2.6 was a three pass assembler) and it assumes that
undefined labels are absolute. If a zero page label is defined with the EPZ
directive after that label was already encountered in the source file, LISA
v3.x will give you an error. To correct this problem, either move the zero
page definition to the beginning of the source file (if practical or
possible) or use the FZR assembler directive to define the label as zero page
before the label is used. The syntax for the FZR directive is:
FZR <label>
<label> must not have been previous defined.
If you do not understand why FZR is required, consider the following program
sequence:
ORG $800
LDA ZPG
LBL LDX ZPG
DEX
BNE LBL
ZPG EPZ $0F
During pass one of the assembly, LISA computes the address of LBL by adding
up all of the program bytes from the beginning of the program to the label.
Unfortunately, when then't yet been defined (in pass one), LISA v3.x assumes
that the label is an
absolute label and treats the LDA as a three-byte instruction. Later during
pass one, ZPG is defined to be a zero page value. So during pass two, a
two-byte instruction (rather than a three-byte instruction) is generated
which causes a phase error. To prevent this from happening, LISA v3.x will
print an error message if you attempt to define a zero page label after it
was encountered in the text. To solve this little problem, simply move the
EPZ definition to an earlier point in the text or use the FZR pseudo-opcode
to state that the label is a zero page label. Incidentally, LISA v2.6
doesn't require a mechanism like this because it is a three-pass assembler.
LISA v2.6 collects all of the zero page labels during pass one and then
processes the remaining text during passes two and three. LISA v3.x is a
two-pass assembler which is why FZR is required. The advantage of a two-pass
assembler is that it is significantly faster than a three-pass assembler.
Note that the LCL pseudo-opcode completely undefines the label following it.
If a label is declared as a zero page label (with either EPZ or FZR) and
then that same label appears in the operand field of an LCL pseudo-opcode,
you must declare the new value of the label before it is used if the label is
a zero page label. Good programming style dictates that local labels defined
via equate statements be declared right after the occurrence of the LCL
directive. MSG, whose sole operand must be a string, prints a message during
both passes of the assembly. The IF1 and IF2 directives can be used to
selectively print the message during pass one or two. The up-arrow (caret)
character has special significance within a MSG string.
"^^" prints a single up-arrow character.
"^R" prints a carriage return.
"^H" homes the cursor and clears the screen.
"^B" beeps the speaker.
Other special characters will be defined in later versions of LISA v3.x.
SBT is used in a fashion identical to TTL. SBT is used to define a
subtitle. The single string which follows is stored in LISA's internal
subtitle string variable and it is output at the top of each page immediately
below the major title. SBT does not cause an automatic page ejection.
Follow the SBT directive with a PAG directive if you wish a form feed.
The CHN directive is identical to LISA v2.6's ICL directive, except only
valid ANIX filenames are allowed within the string following the CHN
mnemonic.
The ANX directive (for ANIX command) is similar to the LISA v2.6 DCM
command. It lets you execute an ANIX intrinsic command during assembly.
This command is useful for SAVE'ing binary object code to disk, changing
default disk drives with the "PREFIX" command, etc. Placing a control-P in
the quotation marks will turn on the ANIX printer device. Note that unlike
DCM, ANX is active on both passes. Use the IF1 and IF2 directives to execute
ANX during only one of the passes.
The INP command will prompt you to enter the value of a label during
assembly. A symbol defined this way is always an absolute label.
Note that the ASC directive which appears in LISA v2.6 is not implemented in
LISA v3.x, use the BYT directive instead.Address Expressions Address
expressions in LISA v3.x have changed dramatically since LISA v2.6. In
fact, the major source of file incompatibility centers around address
expressions. First of all, LISA v3.x evaluates expressions from left to
right.
This is a source of incompatibility between the LISA v2.6 assembler (which
evaluates expressions from right to left) and the LISA v3.x assembler. For
example, in LISA v2.6 the equate:
LBL EQU 5-3+1
evaluates to 5-(3+1) returning one. In LISA v3.x this expression evaluates
to (5-3)+1 returning three. The exclamation mark is no longer allowed in
front of decimal constants. Negative decimal constants should be entered as
a minus sign followed by the decimal digits.
The format for single character constants (e.g., after the " " in an
immediate expression) has been changed somewhat. With LISA v2.6 the
quotation mark is represented using the character sequence """. In LISA
v3.x, four quotation marks are required (which makes the usage identical to
that for character strings). Likewise, when you are enclosing character
expressions within apostrophes, the apostrophe character is represented with
four apostrophes, e.g.,
''''.
LISA v3.x supports three unary operators, "-" (negation), "~" (logical
complement), and "@" (relative address). The "-" operator takes the two's
complement of the value which follows, the "~" inverts the bits of the value
which follows. The "@" operator subtracts the current location counter value
from the address that follow the "@" (at sign). The unary operators have
precedence over the binary operators.
LISA v3.x supports fourteen binary operators. They are:
+ - * / & | ^
= < > % <= >= <>
Note that LISA v2.6 uses " " for not equal and LISA v3.x uses "<>" for not
equal. Interleaving spaces are not allowed between the two characters in the
"<=", ">=", and "<>" operators (you'll see why in a minute). The comparison
operators return zero if the comparison does not hold, one if the comparison
is true. The "%" operator is the modulo (remainder) operator. It returns
the remainder of the operand to the left of the "%" divided by the operand to
the right.
Like LISA v2.6, LISA v3.x reuses several symbols as operators in address
expressions. Such multiple use can lead to certain ambiguities. For
example, consider the expression:
>0<>0
Does this mean >0 <> 0, or does it mean >0 < >0? To eliminate such problems
in these rare situations, simply type ">0 <> 0" for the first form, or ">0 <
>0" for the second form. Unlike LISA v2.6, LISA v3.x's editor allows you to
enter spaces into the middle of address expressions. These spaces are used
to resolve conflicts when an ambiguity problems arise.
The BYT, ADR, HBY, and DBY pseudo-opcodes allow the same operands as the
".DA" directive. ASCII strings (surrounded by quotation marks or
apostrophes) generate a single byte of data for each character in the string.
If an address expression is prefaced with a pound sign (" "), then LISA v3.x
will logically AND the sixteen-bit address expression with $FF and use the
result as the value for the address expression. For example, the instruction
"ADR $FFEE" is identical to "ADR $EE". The "/" operator, if it prefaces an
address expression in the operand field of BYT, ADR, HBY, or DBY, shifts
this address expression to the right eight bits and uses the resultant value.
"ADR /$FFEE" is identical to "ADR $FF". "BYT /$FFEE" is equal to "BYT $FF"
which is equal to "HBY $FFEE".
Note that "HBY /$nnnn" always produces zero, regardless of the value of
$nnnn. The " " and "/" operators behave exactly like their LISA v2.6
counterparts when they are used in the operand field of a ".DA" or "CSP"
instruction.Converting LISA v2.6 Files to LISA v3.2 LISA v3.2 uses a
completely different tokenizing scheme than LISA v2.6. The advantages to the
new scheme include reduced storage requirements and a faster assembly rate.
The disadvantage is that LISA v2.6 files cannot be directly loaded into LISA
v3.2.
To convert a LISA v2.6 (or any older version of LISA) source file to LISA
v3.2, the first thing you should do is assemble your LISA v2.6 source file
and save the object code to disk.
This is a very important step! Next, write the LISA v2.6 source file to disk
using the LISA v2.6 W)rite command. At this point, run the ProDOS CONVERT
utility and copy the text and object code files from your DOS 3.3 disk to a
ProDOS disk (if you are still running LISA v1.5 on DOS 3.2, MUFFIN the file
to DOS 3.3 before running the CONVERT utility). Then boot LISA v3.x and use
the LISA v3.x R)ead command to tokenize the source file. While the file is
being read into memory, LISA v3.2 will stop whenever it encounters a line it
doesn't like. This usually occurs when an ENZ, ICL, ASC, or DCM directive is
encountered in the LISA v2.6 source file. LISA v3.x will also print an error
message and make you retype the line if a decimal constant prefaced with an
exclamation mark or three apostrophes (or quotation marks) are found on the
line. Simply retype the line without the exclamation mark or add an
additional quote or apostrophe to the line. In the case of ENZ, simply hit
return. For ICL, substitute CHN for the ICL and check to make sure the
filename is a valid ANIX filename. If you encounter an ASC pseudo-opcode,
substitute BYT for ASC and copy the operand field after the BYT directive.
DCM requires the most modification since ANIX commands and DOS 3.3 commands
are somewhat different. Consult the ANIX manual for more details concerning
valid ANIX commands.
Another place you may encounter difficulty is with the older LISA v1.x style
immediate character and hexadecimal constants. The earliest versions of LISA
allowed an immediate operand to consist of an apostrophe or quotation mark
followed by a single character, or a hexadecimal value that began with a
numeric digit. E.g.:
LDA 'C -- Same as LDA 'C'
LDA "C -- Same as LDA "C"
LDA 01 -- Same as LDA 01
As promised in the LISA v2.6 manual, these forms of the immediate operand
are no longer supported. In the case of the first two instructions, the LISA
v3.2 editor will print an error message when you attempt to read the
instruction into the editor. The third case will produce an error only if
the hexadecimal value following the instruction contains a hexadecimal digit
in the range $A...$F. If the value following the instruction is composed
entirely of decimal digits, LISA v3.2 will think that you wish to access the
zero page memory location specified by this decimal address. The easiest way
to catch this type of error is to compare the object code produced by LISA
v3.2 against the object code produced by LISA v2.6 (or earlier), see the next
paragraph for details.
After you've R)ead the entire file into memory, save the file to disk with
the LISA SA)ve command. Note the size reduction over the LISA v2.6 version!
After saving the source file to disk, assemble the file and leave the object
code in memory. Now load the object code saved from the LISA v2.6 assembly
at a different location and compare the two pieces of object code using the
monitor Verify command. Note any locations which are different between the
two assemblies and compare the code emitted by LISA v3.x to LISA v2.6. If
there are some differences which aren't easily explained, chances are you've
encountered an address expression which returns a different value in LISA
v3.x than in LISA v2.6. Go back to your source listing and check the
instructions which generated the bad code. Check both the actual address
expression value and the definitions of any labels used in the expression.
If it doesn't make sense why the bad code was generated, call Lazerware at
(714) 735-1041 to report the problem.
CONVERTING LISA V3.1 FILES TO LISA V3.2
To allow for the additional addressing modes provided by the 65C802 chip, some
internal tokenization formats had to be changed between LISA v3.1 and LISA
v3.2.
If you have some files in a 3.1 format that you would like to convert to the
3.2 form, simply W)rite the 3.1 file to disk and then R(ead the textfile back
into LISA v3.2. Other than the tokenizing scheme, LISA v3.1 files are
absolutely compatible with LISA v3.2.
IF YOU FIND A BUG IN LISA V3.2
Actually not "IF", when you find a bug in LISA v3.2 we would appreciate
it if you would tell us about it. But please, make sure it really is a bug
before calling us. Also, try to locate the exact nature of the problem. An
error report of the form "the system just hangs up" is of no value to us.
Find the exact instruction where the assembler is misbehaving (if during
assembly) or try to locate the exact sequence of events which create a
problem in the editor. The more information you can supply the faster we can
fix the problem.
The best form of a bug report is to send us a copy of your LISA v3.x disk
with the source file containing the problem and a description of where the
problem occurs (naturally, all source files will be handled on a strictly
confidential basis and will be destroyed once the problem is isolated).
The next best solution is to send us a printout of the source file where the
problem occurred. If either of these cases are impractical, a written
description describing the problem and where it occurs is the next best
thing. A phone call is the least desirable alternative (although you may
want to call in to see if the bug has already been discovered).
All correspondence should be sent to:
Lazerware
2271 Indian Horse Dr.
Norco, Ca. 91760
All phone inquiries:
(714) 735-1041 to leave a message.
OTHER LISA V3.2 FEATURES
In additional to other tokenization features, LISA v3.2 tokenizes the symbols
at edit time and maintains an edit time symbol table. You are limited to 512
symbols for any single source file. If you get a "Too many symbols" error,
SA)ve the source file to disk as a LISA v3.x file, W)rite the file to disk as
a text file (keeping in mind the 122 sector limitation of ANIX v1.2), clear
the source file with the LISA N)ew command, and then R)ead the source file
back into memory retokenizing it. This will almost always solve the problem
since LISA v3.2 does not delete symbols from the edit time symbol table which
are no longer present in the source file. The W)riting and R)eading operation
strips all unused symbols from the edit time symbol table. A big source file
(with about 3,000 lines) typically has between 300 and 400 symbols.
The DS (Dump Symbols) program on the disk can be used to dump the symbol
table after an assembly. To use this program, type:
<control-D>LOAD DS<return>
after the LISA v3.2 "!" prompt, and then type
"<control-D>RUN 800"
If you wish to send the output to a printer in slot one, typing control-P at
the beginning of a line turns on the printer. Under ANIX v2.1 you can direct
the output to any slot, or even to a disk file using RUN commands of the form
"<control-D>RUN 800 >.Sn" (to slot 'n', you should avoid this form)
"<control-D>RUN 800 >.P" (to the printer)
"<control-D>RUN 800 >.C" (to the communications port)
"<control-D>RUN 800 >FILENAME"
assuming, of course, that you've installed the appropriate ANIX device driver.
THE ADVANCED LISA EDITOR (ALE)
Without question, the biggest addition LISA v3.2 offers is the Advanced LISA
Editor (ALE for short). The Advanced LISA Editor program brings a full funct-
ion editor to the LISA assembler environment. Additional commands like find,
find and replace, move, copy, improved listing facilities, intraline editing,
and a help command give the LISA user all of the editing features (and more!)
found in the other assembly language packages. On top of the new editing
features, ALE also provides a built in hexadecimal calculator, a ASCII
character set reference chart, two ProDOS equate reference charts, an ANIX
v2.1 equate reference chart, and a CHARIO equate reference chart (CHARIO is
an ANIX v2.1 subroutine). The new editor package will dramatically reduce the
amount of time required to work on an existing program.
First the bad news. You don't get all of this editing power for nothing.
ALE is a separate program from the LISA assembler, hence you will not be able
to quickly perform an assembly immediately after an editing session.
Another piece of bad news: a version of ALE is not available for LISA v3.2
users that runs on a 64K system.
You will need a minimum of 80K in your Apple ][ system (or 128K in your
Apple //e or Apple //c system). If you are running on an 80K Apple ][ or
Apple ][ Plus system, you will need to reload the assembler before performing
the assembly; this means you will lose several seconds when switching between
the editor and assembler (you've got to save the current workfile, enter ANIX,
load the LISA assembler, load your workfile, and then you can assemble your
sourcefile).
Now for some good news. If you've got a 96K or larger Apple ][ /][ Plus or
a 128K Apple //e-//c, both LISA and the ALE program may reside in memory at
the same time and can be swapped in less than four seconds (less than two
seconds on an Apple //e-//c). The disadvantage, of course, is that your
Apple requires a bit more memory. On a 128K Apple //e or Apple //c this
won't affect you since the minimum amount of memory LISA will work with is
128K, but on the older Apple ][ Plus systems you will need three language
cards, a 32K card and a 16K card, or a 64K (or larger) memory board.
Lazerware recommends a 64K or 128K memory board since the additional memory
in Apples so equipped can be used for other purposes besides running LISA
and ALE (like disk emulators, Visicalc* expanders, etc.). Keep in mind, the
extra memory isn't necessary for running ALE, it just makes ALE's execution a
lot more convenient. This document will make no distinction between the
combined ALE/LISA and the separate ALE -LISA programs. The usage of the
individual programs is identical except for the mechanism used to swap
between the two programs. The following script should be followed when
switching between LISA and ALE on an 80K Apple ][ or Apple ][ Plus system:
From LISA to ALE:
!SAVE <filename> -- Save current workfile to disk.
!SYS -- Quit LISA and enter ANIX v2.0.
=ALE -- Execute the ALE program.
:LOAD <filename> -- Load workfile into memory.
From ALE to LISA:
:SAVE <filename> -- Save current workfile to disk.
:SYS -- Quit ALE and enter ANIX v2.0.
=LISA -- Execute the LISA assembler program.
!LOAD <filename> -- Load workfile into memory.
On a 96K (or larger) Apple system, this process is tremendously simplified.
When running the SETUP.LISA program, you will be asked if you have a 96K (or
larger) Apple system. If you answer yes (by specifying your particular memory
configuration) then SETUP.LISA will create a LISA program which automatically
loads the combined LISA/ALE program into memory. When running the combined
version, you can switch between the LISA assembler and the ALE editor by
simply type "U" followed by return. E.g.:
From LISA to ALE:
!U H -- Switch to ALE (takes a few seconds)
From ALE to LISA:
:U -- Switch to LISA (takes a few seconds)
! -- THE PROMPT CHARACTER
The prompt character can be used to determine which program you're currently
operating in. LISA uses an exclamation mark for the prompt character (a
carry over from the mini-assembler found in Integer BASIC for those of you who
are curious) and the ALE program uses a colon for its prompt character. If
you ever find yourself in the wrong program, simply press "U" to switch
between the two.
THE NEW ALE COMMANDS
The Advanced LISA Editor program is an extended version of the standard LISA
editor. ALE was created by removing the assembler from LISA v3.2 and using
the space freed to extended the editor. Since ALE is an extension of the LISA
editor, all of the editor commands you've been using in LISA are present in
ALE as well. So you're not going to have to learn a whole new set of commands
just the new commands that ALE provides. All of the standard LISA v3.2 edit-
ng commands are supported in ALE.
Probably the first new command worthy of discussion is help. Whenever you
are presented with the ALE colon prompt, you can get a list of the commands
by pressing a question mark followed by return. So if you forget one of the
editing commands, simply press "?" and ALE will list all of the commands.
If you're already missing LISA v2.6's FIND command in LISA v3.2, fret not, a
much better version is supplied in the ALE program. The FIND command in LISA
v2.6 searched only for labels in the source file; the ALE command will search
for almost any string within a LISA v3.2 source file. The syntax for the
FIND command is:
F{ind} <string>
The curly braces surround optional characters, i.e., "F" followed by a space
works just fine. Note that "FR" is reserved for FIND & REPLACE, so the
second character of the FIND command must not be an "R" unless you want to
execute the FIND & REPLACE command.
The FIND command builds the string by locating the first non-blank character
after the FIND command. The string consists of every character from this
non-blank character to the end of the line. Once you press return, ALE will
search for each occurrence of the specified string and the line containing
that string will be listed. Since there may be multiple occurrences of the
string on a single line, ALE always inverts the string when the line is
displayed on the screen. So if the same line is listed twice, it's due to
multiple occurrences on the same line.
If there are more than 22 occurrences of the string within your source file,
you can temporarily halt the FIND command by pressing the space bar. Once
you've stopped the listing by pressing the space bar, pressing control-C will
abort the FIND command, pressing return will list the next occurrence of the
string in the file, and pressing any other key will resume the fast search.
The ALE FIND command converts all lower case characters to uppercase before
performing the search. Therefore, the case of the search string is
irrelevant. To speed up the (already slow) searching process, a programming
trick was used to match upper and lower case characters. There are two
unfortunate side effects of this programming trick: first, all characters in
the range $C0...$DF will match all characters in the range $E0...$FF; second,
all characters in the range $80...$9F will match all of the characters in the
range $A0...$BF. This means that, in addition to converting lower case to
uppercase, certain special characters will match other characters. For
example, the grave accent ("`") will match the at sign ("@"). Likewise, the
numeric and lower valued special characters will match the control characters.
Since control characters almost never appear within an assembly language
source file, this second problem will rarely cause you any trouble.
Another command present in ALE, one which has been long requested by
faithful LISA users, is a FIND & REPLACE command. The syntax for this
command is FR Gsearch stringH ^ Greplacement stringH The up-arrow character
(the little caret symbol above the "6" on Apple //e and Apple //c systems,
above the "N" on Apple ][ and Apple ][ Plus systems) is used to separate the
search string with the string it is to be replaced with. The following
command replaces each occurrence of "LBL1" with "LABEL1":
FR LBL1^LABEL1
Whenever the FIND & REPLACE command locates a line containing the search
string, it lists the line to the screen and asks you if you want to replace
this occurrence with the replacement string. When so prompted you may enter
"Q" or "q" for quit, "Y" or "y" for YES, or "N" or "n" for NO. All other
input will be ignored. If you answer YES, the FIND & REPLACE command will
substitute the replacement string for the source string and attempt to
retokenize the new line. If an error occurs during tokenization, you will
have to retype the entire line (hopefully in a corrected form) into ALE. If
you select "N", then the FIND & REPLACE command ignores the current line and
searches for the next occurrence of the search string. If you select "Q",
the FIND & REPLACE command will abort processing and return to the ALE
command mode. The ALE program also provides COPY and move (TRANSFER)
commands. These useful commands let you duplicate a block of statements
within the file or move a block of statements elsewhere in the file. The
syntax for these commands is:
CO{py} <start>, <end>, <dest>
TR{ansfer} <start>, <end>, <dest>
The three parameters following these commands are all line numbers within
the source file.
The <start> line number is the first line of the source block which you want
to copy or move. The <end> line number, which must be greater than or equal
to the <start> line number, is the line number of the last line of the line
of the block to be copied or moved. If <end> is greater than the last line
in the file, it will default to the last line in the file.
The <dest> parameter is the destination line number. This value must be
greater than <end> or less than <start> or ALE will give you an error.
The COPY command will duplicate lines <start>...<end> at line number <dest>.
The TRANSFER command also performs this duplication, but then deletes the
original lines from the file.
Three new versions of the list command have been added to ALE's command
repertoire. Pressing a comma (",") followed by return lists the next 15
lines in the file. Pressing a period lists the fifteen lines around the
current line. Pressing a hyphen ("-") lists the prior twenty lines. These
list commands simulate the page up, page down, and rewrite page commands
found in screen oriented editors.
The current line is defined by the last LIST, DELETE, or INSERT command
executed in ALE. The last line listed by the last LIST command (including
",", ".", and "-") becomes the new current line. If the last command was a
DELETE command, the line after the last (or only) line deleted becomes the
new current line. If the last command was an INSERT (or MODIFY) command,
then the current line is the first line after the text you've inserted. The
period command is really useful for cleaning up the display, especially after
you've performed several screen editing commands. The comma and hyphen list
commands simulate page down and page up commands in a screen oriented editor.
These commands are great for leisurely searching through a source file.
In addition to the new editor commands, ALE also supports four built in
intraline editing commands. These commands, which are available while in the
insert mode, simulate the up and down arrow key functions in a screen
oriented editor; they allow you to skip over or edit lines adjacent to the
current input line. These commands are invoked by pressing control-A,
control-B, control-C, or control-W as the first character of an input line.
The control-A and control-B commands are complementary.
The control-A command takes the previous line and moves it down making it
the next line in the file. For example, if you accidentally entered the
insert mode one line below the desired line, you could use control-A to move
the insertion point in front of the previous line.
The control-B operation performs the converse operation to the control-A
command; it swaps the current line with the next line in the source file.
Control-B is useful for several things. It lets you skip over any number
of lines in the source file allowing you to selectively insert lines within
the source file without having to exit and reenter the insert mode. It also
allows you to adjust the insertion point if you accidentally typed the wrong
line number after the insert command.
The control-C and control-W commands are also complementary. Rather than swap
the next or previous line with the current line, the control-C and control-W
commands simply list the next or previous line and then delete it.
Control-C lists and deletes the next line; control-W lists and deletes the
previous line.
The control-W command turns out to be the most useful of the intraline
editing commands. If you make a mistake (one which is syntactically correct)
while entering a line of text at the keyboard and you've already pressed
return, you can reedit this invalid line by pressing control-W as the first
character of the next line.
The control-C command lists and then deletes the following line in the file.
The control-C command is useful when you want to insert a few lines and then
modify a couple of lines that follow the lines you've inserted.
THE BUILT-IN CALCULATOR AND REFERENCE TABLES
The built in hexadecimal calculator is probably the most-often used "new"
feature in the ALE program. By pressing the ESC (escape) key twice, you open
up the calculator mode. Note that the calculator can be turned on at any
point except in the middle of a list operation or when the FIND & REPLACE
command prompts you for a YES/NO/QUIT reply. At any other time you can enter
the calculator by double-striking the ESC key. In particular, you can enter
the calculator mode even in the middle of a input line while in the insert
mode. When you turn off the calculator, the screen will be restored to the
display it contained before the calculator was turned on and you can
continue any input you were entering when you turned the calculator on.
The ALE hex calculator operates in one of two modes: decimal or hexadecimal.
If the number in the display is prefaced by a dollar sign ("$"), then the
calculator if operating in the hexadecimal mode. If the number in the
display contains no such prefix, then the calculator is operating in the
decimal mode. At any point you can switch between the hex and decimal modes
using the "H" and "M" keys. Pressing "H" moves you into the hexadecimal mode
and converts the number in the display to hexadecimal; pressing "M" switches
the calculator into the decimal mode and converts the number in the display
into its decimal form.
While in the decimal mode, you can enter a value into the calculator using
the 0I9 keys on the keyboard. In the hexadecimal mode the 0I9 and AIF keys
are active. In the decimal mode, the AIF keys are ignored. The calculator
supports two byte arithmetic. If you attempt to enter a value larger than
$FFFF in hex mode, only the last four digits will be retained. In the
decimal mode, entering a value between 32,767 and 65,535 will produce a
negative number which is the two's complement representation of the number.
Entering a number greater than 65,535 produces a value which is MOD 65,536
that is consequently displayed as a signed two's complement number. Moral of
the story-- while operating in decimal mode, keep your decimal numbers below
32,768.
The calculator supports fifteen different functions. Each function is
executed by pressing a single key on the Apple's keyboard. The "H" and "M"
commands you've already seen, the remaining commands are:
addition +
subtraction -
multiplication *
division /
modulo or remainder %
logical AND &
logical OR |
logical exclusive-OR ^
shift left < or ,
shift right > or .
logical NOT ~
sign reversal S
clear the calculator L
Except for the last five operators and "H" and "M", all of these operators are
binary operators which operate on the number in the display and the next
number entered. A pending operation can be completed by pressing "=" or
return. The shift left and right, logical NOT, sign reversal, clear the
calculator, "H" and "M" operators are unary and operate directly on the value
in the display.
While in the calculator mode, pressing "T", "Q", "P", or "O" will display
one of the reference charts available in ALE. Pressing "T" will display an
ASCII character set chart ("A" can be used to toggle between standard and
alternate character sets on an Apple //e or Apple //c); pressing "Q" will
display a list of the ANIX entry point addresses; pressing "O" displays the
ANIX CHARIO subroutine opcodes; and pressing "P" displays the values for the
ProDOS opcodes. While the ProDOS opcodes are displayed, you can press the
letter to the left of any particular ProDOS function and ALE will display the
parameter list for that function. You can return back to the calculator mode
by pressing ESC key. Likewise, you can return from the calculator back to
ALE by pressing the ESC key.
ALE's built-in calculator and reference charts are extremely valuable tools
in the ALE program. We're sure you'll find them quite indispensable once you
get used to them.
THE NEW LISA MONITOR PROGRAM
NOTE: This program is not available to LISA.64K users. Use the Apple monitor
instead. Since the Apple monitor is not particularly compatible with ANIX,
you should only operate it in the 40 column mode. First of all, the LISA
monitor is not particularly compatible with the Apple monitor(s). The LISA
monitor is not a stand-alone terminal program, it expects ANIX v2.1 to provide
all of the console and device related operations.
Furthermore, the LISA v3.2 monitor only maintains the most-often called
entry points in the monitor, and these entry points are converted to ANIX
calls. These entry points are supported only for the benefit of peripheral
cards which insist on calling routines in the Apple monitor, they are not to
be called by your assembly language subroutines. Call the equivalent ANIX
routine instead!
By removing most of the code dedicated to I/O functions in the Apple monitor
program, enough space was freed to allow several important extensions to the
debugger/monitor portion of the monitor. In addition to these extensions, an
ANIX interface is provided that allows you to make ANIX calls while the
monitor is switched into memory in the auxiliary language card bank on a 128K
Apple //e or Apple //c (normally you could not call ANIX while the auxiliary
language card bank is switched in because the stack and zero pages are also
switched).
Since the new LISA monitor program calls ANIX to perform all of its I/O, it
automatically works with any console driver connected to ANIX. If an
eighty-column (or greater) console driver is attached to ANIX, the monitor
program will automatically display sixteen bytes across the screen when
dumping memory (rather than eight bytes supported on the forty-column
display). So if you're operating in an eighty-column mode, you'll be able to
dump twice as much memory as before.
The first new command command in the LISA v3.2 monitor is a generalized
memory fill command. The syntax for the memory fill command is:
adrs1.adrs2:byte1 {byte2...byten}
Note the similarity between this command and the normal memory change
command. The fill command fills all of the memory locations from adrs1 to
adrs2 with the data following the colon. If there is a single byte following
the colon, that byte is repeatedly stored into the specified memory range.
If there are several byte values after the colon, the fill command circulates
through these values as needed.
ASCII strings as well as hexadecimal values are allowed in the data field.
Examples:
800.900:0 Same as 800.900Z in old LISA monitor.
800.17FF:FF
1000.17FF:"hello there"
800.FFF:0 "ABC" 55 35 "DEF" 20 'GH'
Another really useful addition to the LISA v3.2 monitor is the search command.
This command lets you search though memory for the first occurrence of a
string of bytes. The syntax for the command is:
adrs1.adrs2=byte1 {byte2...byten}
The search command searches, within the specified memory range, for the
first occurrence of the data string which follows the equal sign. Like the
memory fill command, the search command accepts hexadecimal data, ASCII data,
or any mixture of the data in the data field. For example, the following
command searches for the zero-terminated string "Hello there" in the memory
range 800.8FFF:
800.8FFF="Hello there"00
The search command will print the address of the first occurrence of the
string within the memory range specified (providing the string is present in
this range).
LISA V3.2 ERROR MESSAGE DESCRIPTIONS
Edit Time Errors:
BAD CHARACTER IN SYMBOL Illegal character in symbol.
ILLEGAL MNEMONIC Mnemonic is not a valid LISA v3.x mnemonic.
TOO MANY LABELS IN PROGRAM More than 512 labels in this source file.
ILLEGAL LABEL Illegal character or label not allowed here.
LABEL REQUIRED HERE Equates and other pseudo-opcodes require a
label.
ILLEGAL ADDRESSING MODE Invalid addressing mode for this instruction.
ILLEGAL CHARACTER/OPERAND An illegal character was encountered in the
operand field.
BAD NUMERIC VALUE Value entered contained illegal characters or
it was out of range.
BAD STRING OR CHAR Usually a closing quote or apostrophe is
missing.
SYNTAX ERROR Catch all for general syntax errors.
BAD LOCAL LABEL REFERENCE Illegal use of a numeric local label.
MEMORY FULL Out of memory error.
ILLEGAL COMMAND Bad LISA v3.x edit command.
Assembly Time Errors:
SYMBOL TABLE FULL Assembly-time symbol table overflow.
OBJECT OVERFLOW The object code generated by the assembler was
outside the range $800...<start of textfile>.
Either your program generated too much object
code or you need to use an OBJ directive to
move the object code down to location $800.
TYPE CONFLICT Attempted to use a macro label as a variable
name.
DUPLICATE LABEL Label was previous defined in the source file.
BAD FWD REFERENCE Address expression contains a symbol which has
not been defined. Certain pseudo-opcodes req-
uire all symbols in the address expression to
be well-defined.
BAD MACRO ID/PARAMETER Either the macro name is bad (or undefined) or
one of the macro's parameters is bad.
MISSING END The end-of-file was encountered without an END
or CHN directive.
SYMBOL IS NOT LOCAL Attempted to release a local label with RLS,
but the label was not localized with a corres-
ponding LCL directive.