Re: Chris Piles Dr Kode assembler

Dr Kode was a great little assembler. Here follows the complete text of the
instructions I have with it:

DR KODE - Z80 EDITOR ASSEMBLER
PROGRAMMED BY CHRIS PILE, 1988
------------------------------



Dr Kode is a complete editor and assembler to enable you to
write machine code programs.


It's important to note that the SAVE CODE option saves the
assembled code from the last ORG address to the end, so if you
use more than one ORG in a listing, you MUST save the code by
direct BASIC commands (press SYM-A at the menu to enter BASIC).
The SAVE and LOAD LIST options save the source listing, and it's
worth emphasising that after loading a listing you MUST enter a
command "o" in the editor to restore it. NOTE WELL: In Dr Kode,
SHIFT is the OPPOSITE of normal; that is, CAPITAL LETTERS are
set and you use SHIFT to get LOWER CASE.

When you run the Dr Kode editor, you will see the Dr Kode LOGO
displayed at the top left of the screen. Underneath will be a
flashing _ (underline) cursor which is the screen position where
text is entered.



THE EDITOR
----------


Dr Kode provides a FULL-SCREEN editor, a bit like the 128K BASIC
editor. Note the old 48K Speccys and the 128's in 48K mode use
what is known as a LINE EDITOR. I'll explain the difference... A
line editor only lets you type or edit a SINGLE line at a time.
If you want to edit another line, you must first enter the one
you are typing or editing, then, and ONLY then, can you request
another line to edit or likewise begin to type a new one. A
FULL-SCREEN editor lets you list several lines on the screen and
then move the cursor all over the screen area, changing lines at
will. The lines are not entered unless you position the cursor
somewhere on the line you wish to enter, and press ENTER!


NOTE: Throughout the instructions, you will see references to
the SYMBOL SHIFT key as just SYM and the CAPS SHIFT as CAPS. You
can clear the screen at any time while you are editing by
pressing SYM and S together. Try it. You will see the screen
clear and the cursor positioned at the top left corner of the
screen.

To enter lines of source (the machine code program listing) into
Dr Kode, you type a line number in the range 1 to 65535 (or
preferably use AUTO-LINE GENERATION) THEN your line of source
text. DON'T FORGET then to press ENTER if you want to enter the
line into the source file.

If there is a line of the same number as the one you have just
entered, then the old one will be replaced with the new one,
else the new line will be entered into its numeric place in the
rest of the source text - a bit like entering a BASIC program!

Source lines are restricted to 31 characters in length. When the
cursor is at the right-hand edge of the screen, it will NOT wrap
to the next line.

NOTE: If you list text lines and delete characters and finally
end up destroying the lines, then don't worry. Providing you did
not press ENTER on any of the lines, the altered versions won't
have been entered; you can CLS and list them again!

A final note on lines: the line length of 31 characters includes
the five-character line number as it's listed , e.g. 00010. If
you use AUTO-LINE GENERATION, then a five-character number is
produced. If you choose to enter a line by typing the number
yourself, e.g. just typing 10, then, if this line of text goes
to the right-hand edge of the screen, when you come to LIST the
line again you will not see the three extreme right-hand
characters. This is because Dr Kode will list the 10 as 00010
and so you will not be able to EDIT the line properly. It will
still assemble OK, though. This is why it's better to use
AUTO-LINE GENERATION to enter lines. Dr Kode uses some single-
letter COMMANDS that are entered on a line of their own and
without a line number. The following is a list of all commands
followed by an explanation of each one...



A --------------------- ASSEMBLE
B ----------- BACK TO BASIC MENU
L (number) ---------- LIST LINES
M ---------------- MEMORY STATUS
P1 ------------------ PRINTER ON
P0 ----------------- PRINTER OFF
a (start step) AUTO LINE NUMBERS
d (start end)------ DELETE LINES
n ------------ CLEAR SOURCE TEXT
o -------------- OLD SOURCE TEXT
r (start step)-- RENUMBER SOURCE
s (text) -------- SEARCH/REPLACE
. --------- EXPRESSION EVALUATOR



Notice any commands that could prove destructive are entered in
LOWER CASE to eliminate accidental entry!

Dr Kode's editor uses some special keys which perform functions
on the SOURCE TEXT you are EDITING. These are listed below.


SYM-S ---------- CLS+HOME CURSOR
CAPS-4(INV.VID)----- TAB FORWARD
CAPS-3(TRU VID)-------- TAB BACK
CURSORS -------- CURSOR MOVEMENT
CAPS-0(DELETE)------ DELETE BACK
SYM-D ----------- DELETE FORWARD
SYM-I ------------- INSERT SPACE


ERROR MESSAGES
--------------

Any errors that you enter are reported by Dr Kode in a PSEUDO-
ENGLISH form, either immediately or later, during assembly. The
errors that can occur and their meanings, are listed next.

NOTE: If an error occurs during ASSEMBLY, Dr Kode will stop
assembling and list the line the error occurred on and also the
error, like the example below where the label "text" hasn't been
defined and Dr Kode reports thus...

00010 LD HL,text (line)

No label (report)


DR KODE'S ERRORS - AND THEIR MEANINGS
-------------------------------------

Number? -- A BAD NUMBER WAS USED
Syntax? -------- A GENERAL ERROR
OK. --------------- ASSEMBLED OK
Exists ----- LABEL ENTERED TWICE
Label? -------- THE LABEL IS BAD
No Label ------- LABEL NOT FOUND
No Room ---------- OUT OF MEMORY
Too Far ------- RELATIVE ADDRESS
OUT OF RANGE



NUMBERS AND LABELS
------------------


Dr Kode will accept numbers from 0 to 65535. Labels can be any
length, but are restricted by the maximum line length of 31
characters and cannot start with a number or the ; symbol nor
can they be on a line of their own or contain spaces or any of
the following characters...

"!_$%&'()*+-,./

Not following these rules will result in either the Syntax? or
Bad Label error when assembling.

A word about the kind of numbers Dr Kode will handle follows...


NUMBERS AND DR KODE
-------------------

Dr Kode will accept numbers in DECIMAL, HEX or BINARY up to 16
bits in length. To use DECIMAL numbers, just type them as
numbers, e.g. 12345; to use HEX numbers you must precede the
numbers with the & symbol, e.g. &A0FF; to use BINARY numbers you
must precede the numbers with the % symbol, e.g. %10101010. The
following examples are all legal ways of using numbers with Dr
Kode...


00010 SC EQU 16384
00020 LD A,%11100110
00030 LD HL,&FFEA
00040 LD BC,%11110101
00050 LD IX,2
00060 LD DE,%1010101111010111
00070 LD A,&FF


The following isn't valid. Can you see why?



00080 LD A,&F0AF

Did you get it? It was because it tried to LOAD a 16-bit number,
&F0AF, into an 8 bit register.If you had assembled this, Dr Kode
would have shown you this line and given you the Number? error!


REM STATEMENTS IN YOUR SOURCE
-----------------------------


If you want to include REMs in your source listing, then just
precede the REMarks with the ; symbol and Dr Kode will ignore
the rest of the line.


The following are both legal ways to REM some source code...

00010 ; Line completely ignored!
00020 RESET JP 0 ;This is USR 0!


ASSEMBLER PSEUDO-OPS
--------------------


You can use the usual Z80 PSEUDO-OPS in your source code. The
following are Dr Kode's legal PSEUDO-OPS:


ORG, PUT, EQU, DB, DS, DW and DM


DB, DS, DW and DM are sometimes referred to in books about
machine code as DEFB, DEFS, DEFW and DEFM respectively; Dr Kode
uses the shorter way. DB (DEFINE BYTE) is a string of 8-bit
bytes; DW (DEFINE WORD) is a string of 16-bit addresses (or
words); DS (DEFINE SPACE) is to reserve space; DM (DEFINE
MESSAGE) is a string of text. Legal examples of these are...


00010 DB 1,2,&FF,%10101110,"A
00020 DW 1,2,16384,&FFA0,
00030 DW %1010101010101010
00040 DS 1024 ;1K of blank space
00050 DM "Text" ;The end quote
;may be omitted!


When Dr Kode assembles the above lines, the relevant bytes are
entered into the code, e.g. line 10 produces the bytes...


1, 2, 255, 174 and 65.


The other three PSEUDO-OPS are:


ORG ------- The code's ORIGIN or start address
EQU ------- Defines CONSTANT labels, e.g. 00010 SCREEN EQU 16384


The above would give the label SCREEN the value 16384.


PUT ------- Assemble for elsewhere


PUT is used AFTER ORG and its purpose is to allow you to
assemble M/C at an address that it isn't practical to assemble
at, e.g. you may want to write some M/C that will "LIVE" and RUN
at address 0. Now, you can't assemble to address 0 because it's
the ROM. This is where you would use PUT, e.g.:


00010 ORG 0 ;The ROM!
00020 PUT 40000 ;Put at 40000
00030 ;Code begins here.....


In the above example, the code would be ASSEMBLED at address
40000, but would be CALCULATED for and will only RUN at, address
0. (Note some assemblers do the reverse and assemble at the ORG
address but calculate for the PUT address.)

PUT is really only useful if you write large MC programs that
are too big to fit into Dr Kode, run in screen memory or above
the start address of the DR KODE code (58535).


THE ONE-LETTER COMMANDS
-----------------------

Enter all these on a blank line with no line number:


A --- ASSEMBLES SOURCE into M/C. If no errors, OK. is printed.

B --- Returns to the BASIC menu.

L --- On its own, L LISTs SOURCE from the start. L40 will
attempt to list from line 40. If 40 does not exist, Dr Kode will
list from the next line down - just like BASIC! While LISTING,
you can press SPACE to pause. SPACE again will stop the LISTing
and ENTER continues the LISTing.

M --- Shows how SOURCE code, OBJECT code and the SYMBOL base
address lie in memory, e.g.:

TXT 25000,00000
OBJ 00000,00000
SYM 00000

TXT is your SOURCE CODE's start address and length. The start is
always 25000. OBJ is your OBJECT CODE's start address and
length. SYM is the SYMBOL TABLE's base address. OBJ and SYM are
only correct after ASSEMBLY.

P1 --- Prints screen output if you have a printer attached and
have selected your interface when initialising, e.g. P1 then L
to print out a listing.

P0 --- Turns off printer output.


a (start step) --- Auto-generates line numbers, e.g. a100 50
gives a start of 100. After entering it 150, 200 etc. (steps of
50). Just entering e.g. a100 gives line 100 then steps of 1. 'a'
alone starts at 10 then steps of 1. I recommend you always use
AUTO NUMBER generation as it's easier, and with TAB your SOURCE
is more readable. (More on TAB later).

d --- MUST be followed by two numbers separated by one or more
spaces. DELETES lines, e.g. d10 90 deletes ALL lines from 10 to
90 inclusive. If the START line is the same or greater than the
END line, you get the Number? error. You get the same if you
don't use two numbers after the d.

n --- Will NEW your SOURCE TEXT and should be used when you want
to begin entering a new program. The SOURCE isn't cleared and
providing you don't enter a line, you can bring back your SOURCE
TEXT with 'o' (see next).

o --- Brings back your SOURCE TEXT after NEW or after loading in
some saved SOURCE.

r --- Renumbers your SOURCE TEXT in steps of 10 with a start
line of 10, whereas adding one number, e.g. r100, renumbers in
steps of 10 with a start of 100. Adding two numbers, e.g. r 100,
50 gives a start of 100 and steps of 50. You cannot renumber
part of the listing; the whole is renumbered.

s --- followed by some text will SEARCH your SOURCE for the text
and display each line that it finds it on, e.g. sHELLO searches
for the word HELLO and every time it finds it, lists the line.
During the search you can hold down any key to pause; release it
to continue searching. You can also use this command to REPLACE
text. To do this you have to follow the first word with one or
more spaces and then the word you want to replace the first word
with (which must be the same length or shorter) and follow this
with g or s for GLOBAL or SELECTIVE replace.

Examples follow...


sHELLO CHRIS g


....will search your SOURCE and every time it finds HELLO will
display it and REPLACE it with CHRIS without asking you! This is
a GLOBAL search and replace.


sCHRIS HELLO s


....will search your SOURCE and each time it finds CHRIS, it will
display it and wait for your choice. Pressing ENTER would then
replaces CHRIS with HELLO and continue to search for more,
whereas pressing SPACE will NOT replace CHRIS with HELLO but
just continue to search for more. (This is a SELECTIVE search
and replace).


x --- followed by an address or expression will cause Dr Kode to
RUN code from the address or result of the expression, e.g.:


x40000


....will RUN code at address 40000. On RETurn to Dr Kode you will
see a number displayed. This number is the value of the HL pair
on RETurn to Dr Kode; you can use this to pass back values.

You can also RUN labels, e.g. xGO will RUN the code starting at
the value of label GO. Of course, you must have defined the
label GO in your SOURCE and assembled it, otherwise you get the
No Label error.


.. --- followed by a mathematical expression will cause Dr Kode
to evaluate the expression and print the result in both DECIMAL
and HEX, e.g.:


.1+1+1+1-3+&FFEF-%10101010


will display...


65350 &FF46


....a DECIMAL and HEX result. Only + and - and whole numbers are
allowed. Labels are permitted in the expression too - providing
they are defined (i.e. after assembly).



A SMALL EXAMPLE PROGRAM TO EDIT AND PLAY AROUND WITH
----------------------------------------------------


That's the descriptions over! Now we will enter a small program
using the commands as explained. First LOAD and run Dr Kode, and
select 1 at the BASIC menu to enter the editor. You'll see the
'Dr Kode' LOGO displayed and _ cursor, and are ready to enter a
program.


When starting a new program, you 'NEW' Dr Kode by typing n then
ENTER to ensure any old program lines are removed. Dr Kode sets
the CAPS LOCK because ALL m/code instructions like LD, POP etc.,
have to be entered in UPPER CASE. For LOWER CASE, hold down CAPS
SHIFT! After NEWing Dr Kode you'll see the LOGO displayed again.

Now, to begin the program, enter:


a10 10


This puts Dr Kode into AUTO LINE mode and displays the
following:



00010 _



Next, enter the program listed. After typing each line, press
ENTER and you will see the next line number displayed.

To TABULATE the text, i.e. to put it in to neat columns, use the
TAB (INVERSE VIDEO) key.


00010 ;Program FADE
00020 ;
00030 ORG 40000
00040 GO LD HL,1234
00050 LD DE,22528
00060 LD BC,768
00070 LDIR
00080 FADE LD HL,22528
00090 LD D,0
00100 FLOOP LD A,(HL)
00110 AND A
00120 JR Z,ISZERO
00130 DEC (HL)
00140 LD D,1
00150 ISZERO INC HL
00160 LD A,H
00170 CP 91
00180 JR NZ,FLOOP
00190 LD A,D
00200 AND A
00210 JR NZ,FADE
00220 RET

Once you've entered the last line, do a CLS to get out of
autoline mode (remember CLS is SYM-S). Next enter:

A

Dr Kode will assemble the source into object code, and almost
instantly you should get the OK.

I recommend you now save the listing by entering B to go back to
the BASIC menu and selecting SAVE LIST. If there should be an
error in your entry and it locks up the keyboard or resets the
computer when you run the code, you can just reload it without
having to type it all in again!

Now you can run your code by entering:

xGO

After it has run, do a CLS again (else you won't see the cursor
because the demo ends with a black screen!!).


If you want to save the OBJECT code, then enter B to return to
the BASIC menu and select SAVE CODE. NOTE: You should ONLY save
your OBJECT code after first assembling the SOURCE, so as to
make sure the code's up-to-date. You can reload and run the code
independently of Dr Kode using LOAD "name" CODE: RANDOMIZE USR
40000.

Reload the source listing at any time by selecting LOAD LIST at
the menu. When you re-enter the Dr Kode editor (or even if you
re-enter it now after saving the code), you won't be able to
edit or assemble the listing it as it is not there! Just use...

o

....to bring it back!

Now you have a small program in Dr Kode, you can experiment with
editing and things like BLOCK DELETE, RENUMBER, LIST, AUTO LINE
and SEARCH & REPLACE.



It's the best way to learn - just mess about!!



DR KODE'S TECHNICAL DETAILS
---------------------------


EDITOR --- Full-Screen editor producing tokenised source to save
memory and speed assembly. Line numbers are reduced to two bytes
and groups of spaces are reduced to one byte. Z80 opcodes are
reduced to single-byte tokens.

ASSEMBLER --- Two-pass assembler and expression evaluator
capable of evaluating DECIMAL, HEX and BINARY numbers with
addition, subtraction and labels of any length in upper and
lower case. The assembler, using optimised token tables for
speed, assembles over 9500 lines of source per minute (160 lines
a second) to ANY memory location (using PUT). During assembly,
labels are constructed in the SYMBOL table which runs down in
memory from below Dr Kode. Each label takes its own length plus
two extra bytes used in the assembler's label search routines to
optimise search times.

Chris Pile




.