Commodore VIC-20 User manual

PROGRAMMER’S
AID CARTRIDGE
Cartouche d’instructions
pour le programmeur

The information in this manual has been
reviewed and is believed to be entirely reliable.
No responsibility, however, is assumed for
inaccuracies. The material in this manual is for
information purposes only, and is subject to
change without notice.
Retyped and redrawn in 2006 for your
enjoyment and for future generations by
François Léveillé. ’-)

iii
PROGRAMMER’S AID
USER MANUAL
TABLE OF CONTENTS
Section One – Introduction to the VIC 20 Programmer’s Aid Cartridge
1.1 Introduction............................................................................................................................. 1
1.2 The PROGRAMMER’S AID Manual..................................................................................... 1
1.3 Starting PROGRAMMER’S AID............................................................................................ 1
1.4 PROGRAMMER’S AID Commands ..................................................................................... 2
1.5 Entering Commands.............................................................................................................. 2
1.6 Indication of Errors ................................................................................................................. 2
Section Two –The Commands of Programmer's Aid
2.1 Introduction............................................................................................................................. 3
2.2 Function Keys ........................................................................................................................ 3
2.3 PROGRAM and EDIT Modes ............................................................................................... 3
2.3.1 PROGRAM MODE ................................................................................................................ 3
2.3.2 EDIT MODE ........................................................................................................................... 3
2.4 AID Commands...................................................................................................................... 4
2.4.1 CONVENTIONS .................................................................................................................... 4
2.4.2 AUTO...................................................................................................................................... 4
2.4.3 RENUMBER .......................................................................................................................... 4
2.4.4 DELETE ................................................................................................................................. 5
2.4.5 FIND ....................................................................................................................................... 5
2.4.6 CHANGE................................................................................................................................ 6
2.4.7 EDIT........................................................................................................................................ 6
2.4.8 KEY......................................................................................................................................... 6
2.4.9 ADDING CARRIAGE RETURNS ......................................................................................... 7
2.4.10 HELP ...................................................................................................................................... 7
2.4.11 DUMP..................................................................................................................................... 7
2.4.12 TRACE ................................................................................................................................... 8
2.4.13 STEP ...................................................................................................................................... 8
2.4.14 OFF......................................................................................................................................... 9
2.4.15 PROG..................................................................................................................................... 9
2.4.16 MERGE .................................................................................................................................. 9
2.4.17 KILL ...................................................................................................................................... 10
2.5 Special Editing Functions .................................................................................................... 10
Section Three –Using Programmer's Aid as a Tool
3.1 Introduction........................................................................................................................... 11
3.2 The BASIC Program............................................................................................................ 11
3.3 The Procedure ..................................................................................................................... 11
3.4 Entering the Program...........................................................................................................11
3.5 Locating the Error................................................................................................................. 13
3.6 Summary.............................................................................................................................. 14

iv
TABLE OF FIGURES
Figure Title
2-1 A Trace Display....................................................................................................................8
2-2 The Screen During Single-step...........................................................................................9
3-1 The First Error....................................................................................................................12
3-2 The First Error Highlighted ................................................................................................13
3-3 Dump of Variables .............................................................................................................13

1
SECTION ONE
INTRODUCTION TO VIC 20
PROGRAMMER’S AID CARTRIDGE
1.1 Introduction
The VIC 20 PROGRAMMER’S AID CARTRIDGE
has been designed to help both new and
experienced BASIC programmers to write, edit
and debug programs quickly and easily. This is
achieved by the AID commands which are
automatically incorporated into the VIC
operating system when the cartridge is inserted.
The cartridge also assigns some of the AID
commands and some BASIC keywords to the
function keys thus giving the programmer his
own shorthand notation during program writing.
This, together with the facility for the programmer
to assign his own functions to these keys, make
PROGRAMMER’S AID an invaluable program-
ming accessory.
This manual does not attempt to teach BASIC
programming on the VIC. If you have no
knowledge of BASIC programming, please
refer to one of the following:
VIC 20 User Manual (supplied with your
computer).
An Introduction to BASIC Parts 1 and 2 by
Andrew Colin (part of the VIC learning series).
1.2 The PROGRAMMER’S AID
Manual
This manual is divided into three parts as
outlined below:
SECTION ONE – INTRODUCTION TO
PROGRAMMER’S AID
This section outlines PROGRAMMER’S AID in
broad terms. It also explains how to load and
start PROGRAMMER’S AID. The conventions
used by this manual in describing the format of
each PROGRAMMER’S AID commands are
also included.
SECTION TWO – THE COMMANDS OF
PROGRAMMER’S AID
In this section, the format of each
PROGRAMMER’S AID is stated, its purpose is
given, its uses explained and an example
shown. The commands are listed in the logical
order in which they might be used when writing
a BASIC program such as the one included in
Section Three of this manual.
SECTION THREE – USING PROGRAMMER’S
AID AS A TOOL
This section illustrates the speed and
efficiency of using PROGRAMMER’S AID when
programming in VIC BASIC. It demonstrates
how some of the cartridge’s attributes were used
to write, edit and debug a simple program.
1.3 Starting PROGRAMMER’S AID
The PROGRAMMER’S AID CARTRIDGE must
always be inserted or removed from the VIC
with the power off. The cartridge is inserted into
the expansion port on your VIC with the label
facing up. (See your VIC 20 User Guide.)
If a VIC 1010 Memory Expansion Board is in
use, this must also be turned off. The VIC 20
PROGRAMMER’S AID CARTRIDGE may be
used with VIC 1212 VIC Machine Code Monitor
and/or VIC 1211A Super Expander Cartridges.
It may also be used with expansion RAM in the
VIC 1010 Memory Expansion Board. Please
note, however, that some operations may
conflict if changing from one cartridge to
another. Therefore it is recommended that the
VIC be turned off to effect a good “switch”.
To begin using PROGRAMMER’S AID type:
SYS 28681 or SYS 7 * 40/ 96 + 9 and press the
RETURN key.
Your VIC will display: –
-- PROGRAMMER’S AID --
READY
All the PROGRAMMER’S AID commands are
now included in the operating system of your
VIC and may be used at any time like any other
BASIC command.
When PROGRAMMER’S AID is started, the
VIC is automatically in PROGRAM mode which
means that the four function keys on the right of
the VIC keyboard have been assigned
programming commands such as GOTO,
CHR$( and GOSUB. (See Section 2.3.1) The

2
alternative to PROGRAM mode is EDIT mode
which assigns edit commands to these same
keys. (See Section 2.3.2.)
There are twelve AID commands available in
each mode. Each of the function keys may be
pressed on its own, with the SHIFT key held
down or with the CTRL key held down. When the
key is pressed, one of 12 preassigned functions
is displayed on the screen. Sections 2.3.1 and 2
describe the function keys and the two modes of
PROGRAMMER’S AID in more detail. If he
wishes, the programmer may assign his own
values to these keys, i.e. different from the
values generated by the PROGRAMMER’S AID
CARTRIDGE. (See section 2.4.8.)
1.4 PROGRAMMER’S AID
Commands
The following is a list of AID commands which
are added to your VIC operating system by the
PROGRAMMER’S AID CARTRIDGE:
Commands used when debugging and
executing programs:
HELP, TRACE, STEP, OFF, DUMP
Commands for assigning the function keys:
KEY, EDIT, PROG, KILL
These commands can only be entered into
the VIC in DIRECT mode, i.e. they cannot be
incorporated into the body of the program.
PROGRAMMER’S AID also gives you six
special program editing functions which can
be used by holding the CTRL key down and
pressing a letter on the keyboard. CTRL and U
for example will erase all the characters on the
line where the cursor is located when the
command was executed. The six special
program editing functions are detailed in
Section 2.5
1.5 Entering Commands
All the commands in PROGRAMMER’S AID
are executed by first typing the command and
then pressing the RETURN key. Some BASIC
commands assigned to the function keys have
a built in RETURN and the command is executed
simply by pressing the key. These commands are
RUN, EDIT, RETURN, TRACE, STEP and PROG.
(See Sections 2.3.1 and 2.3.2.)
1.6 Indication of Errors
If an AID command is not spelt correctly, the
message “SYNTAX ERROR” will be displayed
to the screen. You must retype the command
using the correct spelling.
2

3
SECTION TWO
THE COMMANDS OF
PROGRAMMER’S AID
2.1 Introduction
In Section Two, the two modes of
PROGRAMMER’S AID are described. The AID
commands are listed in the order in which they
might be used when writing a BASIC program
such as the one in Section Three. The use of the
function keys is detailed and instructions are
given to enable the programmer to assign his
own values to these keys.
2.2 Function Keys
PROGRAMMER’S AID makes extensive use
of the VIC’s function keys. There are only four
function keys on the keyboard but there are
many more functions than keys.
Pressing the keys normally, you obtain
functions F1, F3, F5 and F7. Holding down the
SHIFT key and pressing these same keys, you
get functions F2, F4, F6 and F8. By holding down
the CTRL key and pressing the keys, you obtain
functions F9, F10, F11 and F12. (Note that this
last group of numbers is not printed on the
function keys.)
2.3 PROGRAM and EDIT Modes
PROGRAMMER’S AID has two modes of
operation each of which assigns different
commands to the function keys on the right of the
VIC’s keyboard. When you initialize the
PROGRAMMER’S AID CARTRIDGE, the VIC
is automatically in PROGRAM mode.
2.3.1 PROGRAM MODE
In this mode, PROGRAMMER’S AID assigns
the following BASIC keywords to the function
keys:
NOTE: The (RETURN) indicated below will
appear on the screen as a left-arrow in reverse-
field following the last character inside the
quotation marks.
KEY 1, “LIST”
KEY 2, “MID$(“
KEY 3, “RUN (RETURN)”
KEY 4, “LEFT$(“
KEY 5, “GOTO”
KEY 6, “RIGHT$(“
KEY 7, “INPUT”
KEY 8, “CHR$(“
KEY 9, “EDIT (RETURN)”
KEY 10/ , “GOSUB”
KEY 11, “RETURN (RETURN)”
KEY 12, “STR$(“
By pressing the CTRL and F1 keys together or
typing EDIT and pressing RETURN, the mode
changes to EDIT mode.
2.3.2 EDIT MODE
In this mode, the following program editing
commands are assigned to the function keys:
KEY 1, “LIST”
KEY 2, “AUTO“
KEY 3, “RUN (RETURN)”
KEY 4, “DELETE“
KEY 5, “FIND”
KEY 6, “CHANGE“
KEY 7, “TRACE (RETURN)”
KEY 8, “STEP (RETURN)“
KEY 9, “PROG (RETURN)”
KEY 10/ , “RENUMBER”
KEY 11, “MERGE”
KEY 12, “OFF (RETURN)“
NOTE: Commands in one mode can be typed in
full whilst you are in the other mode, i.e. the
PROGRAMMER’S AID modes do not limit the
commands available. They simply enable you to
use the shorthand form of one set or the other.
Here is a summary of the points to remember
about PROGRAM and EDIT modes:
1. The primary importance of both PROGRAM
and EDIT modes is to assign special commands
to the VIC’s function keys in order that you can
write, edit and debug your programs quickly and
easily.

4
2. You can type in any command in either
mode at any time.
3. After initialization of the PROGRAMMER’S
AID CARTRIDGE, the VIC is automatically in
PROGRAM mode.
4. To switch from one mode to the other, simply
press CTRL and F1 keys together. Alterna-
tively you may type PROG or EDIT and press
RETURN.
2.4 AID Commands
2.4.1 CONVENTIONS
The format of each AID command in this
manual is presented using the following notation:
1. Items written in capital letters should be typed
exactly as shown. There is no need to use the
SHIFT key to obtain capitals.
2. Those items enclosed in brackets indicate a
user-specified entry such as a range of program
lines or character string. The brackets are printed
for illustrative purposes only and should not be
typed.
3. Other symbols, such as quotation marks and
commas, must be typed exactly as shown.
4. The return key is indicated by (RETURN).
5. The start line number of a command is indi-
cated by (sln).
6. The finish line number of a command is indi-
cated by (fln).
2.4.2 AUTO
FORMAT : AUTO (sln), (interval between lines)
or AUTO
PURPOSE : To increment and display program
line numbers automatically.
After initializing the PROGRAMMER’S AID
CARTRIDGE, the use of the command AUTO
without specifying either a start line number or
an interval between lines, will automatically
display line number 10/ 0/. A line number 10/ larger
than the preceding one will be displayed each
time you type in a line of BASIC code and press
RETURN. Alternatively, you may use AUTO to
specify your own start line number and increment.
AUTO will display the line number following
your last program entry regardless of whether
or not you deleted any program lines from
memory during the editing of your program. You
may if you wish use AUTO (specifying the next
sequential line number of your program as the
start line number) to bridge the gap in line
numbers thus created. You may also use the
RENUMBER command (see Section 2.4.3) to
create a wholely sequential program listing.
If RETURN is pressed immediately following
the display of a line number, the AUTO command
will be canceled.
NOTE: If you use NEW to erase an existing
program from memory, you must specify the start
line number again with the AUTO command.
EXAMPLE : When you first start up your VIC
with PROGRAMMER’S AID
inserted, to display program line
numbers automatically
beginning at line 10/0/ in intervals
of 10/ lines:
COMMAND : AUTO (RETURN)
DISPLAY : 10/ 0/
TYPE : PRINT (RETURN)
DISPLAY : 10/ 0/ PRINT
110/
RESULT : Each time you enter a line of code
and press RETURN, a line
number 10/ larger than the
previous line number will be
displayed to the screen.
EXAMPLE : To display program lines numbers
automatically beginning at line
50/ in intervals of 5 lines:
COMMAND : AUTO 50/ ,5 (RETURN)
DISPLAY : 50/
TYPE : PRINT (RETURN)
RESULT: 50/ PRINT
55
2.4.3 RENUMBER
FORMAT : RENUMBER (sln), (interval between
lines)
PURPOSE : To automatically renumber all
program lines and all GOTO and
GOSUB entries.
RENUMBER will automatically change all of
the line numbers in your program so that the
program listing then begins at the start-line you
specify and all subsequent line numbers will be
incremented by the interval that you have
defined. RENUMBER will also change the
destination line numbers of all GOTO and
GOSUB entries so that they match the newly-
numbered program lines. This command is
especially valuable if you need space in the
program to insert more code.
EXAMPLE : To renumber all the program
lines and the GOTO entry of the
following program:
10/ 0/ REM RENUMBER COMMAND
110/ PRINT “HELLO I’M VIC”
120/ FOR L = 1 TO 10/ 0/ 0/

5
121 NEXT
130/ PRINT “(SHIFT/CLR/HOME)”:GOTO 110/
COMMAND : RENUMBER 20/ 0/ ,3 (RETURN)
TYPE : LIST (RETURN)
DISPLAY : 20/ 0/ REM RENUMBER
COMMAND
20/ 3 PRINT “HELLO I’M VIC”
20/ 6 FOR L = 1 TO 10/ 0/ 0/
20/ 9 NEXT
212 PRINT“(SHIFT/CLR/HOME)”:
GOTO 20/ 3
2.4.4 DELETE
FORMAT : DELETE (sln) – (fln)
PURPOSE : To delete program lines from VIC’s
memory.
DELETE operates on a line range in the same
way as the BASIC command LIST. The various
formats of the DELETE command are listed
below:
DELETE (ln) Deletes line (ln) only
DELETE (sln) – (fln) Deletes all lines between (sln)
and (fln)
DELETE – (fln) Deletes all lines from the start
of the program to line (fln)
DELETE (sln) – Deletes all lines from line
(sln) to the end of the
program.
EXAMPLE : To delete the first two lines from
the following program:
10/ REM DELETE COMMAND
20/ REM ONE OF THE MANY
30/ REM USEFUL VIC 20/
40/ REM PROGRAMMER’S AID
50/ REM COMMANDS
COMMAND : DELETE – 20/ (RETURN)
TYPE : LIST (RETURN)
DISPLAY : 30/ REM USEFUL VIC 20/
40/ REM PROGRAMMER’S AID
50/ REM COMMANDS
RESULT : Lines 10/ and 20/ have been
removed from the program
EXAMPLE : To delete lines 30/ and 40/ of the
same program:
COMMAND : DELETE 30/ – 40/ (RETURN)
TYPE : LIST (RETURN)
DISPLAY : 50/ REM COMMANDS
RESULT : Lines 30/ to 40/ have been removed
from the program.
2.4.5 FIND
FORMAT : FIND (BASIC code), (sln) – (fln)
or : FIND “(character string)”,(sln) – (fln)
or : FIND (character), (sln) – (fln)
PURPOSE : To search the program for a given
BASIC code or character string and
display the program line(s) where
it appears.
FIND operates on a range of lines in the same
way as a LIST command. Its various formats are
listed below:
FIND (char), – (fln) FINDs from the begin-
ning of the program to
line (fln).
FIND (char),(sln) – FINDs from line (sln) to
the end of the program.
FIND (char),(sln) – (fln) FINDs from line (sln) to
line (fln).
where (char) indicates a BASIC code, character
or character string to be located.
FIND searches for a character or a BASIC
code in a program and displays all lines that
contain that character or BASIC code except
those lines where the character code is
enclosed in quotation marks. This includes all
occurrences in REM statements. If you do not
wish to include REM statements, enter REM with
a set of quotation marks immediately following,
e.g. REM “REMARK”. In this way, items in REM
statements will only be displayed to the screen if
a search is made for a character enclosed in
quotation marks, i.e. a character string.
If a character string search is made, the FIND
command will display all the lines where the
string is contained within quotation marks.
Holding down the CTRL key will slow down
the rate at which program lines are displayed to
the screen. The STOP key will abort the FIND
command.
EXAMPLE : To find the character in the
following program:
10/ REM FIND COMMAND
20/ PRINT “ABCDEFGH VERTICALLY”
30/ A$ = “ABCDEFGH”
40/ FOR C = 1 TO 8
50/ PRINT MID$(A$,C,1)
60/ PRINT “– – – – – – – – –“
70/ NEXT C
80/ REM “CONTINUE
COMMAND : FIND C (RETURN)
DISPLAY : 10/ REM FIND COMMAND
40/ FOR C = 1 TO 8
50/ PRINT MID$(A$,C,1)
70/ NEXT C
RESULT : Every program line containing a
C will be displayed to the screen.
EXAMPLE : To FIND the character string
“ABCD” in the same program:

6
COMMAND : FIND “ABCD” (RETURN)
DISPLAY : 20/ PRINT “ABCDEFGH
VERTICALLY”
30/ A$ = “ABCDEFGH”
RESULT : Every line containing the character
string “ABCD” will be displayed
to the screen.
2.4.6 CHANGE
FORMAT : CHANGE (old code),(new code),
(sln) – (fln)
or : CHANGE (old string),(new string),
(sln) – (fln)
PURPOSE : To search for an existing BASIC
code or character string and
replace it with a new BASIC code or
character string.
If the character string to be modified is
enclosed in quotation marks, CHANGE will only
replace the matching character strings in the
program which themselves are bounded by
quotation marks. Note that in REM statements,
BASIC codes which are not enclosed in quotation
marks , for example 1∅
∅∅
∅REM PRINT, will not be
changed by the command CHANGE
PRINT,PRINT #,10/ 0/ 0/ – 20/ 0/ 0/ .
CHANGE operates on a line range in the
same way as does the BASIC command list
and its various formats are given below:
CHANGE (oc),(nc), – (fln)
Search from the beginning of the program
to line (fln) replacing (oc) with (nc).
CHANGE (oc),(nc),(sln) –
Search from line (sln) to the end of the
program replacing (oc) with (nc).
CHANGE (oc),(nc),(sln) – (fln)
Search from line (sln) to line (fln) replacing
(oc) with (nc).
where oc refers to the old BASIC code or
character string and nc refers to the new BASIC
code or character string.
EXAMPLE : To change the character string
“ABCDEFGH” to “12345678” in
the preceding program:
COMMAND : CHANGE “ABCDEFGH”,
”12345678” (RETURN)
DISPLAY : 20/ PRINT “12345678
VERTICALLY”
30/ A$ = “12345678”
RESULT : All character strings
“ABCDEFGH” will be changed
to “12345678” and each line
where the CHANGE occurs
will be displayed to the screen.
2.4.7 EDIT
FORMAT : EDIT
PURPOSE : To change from PROGRAM mode
to EDIT mode.
The EDIT command gives easy access to twelve
program editing commands which are auto-
matically assigned to the function keys when the
cartridge is inserted into your VIC. (See section
2.3.2.)
You may type the word EDIT or press the CTRL
and F1 keys to enter the EDIT mode. The function
keys are then assigned the following commands:
NOTE: (RETURN) indicates a built-in carriage
RETURN following the command. This is
displayed on the screen as a reverse-field left-
arrow. (See section 2.4.9 to add a built-in
carriage RETURN.)
KEY 1, “LIST”
KEY 2, “AUTO“
KEY 3, “RUN (RETURN)”
KEY 4, “DELETE“
KEY 5, “FIND”
KEY 6, “CHANGE“
KEY 7, “TRACE (RETURN)”
KEY 8, “STEP (RETURN)“
KEY 9, “PROG (RETURN)”
KEY 10/ ,“RENUMBER”
KEY 11,“MERGE”
KEY 12,“OFF (RETURN)“
EXAMPLE : To enter EDIT mode from
PROGRAM mode:
COMMAND : EDIT (RETURN)
DISPLAY : EDIT
RESULT : The function keys are now
assigned program editing
commands.
2.4.8 KEY
FORMAT : KEY
or : KEY number, “code”
PURPOSE : To list the commands assigned to the
function keys which will then allow
you to change their assignments.
KEY allows you to display the information
assigned to the function keys and then change
them if you wish. The function keys can represent
anything which facilitates program writing e.g.
a BASIC keyword, a graphic symbol, a number, a
character string, etc., or a combination of
these. The only restriction is that the information
assigned to any one key must be 10/ characters
long or less. By using the abbreviated form of
BASIC codes, e.g. ? for PRINT, you can
increase the amount of information you assign
to each key.