../../images/stop.gif
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'.