======================================= 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 {,} 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 {,} 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 {,} 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 {,} 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 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 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 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 {,} '.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