Basil’s Compendium: Basic Machine Code for the ZX-81/TS1000

As the title implies, this series is designed to introduce the beginner to the basics of machine coding. The beginner in machine language that is. We must assume that you already have a working knowledge of BASIC.

As the title also implies, I will try as much as possible to relate machine code programming to the concepts of BASIC, with which you are already familiar. (I’m tempted to refer to this as Basil’s Compendium on Machine Code, but I’ll forego that conceit).

Since you’re already familiar with BASIC, you may wonder, why bother learning smother, more foreign language? The answer of course is SPEED, and more economical use of of memory, not to mention the fun of learning itself.

Think of computing as traveling in a foreign country. Machine language is the native language of the computer. If you have ever traveled abroad, then you are aware that is very convenient to have some knowledge of the local language. Although the residents of say, Barcelona (especially Barcelona!) are very courteous, and will make every effort to understand your language, you’ll get your point across a lot faster if you speak Spanish. Again, a big part of the fun of traveling is a chance to try the language.

It is the same with computers. By knowing BASIC (an intermediate language), you’re already halfway there. BASIC is akin to Pidgin, which was developed to help English- speakers to communicate with Chinese and Melanesian people (that’s your history lesson for today).

Let us use a system similar to that used by many modern language schools – we’ll learn to ‘say’ something useful, without worrying for the moment about vocabularies and the rules of the grammar. Like the beginning language student, or someone playing the violin by ear, we’ll know how to make that single statement, but we won’t be able to apply that knowledge to any other situation for some time yet. Don’t panic though, we’ll learn the rules as we go along. It’s just that you might not lose interest so fast if we teach you to do something first.

Start by keying in the rudimentary loader program shown in figure 1-1. SAVE this program. We’re going to use it several times, and it’s a better than even bet that you will damage it before you get through with this lesson.

The backbone of this machine code program is a 1 REM statement, which holds the individual instructions of the program. You won’t recognize them unless you already know the language, but they’re there just the same.

We start out with a rough draft of the statement, as shown in figure 1-2. Figure 1-2 A shows the statement itself, while figure 1-2B tells you how it’s built. The symbol ‘(GR S)’ means ‘Graphics S’ (shift 9, shift S), and so on. With the statement roughed in, proofread it by GOTO 10. You should get the read out shown in figure 1-3. If not, then EDIT and make the necessary changes.

There are some bytes of the program that can’t be easily entered from the keyboard, which for the moment we have denoted by dots, to serve as placeholders. The subprogram at line 100 will help us to fill these vacancies with the proper numbers. Enter GOTO 100, and key in the numbers given in figure 1-4. When you have finished, input Z to break with an error 2/110. Finally, proofreading via GOTO 10, should get the readout of figure 1-5. Check it carefully, and correct any mistakes. (Use CONT to see the rest of the listing.)

You’ll notice that a new column of information has been added. This column, which gives what are known as mnemonics, will not be on the display. It is given to help those of you who already know something about machine code to analyze the program. Don’t worry if it all looks like gibberish to you. All will become clear in due course.

So now that we have the program set up, what can we do with it? Well, try setting the cursor to line 150 and RAND USR 16514. LIST the program. Try it again with the cursor set on line 100. Add other lines, such as 2000 REM, 6900 REM, etc., and try lopping them off, one by one.

I call this program PROGTOP, because it sets a top on the program (similiar to ram top for the top of ram), and it can be very handy. So now you have an idea of the economy and speed of machine code. Remember, the program for all of that lopping off is in the 27 bytes of the 1 REM. Bit by bit, as you read this series, you’ll find out what’s going on in that line.

There’s one big difference between your computer and a resident of Barcelona. If you say ‘soy listo’ in a restaurant on the Ramblas, the waiter will smile and say to himself: “This turista says that he is a clever guy, but que va! He really means ‘estoy listo’ – that he’s ready.” It’s NOT the same with your computer. As in BASIC, since the computer is a literal minded creature, it does what you tell it and not what you meant. What you say is what you get. There’s a fortune waiting for the person who invents a workable DWIM (do what I mean) button. The trouble is, just as machine code is more powerful than BASIC, the significance of your mistakes is multiplied as well.

The material in this series is designed for all ZX-80(8K) through TS1500 computers (some of the listings will work on the 2068 with appropriate address changes although untested at this time). Please read ZX81 to include the entire family.

Since machine code deals directly with the CPU – Central Processing unit – the basic principles here apply to any Z80 based computer. However, access to the CPU may be different from one computer to another. You should have 16K or more of RAM in order to use the loader programs to be described, along with tape or disc equipment for SAVEing programs. I strongly urge you to use a notebook and pen to keep permanent notes. If you learn anything at all from this series, then you’re likely to find yourself consulting your notes again and again.

There are two books that I have found invaluable. One is the instruction manual that came with my ZX81, especially the few pages that list the ZX81 character set (ZX81ers beware of the graphic character typo in your manual). The other is the outstanding “Programming the Z80” by Rodney Zaks (Sybex Inc., 2344 Sixth St. Berkely, Ca. 94710). This is a scary book, because of it’s large scope. I hope however, that by the time you have finished reading this series, you’ll find Mr. Zaks’ volume comprehensible as well as comprehensive.

One other study technique is to get out all those magazine articles on machine code programming that you passed over the first time around. Read them again, in the light of what you will be learning here. Analyze the programs presented, adapt them to your own needs and improve them if you can, See you next time.

10 REM PROOFREADING THE PROGRAM
20 FOR F=16514 TO 16527
30 PRINT F;TAB 7;PEEK F;TAB 11;CHR$ PEEK F;
40 PRINT TAB 16;(F+14);TAB 23;PEEK (F+14);TAB 27;CHR$ PEEK (F+14)
50 NEXT F
60 TOP
100 REM POKEING THE VACANCIES
110 INPUT A
120 PRINT A;TAB 6;
130 LET A=A+16500
140 INPUT B
150 POKE A,B
160 PRINT PEEK A
170 GOTO 110

16514   LD BC,(16394)
16518   LD A,117
16520   INC A
16521   LD HL,16514
16524   INC HL
16525   CP(HL)
16526   JR NZ,-4
16528   INC HL
16529   LD D,(HL)
16530   PUSH HL
16531   INC HL
16532   LD E,(HL)
16533   EX DE,HL
16534   SBC HL,BC
16536   POP HL
16537   JR C,-15
16539   LD (HL),A
16540   RET