WE - ROM ACORN ATOM UTILITY ROM Watford Electronics © 1983
INTRODUCTION
WE-ROM is a set of extensions to ATOM BASIC designed to make the life
of the occasional machine-code user easier. The average user will only
need to make use of the ATOM's built in assembler to modify existing
assembler programs and to create short sequences of machine-code to
speed up BASIC operation. The former is usually to do such things as
modify purchased games software to use their own joysticks etc. Such
users find such tools as a disassembler essential. WE-ROM's tools for
modification of machine-code programs are especially easy to use,
primarily by keeping the 'assemble to' pointer set to the current
location being viewed. In addition to the machine-code aspects, WE-ROM
also provides some of the most useful extensions to ATOM BASIC. Some
examples are: high speed tape interface, two key rollover on the
keyboard, easier scanning of the keyboard from programs, and easily
expandable without recourse to assembler.
The commands
For a better understanding of the commands, try typing in the
examples given.
ABDO Abort DO loop ABD.
Use when leaving from the middle of a DO loop.
10 DO
20 ABDO; GOTO 40
30 PRINT "This will never happen"; UNTIL 0
40 PRINT "I will do this indefinitely"'
50 GOTO 10
Use of ABDO prevents BASIC giving ERROR 18 in this example.
ABFOR Abort FOR...NEXT loop A.
Use when leaving from the middle of a FOR...NEXT loop, exactly as
ABDO, preventing ERROR 111.
ABSUB Abort subroutine ABS.
This removes references to a current subroutine, so that you can
jump directly from the subroutine to any point in the main
program, rather than going back to the command after the GOSUB
which called the subroutine. Prevents BASIC error 2.
AUTO Automatic line numbering AU.
AUTO start, increment
This will generate line numbers startin gwith 'stat', and
incrementing by 'increment' each successive line. The increment
can be negative if desired. If any line number outside 0...32767
is generated the command aborts. Both 'start' and 'increment'
default to 10 if not specified.
Certain control codes have meaning within the AUTO mode:
Control A (or ESC) cancels the current line and leaves AUTO.
Control X cancels the current line and reissues the current
line number.
Control B cancels the current line and issues the _previous_
line number.
Control N cancels the current line and issues the next
line number.
BREAK Set machine-code breakpoint BR.
Used to trap the assembler 'BRK' execution (and hence BASIC
errors) displaying all processor registers and flags. Restores
text mode.
Eg. BREAK #2800;GENERATE AN ERROR
PC AC STATUS IX IY SP
C55C 53 -V-B---C 08 01 1FD
The address specified in the BREAK instruction is the address at
which 'BRK' assembler instruction is to be placed. The previous
contents of that location are saved, and restored when the BREAK
instruction is used with no address after it.
NB. BASIC rests its own 'BRK' trapping prior to each prompt
('>'), so if BREAK is used in immediate mode the RUN or LINK
etc. must be on the same line as the BREAK instruction.
Only the most recent use of BREAK can be restored.
CHAIN Load and RUN a BASIC program CH.
Used in the same way as LOAD, but RUNs the program automatically
after loading.
Unlike the use of '*RUN', this command correctly sets up 'TOP' and
the array pointers.
CURSOR Moves the cursor CU.
CURSOR horizontal position, vertical position
The cursor is moved to the desired position on the text screen.
Eg. CURSOR 13,4;PRINT "HERE I AM"
NB. The top left hand corner is 0,0.
DATA Used with READ and RESTORE DA.
This command is ignored upon execution. It contains data to be
read byt a READ statement. Each data item is spearated from
others on the same line by a comma. Numeric data can be an
expression within brackets, or a constant. If string data needs
leading spaces or commas the whole string must be enclosed within
quotes.
Eg. 1000DATA 3,(2*A+RND%5),A STRING," A STRING, WITH A ,"
NB. When DATA statements appear in your program, _NEVER_
abbreviate DO to D., otherwise statements after the D. will be
treated as data. Placing the data beyond all statements and
'RESTORE'ing to the first line of DATA relaxes this requirement.
DELETE Delete blocks of BASIC lines DE.
DELETE first line number, last line number
Deletes all lines numbered between the two specified lines
inclusive.
DISASSEMBLE Disassemble an area of memory DI.
DISASSEMBLE first address, last address
If first address is omitted contents of variable N is used.
If last address is omitted 65535 is assumed.
If no commas appear first address = last address is assumed.
If ',P' is appended to the command the disassembly listing is
appended to the current program.
If ',W' is appended to the command the listing pauses at the end
of each line. Only one of the P or W may be specified.
Eg. DISASSEMBLE #A002,#A040,W
Upon exit from disassembly, two BASIC variables are altered:
N points to the next location to be disassembled.
P points to the last location disassembled (for patching).
Eg. DISASSEMBLE #2800
2800 08 PHP
[INY
0 2800 C8 INY
DISASSEMBLE
2801 C4 0A CPY #0A
[LDA @1
0 2801 A9 01 LDA @1
DUMP Dump memory to the screen DU.
DUMP first address, last address
Parameters are entered as for DISASSEMBLE, except the ',P' has no
effect. Thus DUMP can conveniently start where DISASSEMBLE leaves
off.
Ef. DISASSEMBLE #A03C,#A03E
A03C 6C 52 00 JMP (#0052)
DUMP,#A050
A03F 4B 45 59 AC E7 52 KEY--R
A045 45 41 44 A8 54 43 EAD-TC
A04B 55 52 53 4F 52 AC URSOR-
Control codes (0...31) are typed as '.'.
Upon exit BASCI variable N contains the next address to be dumped.
EXIT Leave user defined command EX.
This command is described fully in the section 'Extending even
further'
FIND Searches programs FIND
This command lists all lines containing a particular string,
which may be enclosed in quotes.
Eg. FIND PRINT
FIND " THEN"
KBD Engages two key rollover KB.
Selects for all further input, a two key rollover/debounced input
routine.
KEY Keyboard scanner K.
KEY variable
Scans the keyboard and stores key value (ASCII) in 'variable'. If
no key is pressed 0 is returned.
KEY variable, key number
Scans the key with ASCII value 'key number' and stores in
'variable' either true (-1) or false (0), depending on whether
the key is pressed.
This command uses some non-standarad key numbers:
129 - SHIFT 135 - REPT., CTRL. and SHIFT
130 - CONTROL 136 - LOCK
131 - SHIFT and CONTROL 137 - <->
132 - REPEAT 138 - |
133 - REPEAT and SHIFT 139 - COPY
134 - REPEAT and CONTROL
MODIFY Memory modification M.
MODIFY address
Enters monitor mode with address specified, displaying:
Addess HEX contents ASCII ':' prompt
After the prompt any of the following may be entered:
- Move back one byte
"string Enter string into memory without trailing return
@char Enter 'Control' char into memory eg. @L
;basic Execute BASIC commands eg. ;DUMP
[assem Assemble into memory eg. [LDA 8
'return' Advance one byte
Anything else is taken (if possible) as two HEX digits and stored.
NB: Variable P points to the current modifable byte, so to change
the location use ';P=...'. Use ESC to leave MODIFY.
ONERROR BASIC error trapping O.
Eg. ONERROR GOTO 1000
When an error occurs within a BASIC program the statements
following the ONERROR are executed. In the example, when an error
occurs in the program, control is transferred to line 1000 with
the GOTO statement.
ONERROR OFF or the BASIC prompt will restore standard error
handling.
NB. ?0 = Error number, ?1, ?2 = Error line number.
READ Read data into variables REA.
Eg. READ A,$#2800
Standard BASIC read; copies data from DATA statements into specified variables.
An example of the use of READ is:
10RESTORE;REM VERY important!
20READ N;REM number to do
30FOR A=1 TO N
40READ B
50PRINT B
60NEXT A
70END
80DATA 5,1,2,3,4,5
NB. RESTORE _must_ be executed before the first READ.
RESTORE Set data pointer RES.
Eg. RESTORE
Subsequent searches for DATA will begin from the beginning of the
program.
Eg. RESTORE 20
Subsequent searches for DATA will start from line 20. A label can
be used instead of a line number.
TAPE Select tape speed T.
Eg. TAPE 0
Selects 300 baud
Eg. TAPE 1
Selects 1200 baud
Both routines indicate operation by placing each transferred byte
at the top right corner of the screen.
NB. When using 1200 baud, you may find a higher incidence of tape
errors. This is because there is less redundancy in the stored
information. It is therefore recommended that all important
programs are saved at 300 baud also.
Extending even further
To add a new BASIC command, select an unused text space (ie. ?18=...;
NEW). Type a line 0 containing '0REM$%command name'. Then enter a
program in BASIC to perform the desired operation. The command is
ended by using the EXIT statement.
Eg.
?18=#82;REM in screen memory
NEW; REM clean up the new text space
0REM$%HELLO
10PRINT "Hello There!"'
20EXIT
HELLO;REM Test the new command
Hello There!
>
NB. Command names must not start with a space.
Parameters can be transferred to the command, by placing them after
the command name eg. 'HELLO 3'. Parameters are read within the command
by the use of the READ statement. All parameters (there can be more
than one, separated by commas) must be READ otherwise an error will
occur upon EXIT from the command.
Eg.
?18=#82;REM select a text space
NEW; REM be tidy
0REM$%MP
5REM This command is called MP
10READ Q,$#2800;REM READ a number and a string
20IF Q<1 THEN EXIT 23;REM If printing less than once give error 23
30FOR P=1 TO Q;PRINT $#2800;NEXT P
40EXIT
MP 3,"*"
***>MP 0,"*"
ERROR 23
>MP 5,"HELLO"
HELLOHELLOHELLOHELLOHELLO>
If an expression is put after the EXIT command, the expression is
evaluated, and the calling program is given the ERROR of that value.
Labels should not be used within commands.
'RESTORE' should not be used within a command.
Variables P and Q are local to the command, so their values are
restored on EXIT.
Always leave commands via EXIT or END.
Do _NOT_ allow a command to call itself.
Commands need 19 bytes workspace at their end, so do not use any
locations below TOP+19.
All possible text spaces from #400 to #A000 are scanned for possible
commands.
A sample editing session using WE-ROM commands
Set up a program to put '*'s in the top half of the screen.
>P=#2800
[LDY @0;LDA @#2A;STA #8000,Y;INY;BNE #2804;RTS;]
0 2800 A0 00 LDY @0
0 2802 A9 2A LDA @#2A
0 2804 99 00 80 STA #8000,Y
0 2807 C8 INY
0 2808 D0 FA BNE #2804
0 280A 60 RTS
Try it out.
>LINK #2800
Check register contents after first loop.
>BREAK #2808;LINK #2800
PC AC STATUS IX IY SP
2808 2A ---B---- AF 01 1FD
Disengage breaking, and restore program.
>BREAK
We want to fill with something else...
>DISASSEMBLE #2800,,W
2800 A0 00 LDY @#00
2802 A9 2A LDA @#2A
A graphic character will do...
>[LDA @#41
0 2802 A9 41 LDA @#41
Check the rest of the program.
>DISASSEMBLE ,,W
2804 99 00 80 STA #8000,Y
2807 C8 INY
2808 D0 FA BNE #2804
280A 60 RTS
Try it out.
>LINK #2800
Changing the fill character another way...
>MODIFY #2800
2800 A0 ;
2801 00 .;
2802 A9 -;
2803 41 A:"C
2804 99 9:-
2803 43 C:2A
2804 99 9:-
2803 2A *:>
The fill character was changed twice, once to 'C' and then back to '*'.
Error codes used by your ROM
1 Invalid variable name in KEY statement.
21 Error in use of AUTO, either used within a program, or
comma not used between operands.
22 Out of DATA in a READ statement.
110 FIND used within a program.
175 Comma missing in CURSOR statement.
208 Error in DELETE command, either DELETE used within a
program, or no comma between operands, or first line to
be DELETEd is after the last.
221 Error in READ statement, READing into an invalid
variable or a string in page zero, or comma missing
within a DATA statement.
Nore: BASIC will issue an ERROR 175, if an expression is used in
place of a number as a paramter to these commands, without
placing the expression in brackets. Variables on their own need
not be parenthesised.
Memory usage by the utility ROM
The ROM uses locations #50-#7F as short term working storage.
Locations #238-#23D are used as semi-permanent storage, thus:
#238 Flag for READ =0 If 'RESTOREd'
255 If READing parameters for user command.
#239,A DATA pointer for READ.
#23B,C Location to replace stored byte for BREAK.
#23D Stored byte for BREAK.
Locations #21C,D are used by the AUTO command temporarily to
store the old vector for reading a character from the keyboard.
There is within the Utility ROM another keyboard input routine
other than that selceted by 'KBD', this is similar to that
selected by 'KBD', but editing is disabled, and editing keys
return 'ASCII' codes greater than 128 (See 'KEY' command). Select
this input routine by '?#20A=#34;?#20B=#AD'.
|