HOT Z Clinic

Last time, we looked at the details surrounding HOT-Z’s READ mode. This issue, we’ll use HOT-Z to write some machine code. The program we write will not be a masterpiece that sends shivers up your spine. Instead, it will be something short and sweet, but it will demonstrate the way you use HOT-Z to write code. What I have chosen is a machine code routine which will tell you how many bytes of free memory you have which can be used for additional Basic program lines and variables. The TS2068 already has this function built into its Basic language. This is the FREE function. When you execute the command PRINT FREE, it prints out the number of “free” bytes which are still unused. All you 2068 owners, please bear with me as we go through the examples. The intent here is to learn how to use HOT-Z, not to receive spoon-fed programs.

Load HOT-Z into your computer, and work your way to the disassembly display in READ mode as shown in the last issue. The first step in writing machine code with HOT-Z is deciding where in memory our program should be located. The object is to pick a convenient place which will not be get in the way of the Basic operating system. Machine code programs can be placed just about anywhere, but if you don’t take special precautions, the Basic operating system will not intuitively know where it is. As a result, your machine code can be erased accidentally without you even knowing about it. The Basic is like an elephant and your machine code program is an ant. You must be careful not to be trampled.

Fortunately it is very easy to set aside an area of memory and tell the Basic system to leave it alone. The time honored tradition in the TS1000 is to create a REM line in basic which contains enough blank spaces to hold your code. As you shall see, this can also be done on the 2068. When you enter a Basic REM line which contains some number of letters or spaces after the rem token, you are using the operating system itself to set aside a block of memory as a basic program line. The characters or spaces that you start with can then be changed into machine code instructions.

Another way to set aside memory for M.C. programs is to tell the computer there is less memory attached than what there really is. This technique is called “lowering RAMTOP”. Using this technique, the highest addresses are made unavailable to the Basic. As more program lines and variables consume memory, the computer will eventually reach a point beyond which nothing more can be added. It will stop with an “Out of Memory” error. In a computer with a lowered RAMTOP, the computer will run out of memory before reaching the actual top of ram. The bytes you set aside by lowering RAMTOP are safely preserved and will not be accidentally overwritten in our program, we shall choose the first option of reserving bytes: creating a REM line.

To do this, use the QUIT command to turn HOT-Z off. On the TS1000, press SHIFT and the letter “Q”. On the 2068, press Symbol Shift and the letter “Q”. The result is the same in both computers: HOT-Z is turned off and the Basic operating system is restored.

Now enter a rem line with 50 “X”‘s following the REM token. After the line is entered, the screen should look like:

1 REM XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Now we can go back into HOT-Z and change those “X”‘s into real machine code commands. If you use the TS1000, enter the command RAND USR 22528. To turn the 2068 HOT-Z back on, enter RANDOMIZE USR 24098. This puts us right back in HOT-Z’s READ mode. The next task is to use HZ to find the REM line we just entered.

This is simple on the TS1000. The owner’s manual states that all basic programs start at the address 16509 in decimal. The 2068 is a bit different in that Basic programs need not always start at the same address. Different hardware or software configurations may cause a program to start in a different position. There is, however a 2068 system variable called “PROG” which will always hold the address where the Basic program begins (see page 263 of the 2068 owner’s manual). PROG is a two byte variable at address 23635 and 23636.

In the last issue we talked about displaying a specific group of addresses by typing in a 4 digit hex address to make HOT-Z display a screenful of bytes starting at the address you type in. HOT-Z includes a very nice feature which lets you type in the starting address in decimal too. This is very useful in our case where we need to jump to decimal 16509 in the TS1000 or decimal 23635 in the 2068.

If you use the TS1000, type SHIFT and “3”. 2068 owners should press Symbol Shift and “U”. This tells HOT-Z to expect a 5 digit decimal number rather than a 4 digit hex. After pressing these keys, the top left of the screen will change (this is where it says “ADDR”) to make room for a 5 digit input.

Now you can type in an address in decimal. For the TS1000, type 16509 to make the computer show you the start of the Basic Program. For the TS2068, type 23635. This will show you the values of some of the 2068 system variables. The top two bytes will be the address of the start of the Basic program. The 2068 will show address 5C53 holding the value of 56 and the address 5C54 holding the value 68. One might deduce, therefore that the address of the Basic is 5668 hex, but that is incorrect. All computers store numbers in the exact opposite order that humans do. To the computer, a 56 followed by a 68 translates to the hex address of 6856. Now that we have looked up the address in PROG, we can make HOT-Z display this area in memory simply by typing the address in. So type: 6856. At this point, both in the TS1000 and the 2068, HOT-Z should be READING a disassembly of the start of your Basic REM line.

It doesn’t look much like a rem line does it? This is because Basic program lines are NOT machine code, they are data which is interpreted by the ROM. Since the computer is in the disassembly mode right now, it is trying to disassemble data. The result is a nonsensical display. You may recall that we covered this type of situation in the last issue. Refer to it for more details. To view the program line properly, we must go to the DATA MODE. On the 2068, press Symbol Shift and “G”. On the 1000 press Shift and “D”. Do you see the REM token and the “X”‘s which make up your program line now? The REM token should be found on the fifth line of the data display. Below it, you will find the first screenful of X’s which you typed in. You may be wondering what the top four lines of the data display represent. These are the addresses which hold the decimal values 0, 1, 52, and 0 respectively. I refer you to your computer manual–the chapter entitled “Organization of Storage”. On the TS1000 page 128 and page 255 in the 2068 book, you will find a nice chart which depicts the byte structure of a Basic program line. As the chart says, the first 2 bytes represent the line number (the HOT-Z display indicates that we must be looking at a line number 1), the second two bytes show the length of text plus the ENTER character which is always the last character of any program line. HOT-Z shows this line has a length of 52 bytes (that’s one byte for the REM token, 50 X’s, and 1 byte for the ENTER character. 1+50+1=52).

Generally, you should not try to change these first four “pointers” of the program line unless you know what you’re doing. We’ll cover that at a later date, however, I will mention that HOT-Z can put whatever values you choose into these pointers. Changing the first two bytes will change the line number when you go back to Basic and list the program. Changing the second two bytes will do all kinds of crazy things. Many of them will cause your computer to crash the instant you go back to basic. The TS1000 version of MTERM (modem software) had these bytes changed as a copy protection scheme. Pro/File Updates Vol.2 No.4 (pg.2-3) showed how to merge two smaller rem lines into 1 big one by changing these two length pointers.

For our present task, we want to find the address of the first “X” after the REM token. This is where we are going to begin writing our machine code. Before going any further write down both the hex and decimal addresses of this “X”. On the TS1000 it will be 4082 hex and 16514 decimal (does that number ring a bell?). On the TS2068 you should write down 685B hex and 26715 decimal.

Now switch back to the DISASSEMBLY MODE (SHIFT and “D” for TS1000, or Symbol Shift and “G” for TS2068) and then type the hex address you just wrote down for the first “X” of your REM line. This will clear the display of the line “pointers”. Now you are ready to put

HOT-Z into what is called the WRITE mode which is carried out by pressing SHIFT and “A” (for TS1000) or Symbol Shift and “A” (for TS2068).The top line of the display will change slightly and indicate that you have entered the WRITE mode. Immediately to the left of the mnemonic display a cursor will appear which is where a machine code command will be entered when we actually start to write it.

A new indicator called “END” appears in the upper right corner of the screen. END is a VERY important variable which both you and HOT-Z use constantly in a wide variety of ways. “END” can be defined rather crudely as the “end” of the machine code you are writing.

Or the “end” of a block of memory you are working on. It is hard to pin down the true meaning of END because at different times it represents different things. END always represents a hex address. Its value starts out at 8000 hex, but it can be changed to other values. As you learn to write machine code you will find yourself changing END (or Setting END) constantly to accomodate various tasks. Think of END as being an arbitrary end address of a block of memory. The starting address is defined by the location of the cursor. Depending on how you set END, this memory block can be large or small.

I will cover the specific uses of END as I cover specific functions HOT-Z is capable of handling. But here are a few general uses just to give you an idea of END’s purpose.

When you print out a listing of a dissassembly, HOT-Z starts Iprinting at the cursor and stops at the address specified in END.

When you SAVE or LOAD a block of data or machine code, the actual bytes processed range between CURSOR and END.

When you need to insert a machine code command between two existing commands, the END address is the last address to be bumped up when HOT-Z makes room for the new instruction.

The same is true when you delete an instruction. Only here, everything less than the END address is moved down. Values which lie beyond the END address are unchanged.

To assign new values to END, press the keys you normally use to produce the “TO” token (Shift and “4” for TS1000, Symbol Shift and “F” for TS2068). HOT-Z will respond by asking you to input a new 4 digit hex address for END. Whenever you write machine code, it is always a good idea to set END to the last byte of memory you plan to be working on. For our poposes, this means the last “X” in our REM line (40B3 for the TS1000 or 688C for the 2068). So press “TO” and change END to the address appropriate for the computer you use.

This will protect us against accidental erasures or insertions which, if END were improperly set, might mess up our program line and cause the computer to crash when we go back to Basic. Even worse, a bad END could jumble up HOT-Z itself, and we could crash instantly!

With END safely set to the last X of the REM line, here’s a good demonstration of how CURSOR and END work together to define a block of memory. HOT-Z has a “clear memory” function which sets every byte from the Write Cursor to the END address to the value of zero. This is not necessary to do before you start to write machine code, but now seems an appropriate time to show you this.

To clear a block of memory on the TS1000, press Shift and Enter while you are in the WRITE mode. This changes the cursor into the letter “F” for FUNCTION. Now press the number “0”. All bytes from CURSOR to END will change to zero.

To clear a block of memory on the TS2068, press Symbol Shift and Caps Shift, then press Symbol Shift and “7”. As in the TS1000, everything from CURSOR to END will become zero.

In both computers, this function puts you back in the READ mode so if you are writing machine code, you must go back to the WRITE mode by pressing the proper keys for your computer. If you were to quit to basic now and list your rem line which held the 50 X’s, you would find them all changed to CHRS 0 now. Try it if you don’t believe me.

If HOT-Z is in some other mode, press the appropriate keys to make your version go into the Write mode with the cursor beside the first character of the rem line (4082 for TS1000, 685B for TS2068). Be sure that END is set properly. Now you are ready to type in machine code mnemonics. Do this by simply pressing the letters and/or hex numbers used to make up the instruction. For example, the first command in the listing for the TS1000 is LD HL,(4004) so you would type an L, D, space, H, L, parenthesis, 4, 0, 0, 4, parenthesis, and then you press ENTER.

HOT-Z then converts your mnemonic command into hexcode which it displays, and drops the cursor down to the next line. Also note that the “4004” in the mnemonic column is changed to “RMTP”. This is a NAME which HOT-Z gives to the address 4004. HOT-Z has names for many of the key addresses and system variables used by the computer. In addition, it is possible to assign new names to your own addresses. When an address has a name, HOT-Z will automatically put the name into the disassembly because it holds more meaning than a plain number like “4004”. In this case, RMTP is the name given to the system variable RAMTOP which is defined in the owner’s manual as storing the address of the first byte above the Basic operating system.

Names and Naming will be covered later. For now, I’ll just say that you can use names interchangeably with the addresses they represent. You could have just as easily typed in LD HL,(RMTP) when you entered the mnemonic. HOT-Z would have assembled the command properly.

As you enter mnemonics, HOT-Z will check the syntax for you. If you do not enter the command correctly, the program will not assemble the line. Instead, the cursor will go back to the place where it lost track of what you were trying to write, and give you the chance to fix the line. Characters can be deleted by pressing the DELETE key (shift and “0”), The cursor can be moved left or right by pressing Shift and either the left or right arrow keys.

If you are typing in a mnemonic and HOT-Z refuses to accept your line no matter how you try to fix it, you can restore the line to its original mnemonic by pressing Shift and ENTER (for TS1000) or Symbol Shift and “O” (for 2068). This is very handy if you get half way into entering a mnemonic and then change your mind and decide to go back to the original.

After a line has been entered, and the cursor is located at the beginning of the next line, you can move the cursor up or down by pressing Shift and one of the arrow keys. This permits you to skip lines of code, or go back toa previous one if you should spot an error.

With these introductory remarks out of the way, try entering the remainder of the machine code. Choose the listing given for whichever computer you are using and type in the mnemonics.

LD HL,(4004)
LD DE,(401C)
SBC HL,DE
PUSH HL
POP BC
RET

LD HL,(5CBC)
LD DE,(5C65)
SBC HL,DE
PUSH HL
POP BC
RET

After you type in the last RETurn instruction and press Enter, you will be ready to go back to the READ mode, and from there, back to Basic to try your machine code out. To exit TS2068 “FREE Memory” from WRITE mode to READ mode, press just Enter when the write cursor is at the start of a mnemonic instruction. In other words, don’t type a mnemonic, type just Enter to go back to the READ mode.

From the READ mode you can quit to Basic to look at your program line. It looks quite different from the way it did when it was full of “X’s”, HOT-Z replaced them with the values representing the machine code you just typed in.

From Basic, you can SAVE your program line so it can be loaded back for some other application. You can also try running it. This, of course, is not done by typing RUN. Use of the RUN command will cause Basic to run, but not machine code. To get machine code running, you use the USR function followed by the starting address of your machine code in decimal. This is the address you wrote down way back at the start of this article. 16514 for the TS1000 and 26715 for the TS2068. So to execute this machine code on the 1000 and thereby find out how much free memory you have, enter the command, PRINT USR 16514. On the 2068, enter PRINT USR 26715. In both instances, the number of unused bytes will be printed on the screen. As more line numbers and Basic variables are added to memory, the machine code will print smaller and smaller results.

In our listing, the first command, LD HL,(RMTP) loads the HL register with the CONTENTS stored in the system variable called Ramtop. Two very similar looking mnemonics perform very different functions which you should learn early in your machine code career. These are:

LD rr,NN which loads the register with the number NN and

LD rr,(NN) which loads the register with the CONTENTS of the address NN.

The convention used in all Z80 mnemonics is to use the CONTENTS of an address whenever the address is enclosed by parentheses. If there are no parentheses surrounding the number, the number itself is loaded into the register.

Therefore, the second instruction, LD DE,(STND) loads the DE register with the CONTENTS of the system variable called Stackend.

Third, SBC HL,DE subtracts the value in DE from the value in HL and leaves the result in HL.

The fourth and fifth instructions work together to transfer this result into the BC register. PUSH HL puts the end result of the subtraction on to the stack. Then, POP BC takes it right back again and puts it into the BC register.

Finally, RET means RETURN from the subroutine. In other words, return to basic. Since the USR function is like a Gosub to machine code, and when it returns, it does so with a number equal to the BC register, you can use the Basic command PRINT USR xx to execute the machine code and print the contents of BC on the screen. Thus you see how much free memory remains. Simple, right?

The first installment of HOT-Z Clinic in the last issue generated a lot of good response. So I guess I’m on the right track. Don’t forget that you also have Ray Kingsley’s instructions. They contain much useful information albeit a tad difficult to decipher. Take a little from this column and a little from Ray. By combining bits from several sources, learning how to use HOTZ will come much more easily than when you depend solely on one source of information.