______________________________________________________________________________ LISA816 v4.0g SHAREWARE version by Randall Hyde and Brian Fitzgerald (c) 1980-1987 Randall Hyde and HAL LABS all rights reserved. Note: this shareware version of LISA may be freely distributed, provided that the following files are included: LISA816 shareware assembler ANIX.SYSTEM ANIX system (LISA runs under the ANIX shell) LISA.DOC this document file DISASM816.SRC source to the disassembler SIMPLECDA.SRC source to the simple CDA After a two-week review period, you are required to either destroy any copies you have (should you decide NOT to purchase the assembler package) or send $50.00 (plus $5.00 shipping and handling) to HAL Labs 18942 Dallas Perris, CA 92370 APDA should also be carrying LISA816 in the near future, along with the ANIX package (manual, extrinsic source and ANIX shell source). The disassembler provided in this package is also SHAREWARE; if you purchase LISA816, the disassembler is included. If you wish to use the disassembler otherwise, send $15.00 to the above address (which entitles you to a disk, one update, and printed documentation). ANIX is freeware, but is (c) 1982-1987 Randall Hyde. DISASM816 is (c) 1987 HAL Labs ______________________________________________________________________________ What follows are some notes on using the LISA816 assembler. Providing an assembler as share-ware is a large task- an assembler is usually not the intuitive kind of program that a word processor or terminal emulator is. So, even though the accompanying document is 40K long (longer than the assembler!), everything is not covered. Of course not! After all, we want you to buy the assembler. However, we also want you to get a good feel for what LISA's like. Therefore, there are several programs included in the package. First, there's the source to a 65816 disassembler. Second, there's the source to a SIMPLE CDA. Each file can be LOaded into the assembler, ASMbled (to a file on disk) and run. Any simple questions may be sent online to GEnie: HAL.LABS DELPHI: HALLABS CompuServe: 72250,3226 Until you buy the assembler, we won't answer more than a few simple questions, of course. Registers users, of course, get better support. How to set up LISA816: LISA816 runs under the ANIX shell. Therefore, you must have ANIX running before you can use LISA816. Either 1) run ANIX.SYSTEM from basic (ie "-ANIX.SYSTEM") 2) make a boot disk with PRODOS and ANIX.SYSTEM Then, after you have run ANIX, from the ANIX command line, type LISA816 (assuming that the LISA816 file is in the currently prefixed directory). ANIX is a command-line interface with many useful programmer extensions; that's why LISA816 uses it (ANIX was actually developed mainly so that there would be a decent environment to run LISA in). After that, you're up and running. We hope. Have fun! ______________________________________________________________________________ Source Editing Commands LISA has a few special characters of it's own, that only have meaning in the insert mode. These special characters are used to enhance source-file editing. <> is used to exit insert mode. This command, as do all the following commands, needs to be used as the first character of an insert line. <> has the effect of moving the insertion point to before the line immediately preceding the current insertion point. The previous line is displayed (for user convenience), and the new line number displayed for insertion. <> has the effect of moving the insertion point to after the line immediately following the current insertion point. The next line is displayed (for user convenience), and the new line number displayed for insertion. If the insertion point is line N, then line N+1 becomes line N, and the new insertion point is line N+1. <> has the effect of deleting the line previous to the insertion point, and then starting insertion at that point. The deleted line is displayed (for user convenience), and the new line number displayed for insertion. This is the most useful of the four special editing commands. Typically, a line will be entered, the user will press return, and then notice an error. Using <> has the same effect as: <> M nn ... <> has the effect of deleting the next line in the source following the insertion point, and placing the insertion point following that line. The deleted line is displayed (for user convenience), and the new line number displayed for insertion. If the insertion point is line N, then line N+1 is deleted, and the new insertion point is line N (because line N+1 was deleted). Importing and Exporting Text Files LISA source files are stored in a compressed, tokenized form. This has several advantages: * files are smaller * assemblies are faster * most errors are caught at edit time, not assembly time The disadvantage, of course, is that files are not stored in a pure text format. It is, however, easy to import text from a text file, or to save a LISA file out as text, by using the READ and WRITE commands. To import text, simply use a command of the form READ nnn > by itself to exit insert mode. Exporting to a text file is just as easy, using a command of the form WRITE n1,n2 >textfile where n1..n2 is the range of lines to write to the text file named textfile. Normally, LISA writes text files with no space padding to line columns up. If you want the space padding, insert the TAB switch in the write command: WRITE -t n1,n2 >textfile and spaces will be added to pad the columns out as they would be if a LIST command were issued. READ and WRITE can also be used to move portions of code from one LISA file to another. If you have libraries that you raid routines from, or perhaps equate files that you only want certain lines from, you would use WRITE to extract the lines needed, and READ to insert them into the correct source file. LISA editor commands Note: each command may be abbreviated to the characters shown in upper case. Optional parameters are enclosed in braces, as {optionalparms}; required parameters are encased in double-brackets as, <>. <> (execute ANIX command) Parameters: output file/device. Usage: <> <> Executes the command following the <> as an ANIX intrinsic command. ANIX will report any errors that occur in the execution of the command. <> (toggle printer on/off) Parameters: none Toggles the setting of the ANIX printer device; if printer was off, printer is turned on, and vice versa. This action is the same as in the ANIX shell. - (list previous 20 lines) Parameters: none. Lists the 20 lines previous to the last line listed (by any list command). , (list next 20 lines) Parameters: none. Lists the 20 lines after the last line listed (by any list command). . (list 20 lines around current line) Parameters: none. Lists the 20 lines around to the last line listed (by any list command); ie, from -10 to +9 around the current line. ? (command help) Parameters: output file/device. Usage: ? {>outfile} Prints a short summary of all the LISA commands available; if {>outfile} is present, output is redirected to the selected file or device. Assemble (assemble source) Parameters: output file/device. Usage: Assemble {>outfile} Assemble the source file in memory; if the optional parameter {>outfile} is present, output is directed to the selected file or device. If the source file in memory ends with a CHN " <>" and not an END, the file in memory is saved out to disk as "T.." and then assembly continues with <>. BReak (break to monitor) Parameters: none. Exits from LISA into the LISA monitor. To return to LISA, use <> for a LISA warmstart (leaves file intact) or <> for a LISA coldstart (does a NEW on re-entry to LISA). COpy (copy source lines) Parameters: start line, end line, dest line. Usage: COpy <>, <>, <> Copies source lines in the range <>.. <> to a position in the file starting at <>. Note that <> must not be less than <> and <> cannot lie within the selected range <>.. <>. CPu (set CPU type) Parameters: CPU type Usage: CPu <> Set CPU type to be of type <>. CPU Type must be one of the three: 6502 65C02 65816 If <> is omitted, the current CPU type is displayed. Delete (delete source lines) Parameters: delete line 1, delete line 2. Usage: Delete <>, {delline2} Deletes source lines in the range <>.. <>. If <> is not specified, only line <> is deleted. The range must be legal - <> must not be less than <>. DS (dump symbol table) Parameters: optional file/device. Usage: DS {>outfile} Will print the symbol table from the last assembly to the standard output device. As usual, output may be directed to any ANIX device (>.P for printer, >filename for file, etc). Find (find search string) Parameters: search string. Usage: Find {searchstring} Looks for {searchstring} in the file and displays all lines it is contained in. FIND may be aborted by pressing <>. If no search string is specified, FIND will do nothing. FReplace (find and replace) Parameters: search string, replacement string. Usage: FR {searchstring} ^ {replacestring} Looks for {searchstring} in the file and replaces it with {replacestring} where-ever found. FR will prompt for replacement at each occurence of {searchstring}. FR may be aborted by pressing <>. If no search string is specified, FR will do nothing. If no replacement string is specified, FR will delete the search string if allowed. Insert (insert source lines) Parameters: insert line. Usage: Insert {insline} Starts insertion of source code lines at <>. If <> is not specified, insertion starts at the end of the file. Insert mode is exited by entering <> on a blank line. LEngth (source file stats) Parameters: optional file/device. Usage: LEngth {>outfile} Will print the statistics for the current source file in memory- length, number of symbols. List (List source lines) Parameters: list line 1, list line two, output file/device. Usage: List {line1},{line2},{>outfile} Lists source lines in the range <>.. <>. If no lines are specified, then the entire source file is listed, starting at line 1. If only the first line is specified, then only that line is listed. If one line number is given, followed by a comma, then 20 lines are listed starting at that line. If one line number is given, followed by two commas, then the entire source file is listed, starting at that number. If both numbers are given, then the source lines in that range are listed. If the optional parameter {>outfile} is used, output is re-directed to the selected file or device. LOad (load source file) Parameters: ProDOS pathname. Usage: LOad <> Used to load a LISA source file from disk. Errors- applicable ProDOS errors, memory full, not LISA vx.x file. Modify (modify source lines) Parameters: modify line 1, modify line 2. Usage: Modify <>, {modline2} Deletes source lines in the range <>.. <>, and then starts insertion at <>. Note that MODIFY is equivalent to DELETE followed by INSERT at the first line <>. MODIFY follows the same syntactic rules as DELETE. New (clear LISA workspace) Parameters: none clears the LISA workspace area in preparation for new source file creation. Read (read text file source) Parameters: insert line, read source. Usage: Read {linenum},{> Used to load a LISA source file from disk. Errors- applicable ProDOS errors. SYstem (system call) Parameters: none. Returns control to ANIX shell. To return to LISA, type RUN 303 from ANIX. TAbs (set tab stops) Parameters: opcode tab, address tab, comment tab. Usage: TAbs { <>, { <>, <>} } If no tab stops are specified, then the default tab stops of 10,19,40 are used. If TA 0 is used, the current tab stops are displayed. If three tab stops are specified - TA x,y,z - then the opcode field tab is set to x, the address field tab is set to y, and the comment field tab is set to z. These tab stops settings are saved with the file. Note that LISA tab stops are implicit, and used for output formatting - the TAB key is not used on input. TRansfer (move source lines) Parameters: start line, end line, dest line Usage: TRansfer <>, <>, <> Moves source lines in the range <>.. <> to a position in the file starting at <>. TRANSFER is subject to the same restrictions as COPY; it is the same as COPY, except that it deletes the original lines from the file. Write (write source lines) Parameters: write line 1, write line two, output file/device. Usage: Write {line1},{line2},{>outfile} Write out source lines in the range <>.. <>. No line numbers are printed for the listed source lines (as opposed to LIST, which numbers each line). If no lines are specified, then the entire source file is listed, starting at line 1. If only the first line is specified, then only that line is listed. If one line number is given, followed by a comma, then 20 lines are listed starting at that line. If one line number is given, followed by two commas, then the entire source file is listed, starting at that number. If both numbers are given, then the source lines in that range are listed. If the optional parameter {>outfile} is used, output is re-directed to the selected file or device. Note that this is the typical use of write. ______________________________________________________________________________ LISA expression syntax 13.1 Definitions. A token is the smallest meaningful unit of text in a LISA source line. The tokens of LISA are classified into special-symbols, identifiers, numbers, character-strings, and comments. A LISA source line is composed of tokens, separated by blanks (a blank is defined as the ASCII space character). The tokens are classified by type according to the field they are in- label field, opcode field, operand field, and comment field. Two adjacent tokens must be separated by one or more separators if each token is an identifier, number, or opcode. Only 1 token may be in the label, opcode, and comment fields apiece- the operand field can (and often does) contain multiple tokens. 13.1.1 Character Set and Special Symbols. The letters are the English characters A through Z, and a through z. The decimal digits are the numerals 0 through 9. The hex digits are the numerals 0 through 9, letters A through Z, and a through z. The binary digits are the numerals 0 and 1. The special-symbols are tokens having one or more fixed meanings. The following single characters are special-symbols: + - * / = < > @ # $ % ^ & | \ ( ) [ ] , ' " ~ : The following character-pairs are special-symbols: <= >= <> :A :L 13.1.2 Labels. A label is an identifier appearing in the label field or the operand field (regular and numeric), or in the opcode field (macros only). A label serves to denote a constant, variable, program address, data address, or macro call. Identifiers can be any length up to 63 characters, all of which are significant. Case is not important in identifiers. Labels can have the same spelling as an opcode, because type is determined by context. A label must begin with either a letter (regular labels), the special character {^} (numeric local labels), or the special character {_} (macro call). Regular labels can contain letters, numbers, and the special characters {.} and {_}. A regular label in the operand field can be followed by the type-coercion tokens {:A} or {:L}. Numeric local labels are {^} followed by 1 numeric digit, and are referred to as {^0}..{^9} in the label field, or {<0}..{<9} and {>0}..{>9} in the operand field. Regular labels must be unique (within their scope); numeric local labels do not have to be. 13.1.3 Opcodes. An opcode is an indentifier appearing in the opcode field. An opcode may be classified into one of three groups- instruction, pseudo-op, or a macro. The following opcodes are the legal instructions and psuedo-ops for the assembler: = .DA .DB .EL .FI .GO .IF .LA .LX .MD .ME .SA .SX .TF .WE ADC ADD ADR AND ANX ASL BBY BCC BCS BEQ BFL BIT BGE BLT BMI BNE BPL BRA BRK BRL BTR BVC BVS BYT CHN CLC CLD CLI CLV CMP CND CON COP CPU CPX CPY CSP DBY DCI DEC DEX DEY DFS DPH END EOR EPZ EQL EQU EXP FZR GEN HBY HEX ICL IF1 IF2 INC INP INX INY JML JMP JSL JSR LCL LDA LDX LDY LIB LNK LSR LST MSG MVN MVP NLC NLS NOG NOP NOX OBJ ORA ORG PAG PAU PEA PEI PER PHA PHB PHD PHK PHP PHS PHX PHY PLA PLB PLD PLP PLX PLY PSM REP RLB RLS ROL ROR RTI RTL RTS RVS SAV SBC SBT SEC SED SEG SEI SEP SET STP STR STX STY STZ SUB SWA TAD TAS TAX TAY TCD TCS TDA TDC TRB TSA TSB TSC TSX TTL TXA TXS TXY TYA TYX USR WAI WHL XBA XCE XOR ZRO Any other identifier appearing in the opcode field is assumed to be a macro- all macros must begin with the macro lead-in character {_}. Any token appearing in the opcode field that does not parse to an instruction, pseudo-op, or macro is declared illegal by the editor. 13.1.4 Operands. The operand field contains one or more expressions; each expression is separated by the special symbol {,}. An expression consists of a term, which is an label, number, character-string, or special operand, followed optionally by operator-term pairs. An operator is a special-symbol. The whole expression may be prefixed by one or more prefix operators {@}, {~} and {-}. Byte selector operators {#} (low byte), {/} (middle byte), and {^} (high byte) may also prefix the whole expression (before the normal prefix operators). Word selector operators {|}-low word and {\}-high word may also prefix the expression. Type-coercion suffixes {:A} and {:L} must follow the label they apply to, not the expression as a whole. 13.1.4.1 Expression modifiers. Expression modifiers are used to modify an entire expression, and are always the first prefix to an expression. There are five expression modifiers: # select low byte (LISA mode) or low word (APW mode 16-bit) / select middle byte ^ select high byte (LISA mode) or high word (APW mode 16-bit) | select low word (LISA mode) \ select high word (LISA mode) When used with a 65816 instruction, all the expression prefixes indicate immediate addressing mode. When used with LISA pseudo-ops, the expression prefixes select various parts of a 24-bit value for code generation. 13.1.4.2 Operators. Operators are either monadic (operator preceding expression) or dyadic (operator infix between two terms. A monadic operator is one of the following special-symbols. - @ ~ A dyadic operator is one of the following special-symbols. + - * / < > = <= >= <> & | ^ % 13.1.4.3 Labels. An label appearing in the operand field has the same format as one appearing in the label field, except for the special case of numeric local labels. A numeric local label reference in the operand field has the form {<0} to {<9} and {>0} to {>9}, where {<} and {>} indicate the direction relative to the expression of the particular local label. A label in the operand field may have a type-coercion suffix that is used to force address mode type regardless of the declared type of the label- {:A} is used to force the absolute attribute for a label, and {:L} is used to force the long attribute for a label. 13.1.4.4 Numbers. A number can be either decimal, hexadecimal, or binary. Decimal numbers use no prefix. Hexadecimal numbers use the {$} character as a prefix. Binary numbers use the {%} character as a prefix. 13.1.4.5 Character Strings. A character-string is a sequence of characters delimited by the special string delimiter characters {'} or {"}. If {'} are used, the high-order bit of each byte is set to 0; if {"} are used, the high-order bit of each byte is set to 1. Inside the delimiters, a doubled occurrence of the delimiter inserts one char of that delimiter in the string without terminating the character string. 13.1.4.5 Special Operand. A special-operand is a sequence of one or more characters representing a certain value. There are several special operand types. The current program-counter value (of the assembler) can be referenced by {*}. Macro parameters can be referenced (inside a macro) by {?0}..{?9}. Parameters to a macro are numbered by occurrence; parameters, where required, may not be omitted. 13.1.5 Comments. A comment begins with the {;} character, and optionally (first column only) with the {*} character. The comment field is the last field in the source line, and is terminated by a <> character. 13.2 Source Line Formats. Each source line is separated into 4 fields: label, opcode, operand, and comment. All four fields do not have to be present on a line, but there are some restrictions to field appearance. The general case of a LISA source line is- line # label opcode operand comment 11 PROGRAM lda SEQUENCE:L + R.OFFST ;get record byte from sequence The assembler supplies all line numbers. PROGRAM is in the label field (the first field), so it is parsed as a label. LDA is in the opcode field (the second field), so it is parsed as an opcode, and recognized as a 65816 mnemonic. SEQUENCE:L+R.OFFST is in the operand field (the third field), so it is parsed as an operand, in this case as an address expression. The remainder of the line starts with the character {;}, so it is parsed as a comment. If a colon {:} follows the token in the label field, then the line is assumed to have only the label field in it. 29 STUB: If the first character of the line is a comment char {;} or optionally {*}, the line is assumed to have only the comment field in it. 241 ; The next routine is responsible for gathering characters one at If the first character of the line is a blank (space character), then the label field is assumed to be null, not specified. 122 mvp L.BANK,R.BANK ;move var set If the line ends after the opcode field, or a comment character is found following the opcode field, then the operand field is assumed to be null, not specifed. 45 asl ;shift twice for x4 indexing 46 asl Note that in each of the above cases, the lines were listed as LISA would list them, not as they might be entered. LISA tokenizes and formats all source lines according to it's model, checking syntax at line entry time. A line entered in as: 122 draw lda #myset ;get set number for DRAW would be parsed and listed as 122 draw lda #MYSET ;get set number for DRAW and 123 jsr newplot ;call version 2 plot routine (with a leading space) would be parsed and listed as 123 jsr newplot ;call version 2 plot routine 13.3 Syntax checking. Each line is checked for syntax errors on entry. The line is broken up into tokens, and each token analyzed according to it's field position. 13.3.1 Label field. There are two types of labels. Alpha labels must start with an alphabetic character, (upper/lower case), and contain only {A}..{Z}, {a}..{z}, {0}..{9}, {.} and {_}. Labels have a maximum length of 63 characters. Alphabetic case is maintained as entered, but has no significance on assembly ("Label" is the same as "LABEL"). Labels start in the first column of a source line. Errors generated by a bad label include: Bad character in symbol Illegal label Label required here Numeric local labels start with a caret {^} and are followed by a numeric digit {0}..{9}. Only 1 digit is permitted after the {^} symbol. A space { } or a colon {:} must terminate entries in the label field. 13.3.2 Opcode field. There are two types of mnemonics that are legal in the opcode field. The first type are the 65816 opcode mnemonics and LISA pseudo-ops. The second type are macro invocations. All legal 65816 opcodes and LISA pseudo-ops are listed in section 13.1.3. Macros are identified by a special lead-in character, currently defined as {_}. Examples: 23 jsr PRINT 24 byt "Enter file name",0 25 _GETNAME where line 23 contains a 65816 mnemonic {jsr}, line 24 contains a LISA pseudo-op {byt}, and line 25 contains a macro call {_GETNAME}. Errors pertaining to the opcode field include: Illegal mnemonic Illegal label 13.3.3 Operand field. The operand field contains 1 or more expressions; the expression type depends on the mnemonic in the opcode field. Expressions can be: address expressions string expressions If the mnemonic is a 65816 opcode, the expression is embedded in address type selectors, to indicate addressing modes. Legal 65816 address expressions are: 1 iny ;implied 2 asl ;implied (accumulator) 3 ldx #dexpr ;immediate (8 bit) 4 ldy |aexpr ;immediate (16 bit) 5 asl dexpr ;direct page 6 inc aexpr ;absolute 7 and lexpr ;absolute long 8 ldy dexpr,X ;direct page indexed,X 9 dec aexpr,X ;absolute indexed,X 10 ora lexpr,X ;absolute long indexed,X 11 ldx dexpr,Y ;direct page indexed,Y 12 ora aexpr,Y ;absolute indexed,Y 13 sbc (dexpr) ;direct page indirect 14 jmp (aexpr) ;absolute indirect 15 adc (dexpr,X) ;direct page indexed indirect 16 jsr (aexpr,X) ;absolute indexed indirect 17 cmp (dexpr),Y ;direct page indirect indexed 18 eor [dexpr] ;direct page indirect long 19 jsl [aexpr] ;absolute indirect long 20 sbc [dexpr],Y ;DP indirect long indexed 21 and dexpr,S ;stack relative 22 sta (dexpr,S),Y ;stack relative indirect index 23 mvn bexpr,bexpr ;block move 24 bcs rexpr ;program counter relative 25 brl rlexpr ;program counter relative long where epxr can be any legal expression that evaluates to an address. Dexpr must evaluate to a 8-bit (direct page) address. Aexpr must evaluate to a 16-bit (absolute) address. Lexpr must evaluate to a 24-bit long address. Bexpr evaluates to a 8-bit bank number. In each case, unique special-symbols provide address type information; the individual addressing types cause unique opcodes for each instruction to be assembled. If the mnemonic is a LISA pseudo-op, various combinations of address and/or string expressions are permitted. Each expression is separated by a {,} delimiter. 26 adr aexpr,aexpr,aexpr ;16-bit addresses 27 byt "string",expr,'string' ;byte data declaration. 28 .da aexpr,#aexpr,/aexp,\aexpr ;address and byte data Address expressions consist of identifiers and constants combined with operators. An expression is of the form {modifier} {prefix} term {operator-term} {operator-term} . . . There are 5 expression modifiers: # use low byte (LISA mode) or low byte/word (APW mode) of expression / use mid byte (LISA mode) of expression ^ use high byte (LISA mode) or high byte/word (APW mode) of expression | use low word of expression \ use high word of expression There are 3 prefix operators. @expr at-operator. evaluates to {PC-expr}, where PC is the value of the assembler program counter at the start of the instruction line -expr negate-operator. evaluates to {0-expr} ~expr not-operator. evaluates to {$FFFFFF EOR expr}. There are 10 types of terms. identifier statement label or equate label (from EPZ, EQU, EQL etc). The value of the label is used. 354 decimal number (no prefix character). $3B hexadecimal number. %10011 binary number. * value of PC counter (of assembler) ?0..?9 macro parameter value (only inside macro). select one of the 10 possible macro parameters passed to macro invocation. ?# number of macro parameters passed. ?:expr evaluate expr; result must be 0..9 and is used to select one of the 10 possible macro parameters. >0..>9 local label reference in forward direction. >0 refers to next ^0 local label in forward direction, etc. The value of the local label is used. <0..<9 local label reference in backward direction. <0 refers to next ^0 local label in backward direction, etc. The value of the local label is used. There are 14 infix operators + addition - subtraction * multiplication / division % modulo & bitwise AND | bitwise OR ^ bitwise EOR = logical EQUALS < logical LESS THAN > logical GREATER THAN <= logical LESS THAN OR EQUAL >= logical GREATER THAN OR EQUAL <> logical NOT EQUAL String expressions consist of a string delimiter {'} or {"}, followed by some ASCII characters, and ending with the same string delimiter {'} or {"}. The {'} string delimiter sets bit 7 (the MSB) of each byte to 0; the {"} string delimiter sets bit 7 of each byte to 1. To imbed the delimiter char inside a string, double it. 'A string with bit 7 clear' "another with bit 7 set" 'one with ''an apostrophe'' inside it' "a last ""quote"" to remember" ______________________________________________________________________________ Using the LISA calculator Built in to the LISA assembler is a programmer's calculator that will do decimal and hexadecimal math to 224-1 (3 hexadecimal bytes, the range of addresses in the 65816); basic 4-functions (+ - * /), boolean operations (AND OR NOT), negation, left and right shifts, hex to decimal and vice versa. It also has help screens for ASCII characters, ProDOS 8/ProDOS 16 equates, and ANIX and CHARIO equates (for programmers writing programs to run under the ANIX shell. To access the calculator, press <> <> at any place where LISA is waiting for a line of input (even in the middle of entering a line of text). That is, press the ESC key, and then press it again. NOTE: there is a reason why you must push ESC twice to get into the calculator. Pressing ESC in ANIX tells it to return the next keypress unchanged; this is the only way to return all control characters (except RETURN and CTRL-@), since the normal response to some control characters is as screen editing functions. So, pressing ESC twice has the effect of returning one ESC char (which is ASCII $1B or $9B) to the LISA input routine. Once in the calculator, the line editing characters are not needed, so only one ESC is necessary until you return to LISA. The calculator screen should pop up, overlaid on your screen. Don't worry; since it's a pop-up window, it will restore the screen when you exit. The calculator looks like this: _____________ ! | _________ | ESC: quit ! | | | | T: ASCII codes ! | | 0 | | Q: ANIX equates ! | |_________| | P: PRODOS equates ! | | O: CHARIO opcodes ! | < > H M S | ! | & | ^ ~ | H: HEX mode ! | + | M: DECIMAL mode ! | C D E F - | L: clear calculator ! | 8 9 A B * | S: change sign ! | 4 5 6 7 / | &: AND ^: EOR ! | 0 1 2 3 % | |: OR ~: NOT ! | = | <: left shift ! |_____________| >: right shift ! -------------------------------------- Pressing ESC when the calculator is showing will return you back to what you were doing before you entered the calculator. So, you could be in the middle of entering a source line and want to calculate a constant before entry. Pressing ESC twice gets you into the calculator, you do the calculation, note the result, press ESC again to return to line entry, and enter in the calculated constant. The calculator is fairly self-explanatory. It is a regular infix calculator (TI style rather than HP style); so you enter number then operator then number, etc. The RETURN key doubles as the "=" key, for ease of use (most people are well accustomed to hitting RETURN after data entry, much more so than "="). Also, once you've hit return, all is not lost. You can keep on with operator and number pairs after that. The calculator will also retain the value in the display between calls to it. However, if you do an assembly, the accumulator number will be lost. HEX, DECIMAL, SIGN, and NOT operations are instantaneous; they affect the accumulator value only, and do not upset pending calculations. In the upper right-hand corner of the calculator are some prompts for some important help screens. First of all is the ubiquitous ASCII chart. This comes in handy every once in a while (although LISA does handle character constants well, it helps to know what the actual values are if you're doing anything the slightest bit tricky or innovative). Just hit a "T", and the ASCII chart pops up. Press ESC to return back to the main calculator display. Second, there is a help screen for ANIX equates. Pressing "Q" will bring up the ANIX equates screen. This comes in handy when you are writing programs that will execute under the ANIX shell (new extrinsics, little utilities, etc), and don't want to include the master file of ANIX equates in your small program. For ANIX v2.1 running LISA816 v4.0, this will be a list of absolute equates (since this presumes you are running a //e, or IIGS in emulation mode) for JSR calls; for ANIX v3.0 running LISA816 v5.0, this will be a list of COP parameter values, since ANIX v3.0 calls are made via the COP instruction. Once again, pressing ESC will return you to the main calculator screen. Third, there is a help screen for ProDOS equates. Pressing "P" will bring up the ProDOS equates screen. This reference will not only show the ProDOS call numbers, but also the parameter list structures for each call. Once again, if you are running ANIX v2.1, this will show ProDOS 8 (which also is applicable to ProDOS 1.1.1) calls, and their parameter lists; if you are running ANIX v3.0, this wil show ProDOS 16 calls. The ProDOS equates screen will show the calls by name; pressing the letter next to the name will bring up a further screen showing the parameter list required for that call. Press ESC to exit from an individual parameter list, and ESC from the ProDOS equates screen to return back to the calculator. Finally, there is a help screen for the CHARIO calls. Pressing "O" will bring up the CHARIO equates screen. This will show you the call numbers for each CHARIO function; the call number is the parameter to CHARIO needed to invoke that function for the installed console driver. Pressing ESC will return you to the main calculator screen. ______________________________________________________________________________ LISA pseudo-ops Note: not all of these pseudo-ops are implemented in the share-ware version of LISA816 (LISA v4.0g). Specifically: HEX .DB .LA .LX .SA .SX LIB PSM LNK RLB ICL Assembly listing control: LST turns assembly listing on. NLS turns assembly listing off. GEN prints all object bytes for each source line. NOG prints at most 4 object bytes per source line. EXP turns assembly listing of macro expansion on. NOX turns assembly listing of macro expansion off. CND turns assembly listing of conditionals on. NLC turns assembly listing of conditionals off. PAG start new page in assembly listing. TTL "title" set new title at top of each assembly listing page, and start new page. SBT "sub" start new subtitle at top of each assembly listing page (but does not start new page). Conditional assembly control: .IF {expr} assembles code to next .EL or .FI if {expr} evaluates to TRUE. IF1 assembles code to next .EL or .FI during pass 1 only. IF2 assembles code to next .EL or .FI during pass 2 only. .EL assembles code to next .FI if previous .IF evaluated to FALSE. .FI endif clause for the .IF / .EL / .FI construct. WHL {expr} repeat assembly of code to .WE while {expr} evaluates to TRUE. .WE endwhile clause for the WHL / .WE construct. Macro assembly: .MD macro starts a macro definition with name macro. .ME ends macro definition. Program origin control: SEG {expr} start new SEGMENT with attributes "expr". ORG expr defines origin for program code following the ORG. OBJ expr specifies where the object code is stored in memory. PHS expr starts in-line assembly of code with new ORG address. DPH ends in-line assembly and restores to old ORG address. Labels and equates: label EPZ expr define "label" as ZERO PAGE label with value "expr". label EPD expr define label as DIRECT PAGE label (identical to EPZ) label EQU expr define label as ABSOLUTE label with value "expr". label EQL expr define label as LONG label with value "expr". label = expr define label as ABSOLUTE label with value "expr" (the "=" label is re-definable) label CON expr define label as CONSTANT label with value "expr". label SET expr define label as SET label with value "expr". FZR label define label as ZERO PAGE (needed if label used before it is defined). FDR label define label as DIRECT PAGE (identical to EPZ). FAR label define label as LONG (needed if label used before definition). INP label prompt for assembly-time definition of label. LCL label define label as local to specified section (scope ends with RLS). RLS label marks end of local label scope defined with LCL. Constants and storage: BYT expr, .. define byte constants of low-order 8 bits of each expr. HBY expr, .. define byte constants of mid-order 8 bits of each expr. BBY expr, .. define byte constants of high-order 8 bits of each expr. .DA expr, .. define byte, word, string constants. ADR expr, .. define word constants (usually addresses) low byte, then high byte. DBY expr, .. define word constants (usually addresses) high byte, then low byte. CSP expr, .. is JSR followed by byte, word, strings (same syntax as .DA) DFS expr,{e} define space of expr bytes, optionally initialized to e. HEX hexdigits define hex string of bytes. LONG expr,.. define long (and byte and word) constants String declaration: BYT "string" define string- {'} creates with bit 7=0, {"} creates with bit 7=1 DCI "string" define string as in BYT; bit 7 of last char is inverted from normal. RVS "string" define string as in BYT, but with chars generated in reverse order. STR "string" define string as in BYT, with length byte preceding string (PASCAL) ZRO "string" define string as in BYT, with $00 terminating string (C-string) Control operations: CPU type set CPU to assemble for. type = {6502, 65C02, 65816} .DB declare what bank the DBR (data bank register) is pointing to. .LA declare 16-bit ACCUMULATOR mode. .SA declare 8-bit ACCUMULATOR mode. .LX declare 16-bit INDEX mode. .SX declare 8-bit INDEX mode. END end of source. .TF "file",type declare file to which generated code is saved to, and type (type is defined in HEX). SAV "file" saves memory as binary file. ANX "cmd" send cmd to ANIX shell to be executed as an ANIX intrinsic. CHN "file" chain to next file to be assembled. ICL "file" include source file in assembly. PSM "file" include packed-sym file in assembly. LNK "objfile" include object code in link. LIB "library" extract needed object code from library in assembly. RLB "objlib" include information from Run-Time-Library in linkage. .GO expr jumps to address expr to execute a machine language routine. USR expr parses expr, and jumps to user command. MSG "string" print message to stdout during assembly PAU force assembly error ("PAU encountered") ______________________________________________________________________________ ANIX Commands The format for these commands is given in parenthesis. Unless otherwise stated, these commands are to be followed by a carriage return. INTRINSIC COMMANDS * (Asterisk) if an asterisk appears in the first column, that is, the first space, in a line processed by ANIX, then the rest of the line will be ignored. The use of this instruction may not be obvious; it is used to insert comments within an EXEC file. Brk (BRK) Transfers control to the Apple monitor at location $FF/FF65. To return to ANIX, type A000G from the monitor to do an ANIX warmstart. Catalog (CATALOG {pathname} <>) Displays the listing of a directory file. Abbreviation: "CAT". The pathname is optional; if it is present, ANIX will give the specified directory, and if it is absent, then ANIX will look for the default directory. The pathname must be of a DIR (subdirectory) type file, or a disk (a disk is indicated with ".Dn", where "n" represents a number between 1 and 8). Close (CLOSE <>) Will close any and all open ProDOS files. This command may be useful after a program bombs, in order to make sure all the programs opened by the program are closed properly, and their buffers are freed by ProDOS. Date (DATE <>) This prints the date, in the format "mm/dd/yy"; it will, that is, if you have a ProDOS compatible clock installed. (always the case on a IIgs). Otherwise, this command will print the last date specified with the SETDATE command; and if the SETDATE command has not been used, then "-NO DATE" will be printed. Delete (DELETE <> <>) This will erase a file from a disk; the pathname is not optional for this command. It will not erase a file if its "D" attribute flag is turned off (if you don't know what an attribute flag is, wait for the latter part of this section), so it will have to be unlocked before it may be deleted. NOTE: When deleting a subdirectory, it must be empty before the DELETE command will work on it. Exec (EXEC <> <>) The EXEC command is used to redirect input from a textfile rather than a keyboard; the pathname is not optional, and must be the name of a TXT type file, a sequential text file. When the EXEC command is executed, ANIX then begins looking for ANIX commands from the named textfile rather than the keyboard. Load (LOAD <> {hex address} <>) Loads a BIN or SYS file from disk into memory; a pathname is required, but the hex address is optional. If the optional hex address is not present, then the file is loaded at the location from which it was saved. Example: LOAD SHORT.PROGRAM Lock (LOCK {-N -R -W -D} <> <>) This command and the Unlock command are closely associated, and they share the same syntax. The Lock command will set any or all of four attribute flags: the N (rename) flag, the R (read) flag, the W (write) flag, and the D (Delete) flag. The N (rename) flag, upon being set, will thereafter prevent the given file from being renamed, until the N flag for the file is Unlocked. The R (read) flag will stop anyone from reading a file which isn't meant to be touched. The W (write) flag will prevent someone actually saving a new version of a program with the same name of a version you wish to preserve. Finally, the D (delete) flag will stop the deletion of a file. Any of these flags, once locked, may be reset, using the Unlock command. Online (ONLINE <>) Lists all the volumes currently on-line The result will be a line for each volume of this form: s/d volume-name In these lines, "s" is the slot number, "d" is the drive number, and volume-name is the name of the volume in the specified slot and drive. Prefix (PREFIX {pathname} <>) The pathname is optional. See the discussion of pathnames and prefixes following this listing for an explanation of this command. Rename (RENAME <>, <> <>) Changes the name of a file in a directory. The pathnames are not optional, and they must be the same, except for the ending filenames. Examples: Rename /directoryname1/subdirectoryname2/thisprogram, /directoryname1/subdirectoryname2/thatprogram. Rename Yourfile,Myfile Run (RUN <> {parms} <>) Runs (calls) the assembly language program at the hex address named; the hex address is required. The optional parameters are for the use of the assembly language program. Save (SAVE <> <> <> <>) This is for saving out an object file. The hex address and length must be included. Syssave (SYSSAVE <> <> <> <>) This is the same as the Save command above, except that it saves a SYS type file rather than a BIN type file. Time (TIME <>) Prints the time, assuming there is a ProDOS compatible clock present. If there is no clock, then this command prints the last time set by the extrinsic SETTIME command, or 00:00 if SETTIME has never been used. Unlock See LOCK.