1 '.ov 0 .pg 1
2 '.m1 +1 .m4 +1
3 '.HE -- Penram by Roxton Baker --
4 '.fo Page #
5 '.ce 5
10 'PENRAM - A SCROLLING RAM EDITOR 
20 '
30 'Public Domain Software by Roxton Baker 
40 '56 South Rd.  Ellington, Ct. 06029 
50 '(203) 875-2483 
60 ' 
70 ' 
80 'INTRODUCTION 
90 ' 
100 'I recently needed a program that would allow me to 
110 'quickly examine large portions of RAM and easily change 
120 'what I found there, working either in ASCII or hex.  
130 'This ability is required when editing data or text (as 
140 'opposed to machine code) in memory, because with these 
150 'one has no idea at what address a particular byte may 
160 'be.  In my case I wished to scan and modify whole disk 
170 'tracks which had been read in to RAM.  Tracks never 
180 'read the same way twice so the locations in memory of 
190 'ID packs, sector boundaries, etc. are unpredictable.  
195 '
200 'The available monitors for the TRS-80 are, however, 
210 'written with the intention of editing hex machine 
220 'language programs, in which byte locations are well 
230 'defined.  These monitors require you to specify in 
240 'advance the addresses to edit, and generally allow 
250 'editing only in hex, and scanning only in one direction. 
255 '
260 'This is too clumsy when working with data.  
270 'Two-directional scanning would improve matters, but one 
280 'still must read off addresses of interest and re-enter 
290 'them under the edit command.  I greatly prefer the 
300 'Electric Pencil's editing action.  Not only does it 
310 'provide true scrolling in both directions, but its 
320 'blinking cursor can be positioned with the arrow keys 
330 'and anything typed at the cursor location replaces 
340 'what's there.  But the Pencil is not used for editing 
350 'RAM.  It works on its own text files.  
355 '
360 'PENRAM, presented here, is a machine-language utility 
370 'that provides Electric Pencil-like editing directly in 
380 'RAM.  Two-way scrolling can be done at low or high 
390 'speed and the movable edit cursor allows direct 
400 'input of hex bytes or ASCII characters (the mode can 
410 'be toggled at a keystroke).
420 '
430 'A continuous display is maintained of the edit cursor's "address" as well as it's displacement from a reference address
440 'that the user may fix.  Users of the Electric Pencil should understand that PENRAM does not allow true insertion or
450 'deletion of bytes of code; it merely lets you write over what's already there.  A compromise has been made between editing
460 'power on one hand and length (already 1100 bytes) and ease-of-use on the other.
470 '
500 'PENRAM can be used as a
510 'stand-alone utility, called from Basic via USR or 
520 'SYSTEM, or patched onto your favorite monitor as a 
530 'replacement for its editing function.  Instructions for 
540 'appending it to RSM-2 and TBUG are given later.  
550 'Furthermore, PENRAM is in the public domain.  You may 
560 'incorporate it into any program you write, commercial 
570 'or otherwise, without royalty arrangements.  Author 
580 'credit is the only request.  
590 ' 
600 ' 
610 'CREATING THE PROGRAM 
620 ' 
630 'PENRAM is saved on your cassette with the filename PENRAM.  To load the source, first load EDTASM and then load PENRAM according to the syntax of your version of EDTASM.
640 '(The tape contains only the source code.  This allows you to assemble PENRAM at whatever location you desire.  Because of the length of the program, one side of the tape contains comments, the
641 'so it will load into
650 'other side does not.  If you have just 16K of memory, you will not be able to load the commented version.)
720 '
730 'PENRAM may be assembled at any location by 
740 'changing the STARTP address near the beginning.  Allow 
750 'a total of 1100 bytes for the code.  PENRAM also uses a 
760 'little of the stack space of the program that calls it; 
770 'this is normally of no concern. 
780 '
790 'Once assembled PENRAM may be used by itself or it 
800 'may be called by another program.  The START address is 
810 'also the entry point.  When exited PENRAM executes a 
820 'RETurn instruction so it should be called in such a 
830 'manner that this return is meaningful.  This will 
840 'always be the case if PENRAM is called as a subroutine,
850 'or if it is entered from DOS.  If PENRAM is called via the SYSTEM or USR commands in Basic, it may be preferable to jump on return to addresses 06CCH or 0A9AH, respectively.  To achieve
855 'this, change the instruction at RETLBL near the beginning of the source code from:
890 ' 
900 '                  from   RET Z 
910 '                  to     JP Z,nn 
920 ' 
921 'where nn might be 06CCH for example.  This jump takes three bytes as opposed to the one byte RET, so omit the two NOP's immediately afterwards.  The code will still be 1100 bytes long.
922 'You may of course add more code at this point to clear the screen before returning, etc.  You should assume PENRAM modifies all registers except IY.
980 '.pg
990 'USING PENRAM 
1000 ' 
1010 'On entry, or whenever you press shift/LEFT-ARROW, 
1020 'PENRAM will request an address at which to start the 
1030 'display.  Enter a four-digit hex address (or just press 
1040 '<ENTER> to quit).  A hex display of the 256 bytes of 
1050 'memory beginning at that address will appear on the 
1060 'screen.  You may change this to an ASCII display by 
1070 'pressing CLEAR.  Another CLEAR takes you back to hex.  
1080 'The blinking edit cursor will be in the upper left 
1090 'corner.  You move it using the four arrow keys -- any 
1100 'scrolling required is automatic.  At any time you may 
1110 'enter data at the current cursor position.  In the hex 
1120 'mode two hex characters (0-F) are required; in the 
1130 'ASCII mode any printable character may be entered 
1140 '(except arrows).  The characters entered will replace 
1150 'the current byte at that location.  You may BREAK after 
1160 'entering only one hex character in which case the 
1170 'original byte is restored.  All data changes are seen 
1180 'instantly on the screen.  Most keys repeat so that you 
1190 'may easily fill memory with a value, and high-speed 
1200 'scrolling is provided with the shift/UP-ARROW and 
1210 'shift/DOWN-ARROW keys.  
1220 ' 
1230 'On the right side you will see continuously displayed as:
1240 '
1250 '                     > nn <
1260 '
1270 'the actual address of the byte that the edit cursor is next to.  This makes it easy to read off addresses of interest, without counting.  Below that will be shown the value of the
1280 'current reference address and (in decimal) the displacement of the edit cursor from it.  The reference address is updated to the current edit cursor position whenever you press
1290 'shift/BREAK.  To understand the use of the reference address feature, imagine that you wish to move the cursor 287 (decimal) bytes beyond where it is.  You would press shift/BREAK to
1300 'set the reference address to the current position of the edit cursor, and then you would move the cursor downwards while watching the displacement value to see when you'd reached 287.
1310 '
1320 '
1500 'ATTACHING PENRAM TO A MONITOR 
1510 ' 
1520 'The addition of PENRAM will complement the editing 
1530 'features of a good monitor program such as RSM-2 from 
1540 'Small System Software.  It will completely transform 
1550 'the editing of a simple monitor like T-BUG.  Patching 
1560 'PENRAM to either of these is easily done.  RSM-2 
1570 'provides a "U" (user-definable) command that will 
1580 'access PENRAM.  Under T-BUG the normal "M" editing 
1590 'command is replaced.  In the following instructions all 
1600 'addresses and values are in hex.  
1610 ' 
1620 'The 48K version of RSM-2 is assumed.  For 32K, subtract 
1630 '4 from the first hex digit of each address or value 
1640 'marked "*". Thus *E7B3H for 48K becomes A7B3H for 32K.  
1650 'Similarly, *FFH becomes BFH.  For 16K, subtract 8 
1660 'instead of 4.
1670 '
1680 'Assemble PENRAM at *E7B3H by setting
1690 'STARTP in the source code to this value.  Load the 
1700 'resulting object code into memory.  Load and run RSM-2. 
1710 'Using the E-command of RSM-2, change the code at 
1720 'address:  
1730 ' 
1740 '        *EEA6H  from   00          to   7F 
1750 '        *EEB1H  from   32 80 *FF   to   00 00 00 
1760 '        *FF80H  from   C9 00 00    to   C3 76 *E7 
1770 ' 
1780 'At this point the new monitor program PENRSM 
1790 'resides from *E7B3H to *FFFFH, with entry point *EE94H. 
1800 'You may write it out to tape with the P-command, or on 
1810 'a disk system you may go to DOS with G402D and use 
1820 'TAPEDISK or the DUMP command to put PENRSM/CMD on disk. 
1830 ' 
1840 'Adding PENRAM to T-BUG is also easy.  A Level II 
1850 'non-disk machine is assumed.  Assemble PENRAM at 4980H 
1860 'and load the object code into memory there.  Load and 
1870 'run T-BUG.  Use its M-command to carefully change the 
1880 'two bytes at address 440EH: 
1890 ' 
1900 '                   from   32 45 
1910 '                   to     80 49 
1920 ' 
1930 'Use X to break from the editing mode.  The new 
1940 'monitor program PENBUG now resides from 4380H to 4D09H, 
1950 'with entry point 43A0H.  Immediately, before doing 
1960 'anything else, punch it out to tape with the P-command. 
1970 'Under PENBUG the M-command will access PENRAM;  
1980 'shift/LEFT-ARROW <ENTER> returns.  It may also be 
1990 'necessary to press X on return to get the # prompt.     
2000 '
2010 'Attaching PENRAM to other monitors can be done as in 
2020 'the case of T-BUG.  Locate the call or jump used when 
2030 'the edit command is invoked and replace it with a call 
2040 'to PENRAM.  
2050 ' 
2060 ' 
2070 'HOW PENRAM WORKS 
2080 ' 
2090 'Those interested in modifying or extending PENRAM will 
2100 'need to know something of the program structure.  Refer 
2110 'to the source code listing at the end of this article.
2120 'PENRAM operates by keeping track of three important
2130 'addresses, which will be referred to by the names of their storage locations (which are unimportant).  This is not strictly correct, but it's easier to read:
2500 ' 
2510 '.nf
2520 '    1)  HOMADD, the address that is displayed in the 
2530 '        upper-left (home) corner. 
2540 ' 
2550 '    2)  EDCUR, the current location in video memory 
2560 '        (3C00H-3FFFH) of the edit cursor. 
2570 ' 
2580 '    3)  BYTED, the actual address of the byte pointed 
2590 '        to by the edit cursor. 
2600 '.fi
2610 ' 
2620 'The screen is initially filled with 256 bytes of 
2630 'memory starting at the hex address input by the user.  
2640 'This address is the first value of HOMADD.  The edit 
2650 'cursor is positioned at the first byte displayed.  From 
2660 'there it can be moved 15 spaces to the right and/or 15 
2670 'lines down, without causing any scrolling.  A count 
2680 '(stored in RGTCUR) is kept of how many spaces to the 
2690 'right the cursor is moved.  A similar count (in DWNCUR) 
2700 'is kept of how many lines down it is moved.  PENRAM 
2710 'begins each cycle of its operation at UPDATE by 
2720 'calculating, from RGTCUR and DWNCUR, the present 
2730 'address EDCUR of the edit cursor.  It simultaneously 
2740 'calculates (from HOMADD, RGTCUR, and DWNCUR) the value 
2750 'of BYTED so that it knows to which byte in memory the 
2760 'edit cursor is pointing. 
2770 '
2780 'Once these values have been found, PENRAM displays the address stored at BYTED as the > nn < value mentioned earlier.  It
2790 'also displays the current reference address, called ATADD, and subtracts it from the BYTED address to find the present
2800 'displacement.  Available ROM routines are used to conver this displacement to decimal, and it too is displayed.
2810 '
3000 'With this done, PENRAM goes into a keyboard scan 
3010 'loop at KBDSCN.  It remains in this loop, blinking the 
3020 'edit cursor, until a key is pressed.  The cursor blink 
3030 'rate is determined by BDELAY, and the graphics 
3040 'character used for the cursor is defined by CURCHR.  
3050 'Either of these may be changed before assembly.     
3060 '
3070 'When a key is pressed, PENRAM goes to KPRESS and takes 
3080 'action as follows:  
3090 '
3100 '.nf
3110 '    1)  If a shifted up- or down-arrow key, PENRAM 
3120 '        immediately checks the value of DWNCUR and 
3130 '        modifies it or scrolls the the screen, as 
3140 '        appropriate.  This is discussed in more 
3150 '        detail below. 
3160 ' 
3500 '    2)  If the shift/LEFT-ARROW key PENRAM com- 
3510 '        pletely restarts by jumping back to its 
3520 '        ENTRY point. 
3530 ' 
3540 '    3)  If the shift/BREAK key, PENRAM immediately
3550 '        sets ATADD equal to BYTED, thus updating
3560 '        the reference address, and returns to 
3570 '        UPDATE so that the new value will be dis-
3580 '        played.
3590 '
4000 '    4)  If an unshifted arrow key, PENRAM enters a 
4010 '        debounce delay loop and then processes the 
4020 '        key by updating RGTCUR or DWNCUR and scroll- 
4030 '        ing the screen if necessary.  See below. 
4040 ' 
4050 '    5)  If the CLEAR key, PENRAM changes the type- 
4060 '        of-display flag HATYPE from hex to ASCII or 
4070 '        vice-versa, redraws the screen and restarts 
4080 '        the cycle. 
4090 ' 
4100 '    6)  If a valid hex character and in the hex mode, 
4110 '        PENRAM remembers the entry, delays briefly for 
4120 '        debounce, and awaits the next hex character. 
4130 '        When that is received PENRAM forms the new byte 
4140 '        and writes it into BYTED.  Then it steps the 
4150 '        edit cursor right one space by jumping to the 
4160 '        same place (DORT) that a right-arrow would have 
4170 '        taken it. 
4180 ' 
4190 '    7)  If a valid ASCII alpha-numeric and in the ASCII 
4200 '        mode, PENRAM writes it into BYTED and then 
4210 '        steps the edit cursor right as is (6).
4220 '.fi
4230 ' 
4240 'The delay values used for the debouncing are specified 
4250 'as KDELAY1 and KDELAY2.  You may wish to increase them 
4260 'if you experience keybounce. 
4270 ' 
4280 'The cursor movement referred to above as resulting 
4290 'from the arrow keys is coded in routines DOUP, DODN, 
4300 'DOLF, and DORT.  These can be generally described as 
4310 'follows.  If the user is not attempting to move the 
4320 'cursor off-screen then PENRAM just translates the arrow 
4330 'keystrokes into appropriate changes in RGTCUR and 
4340 'DWNCUR, and returns to UPDATE to begin the next cycle.  
4350 '
4360 'When the cursor is moved beyond the edge of the 
4370 'screen, scrolling must take place.  This is done by 
4380 'shifting the current contents of the screen up (or 
4390 'down) by one line, updating HOMADD, and writing one new 
4400 'line at the bottom (or top).  RGTCUR and DWNCUR are 
4410 'also changed as required.  PENRAM then returns to 
4420 'UPDATE to begin the next cycle.  
4430 '.PG 1 .RP 5
