               
               =======================================
                    LISA 2.5 DOCUMENTATION FILE #3
               =======================================
               
                        WRITTEN BY: DATA CAT
               


EXPL OF COMMANDS (cont): 

PAU: PAUSE/FORCE ERROR

PAU  is ignored during passes one and two.  During pass three however,
this pseudo  will  automatically  cause  an  error  ("**ERROR:   PAUSE
ENCOUNTERED")  to occur.  At this point the programmer may A(BORT) the
assembly or C(ONTINUE) the assembly.  PAU is very useful for debugging
purposes as you don't have to watch the screen with your finger on the
space bar should you desire to  stop  the  assembly  listing  at  some
particular  section  of code.  PAU is also useful in determining where
the 4K cutoff is when you are saving obj  files.   Although  an  error
message  is  generated,  this  has  no effect on the assembly.  If the
pause error is the only error encountered then  the  assembly  can  be
considered successful. 

PAG: PAGE EJECT

PAG  will  print  a  control-L  to the listing device when encountered
during pass three.  If you are sending the listing to a  printer  with
forms  control,  your  printer should skip to top-of-form.  PAG allows
you to format your listings nicely, breaking up  subroutines  so  that
they begin on different pages. 

DCI: DEFINE CHARACTERS IMMEDIATE
     SYNTAX: DCI "any string"
     or      DCI 'any string'
DCI  is a special hybrid pseudo. In function its identical to ASC with
one exception:The last character in the string will have an order  bit
which  is  opposite  the value for the rest of the string.  That is,if
you are storing the string in memory with high order bit  on,then  the
last  character  in  the string will be stored with its high order bit
equal to zero.If the string is being stored memory with the high order
bit off, then the last character in  the  string  will  be  stored  in
memory with the high order bit one. 

Examples:
         DCI "ABCDE"     -GENERATES C1 C2 C3 C4 45
         DCI 'ABCDE'     -GENERATES 41 42 43 44 C5

INV: INVERTED CHARACTERS
     SYNTAX: INV "any string"
     or      INV 'any string'
INV takes the string which follows and outputs the characters as APPLE
inverted  (inverse)  characters.  The high order bit is always off: so
whether you use the apostrophe or quote to delimit the string is of no
consequence.  You should realize that  only  the  characters  directly
available  from  the  Apple  keyboard plus "[", "\", "_" have inverted
counterparts.  The lower case letters and several  special  characters
do  not  have  corresponding  inverted  counterparts,  and should they
appear within the INV string, garbage will be created. 

Examples:
         INV "ABCDE"     -GENERATES 01 02 03 04 05
         INV 'ABCDE'     -GENERATES 01 02 03 04 05

BLK: BLINKING CHARACTERS
     SYNTAX: BLK "any string"
     or      BLK 'any string'
BLK is the counter  to  INV.   Instead  of  generating  the  code  for
inverted  characters, BLK generates code for blinking characters.  All
restrictions mentioned for INV apply as well  to  BLK  (for  the  same
reason). 

HBY: HIGH BYTE DATA
     SYNTAX: HBY <expression> {,<expression>}
HBY is similar to ADR except only the high order byte of the following
address  expression  is  stored  in  memory.   Combined  with  BYT its
possible to break up address tables into two groups of one  byte  data
apiece  instead  of the two-byte data generated by ADR.  This allows a
very convenient method of  loading  addresses  when  using  the  index
registers. 

Examples:
  HBY $1234       -GENERATES $12
  HBY $F3         -GENERATES $00
  HBY LBL         -GENERATES H.O. BYTE OF THE ADDRESS LBL
  HBY "A"         -ANY ASCII DATA ALWAYS GENERATES $00
  HBY LBL1,LBL2,LBL3

BYT: LOW BYTE DATA
     SYNTAX BYT <expression> {,<expression>}
BYT  works  in  a manner similar to HBY except it stores the low order
address byte into memory at the current location.  BYT is also  useful
for introducing symbolic values into your programs.  For instance, $00
is often used as the "end-of-string" token.  You can define a constant
"EOS"  (for"end-of-string")and then use BYT to store the value for EOS
in memory for you.  This has two beneficial effects on  your  program.
First,  it  makes  your  program easier to read since "BYT EOS" states
exactly what the value is for whereas "HEX 00" is somewhat  ambiguous.
The  second  beneficial  feature is the fact that should you decide to
change the EOS value from zero to say ETX (ASCII end-of-text) you only
need change one line.  (the EQU statement which defines  EOS)  instead
of  having  to  go  through your program and change each occurrence of
"HEX 00" to "HEX 03"

Examples: 
  BYT $1234    -GENERATES $34
  BYT $F3      -GENERATES $F3
  BYT "A"      -GENERATES $C1 (EXTENDED ASCII FOR "A")
  BYT LBL      -GENERATES CODE CORRESPONDING TO LBL'S
                LOW ORDER ADDRESS

DFS: DEFINE STORAGE
     SYNTAX: DFX <expression> {,<expression>}
DFS reserves memory  storage  for  variables.   DFS  takes  the  first
address  expression  found in the operand field and adds this value to
both the location counter and the code counter.  This  leaves  a  wide
gap  of  memory open for use by arrays, variables, etc.  If the second
operand is not specified,  then  the  memory  space  reserved  is  not
initialized  and  contains garbage.  The second operand in the address
expression, if specified, determines the value to which memory will be
initialized.  The low-order byte of the second address expression will
be stuffed into each byte of the storage reserved by the  DFS  pseudo.
**  Note**  This  initialization is optional.  If it is not explicitly
required it should not  be  used  as  it  slows  assembly  speed  down
considerably.   If  more  than  two  expressions  are  specified,  the
remainder are ignored. 

Examples:
   LBL  DFS $1      -RESERVES ONE BYTE AT LOCATION "LBL"
   LBL1 DFS $100    -RESERVES 256 BYTES AT LOCATION "LBL1"
   LBL2 DFS 300,0   -RESERVES 300 BYTES AND INITS THEM TO ZERO

DBY: DOUBLE BYTE DATA
     SYNTAX: DBY <expression> {,<expression>}
DBY is used in a manner identical to ADR except that the address  data
generated  is  stored  in high order (H.O.) byte/low order (L.O.) byte
order instead of the normal L.O./H.O.  order. 

Examples:
         DBY $1020       -GENERATES 10 20
         DBY $1234       -GENERATES 12 34
         DBY LABEL       -GENERATES (H.O. BYTE) (L.O.BYTE)
         DBY LBL1,LBL2,LBL3

LET: LABEL REASSIGNMENT
     SYNTAX: LABEL LET <expression>
LET allows the programmer to redefine a previously  defined  (non-zero
page)  label.  This is useful for defining local labels, counter, etc.
One note of caution: LET is active on passes two and three.   EQU  and
statement  label  declarations are noted only during pass two.  If you
declare a label during pass two as a statement label or with  the  EQU
pseudo  and  then  subsequently  redefine  it  with  a LET pseudo, the
address used during pass  three  is  the  value  defined  in  the  LET
statement  regardless  of the EQU or statement label definition.  This
is due to the fact that a label defined using  the  LET  retains  that
value  until  another  LET  redefinition  (with  the same label) comes
along.  Since EQU is not active during pass three and statement  label
values  are only noted during pass two, the label will never be set to
its original value.  These problems are easily  overcome,  simply  use
the  LET  in  place  of  the  EQU  in the original definition.  If the
original definition was a statement label then substitute "LABEL LET*"
instead

TTL:TITLE
    SYNTAX: TTL "STRING"
The TTL pseudo causes an immediate page eject (via control-L/form feed
character) and then prints the title specified at the to of the  page.
Every  65 lines a page eject is issued and the title is printed at the
top of the new page. 


     SYNTAX: .IF <expression>
Conditional assembly under LISA lets you selectively assemble code for
different operating environments.   For  example,  you  could  have  a
couple  of  equates  at  the  beginning of a program which specify the
target Apple system.Labels such HASPRNTR,  HAS64K,  HASMODEM,  LCPLUS,
KBPLUS,  ETC.,  can  be  set true or false depending upon the hardware
involved.For example, LISA 48K and 64K are the same file with just one
equate  changed.  Conditional   assembly   handles   all   the   minor
details.Conditional  assembly  uses three pseudo opcodes: '.IF', '.EL'
and '.FI'.  '.IF' begins a conditional assembly  sequence.   '.IF'  is
followed   by   an  address  expression.   If  it  evaluates  to  true
(non-zero),  the  the  code  between  the   '.IF'   pseudo   and   its
corresponding  '.EL'  or  '.FI'  pseudo  is  assembled.If  the address
expression evaluates to false, then the  code  immediately  after  the
'.IF' pseudo-op will not get assembled

     SYNTAX: .EL
'.EL' terminates the '.IF' code sequence and begins the alternate code
sequence.   The  alternate  code  sequence  is  assembled  only if the
address expression  in  the  operand  field  of  the  '.IF'  pseudo-op
evaluates to false (zero).  '.EL' (and its corresponding code section)
is  optional  and  need  not  be  present  in the conditional assembly
language sequence. 

     SYNTAX: .FI
'.FI' terminates the conditional assembly language sequences.  It must
be present whether or not there is a '.EL' pseudo-op present.All  code
after  a  '.FI' will be assembled regardless of the value in the '.IF'
operand field.**Note** LISA does not supp nested IF's.  If a nested IF
is present, you will be given a nasty error  at  assembly  time.   All
IF's  must  be terminated before an END or ICL ps-op is encountered or
assembly will terminate.  To see any example of conditional  assembly,
look at the "LISA P1.L' file on the LISA master disk. 

PHS:PHASE
    SYNTAX: PHS <expression>
The  PHS  ps-op  lets  you  assemble a section of code for a different
address, yet include the code within the body of a program running  at
a  different  address.   This  feature lets you include a short driver
that runs at  location  $300,  for  example,  within  a  program  that
normally runs up at $1000.  It is the responsibility of the program at
$1000  to  move  the  program down to location $300.  Technically, PHS
loads the location counter with the address specified in  the  address
expression,  but  it  does  not  affect  the  code counter at all.  In
essence it performs an ORG without the OBJ.  the DPH must be  used  to
terminate the PHS code sequence. 

DPH- DEPHASE
     SYNTAX: DPH
DPH  is used to terminate the section of code following the PHS ps-op.
It loads the code counter into the  location  counter,  restoring  the
damage done by the PHS ps-op. 

     SYNTAX: .DA <special expression> {,<special expression>}
'.DA'  is  another hybrid ps-op.  It is a combination of the ADR,BYT,&
HBY ps-op.  It is particularly useful  with  the  SPEED/ASM  package's
CASE statement and similar routines. 

Examples:
         LBL1 .DA #CR,RETURN
         LBL2 .DA 'C',#LBL,/LBL2,LBL2
         LBL3 .DA "HELLO THERE",#0,STRADR

If  an  address  expression is prefaced with the pound sign ("#") then
the lower order byte will  be  used.   If  an  address  expression  is
prefaced  with  the slash ("/") then the high order byte will be used.
If neither a pound sign or a slash is specified, then the two bytes of
the address (in low/high format) will be stored in memory. 

GEN: GENERATE CODE LISTING
     SYNTAX: GEN
GEN(and NOG)control the output during assembly.If GEN is in effect(the
default)all object code output is sent to the display device

NOG: NO GENERATE
     SYNTAX: NOG
NOG will cause only the first three bytes to be listed to  the  output
device  during  an  assembly.This  dramatically shortens progr listing
containing strings and multiple address. 

USR: USER DEFINED PSEUDO OPCODE
     SYNTAX: USR <anything>










