MCUtil

Date: 198x

Type: Program

Platform(s): TS 2068

MCUtil is a machine code utility suite providing seven tools for inspecting, entering, relocating, and converting machine code in memory. The program displays memory contents as a navigable block grid (up to 160 bytes) with joystick support via STICK, uses UDG characters (defined by POKEing addresses 65368–65391) to render a three-character cursor overlay with OVER 1, and performs hex conversion by hand using CHR$ arithmetic rather than a built-in hex function. A separate decimal-to-machine-code address splitter computes the high and low bytes of any 16-bit address, and a relocation routine handles both upward and downward block moves with careful loop-bound calculations to avoid overwriting source data. Lines 9958–9999 contain a self-modifying BASIC renumberer that patches GO TO/GO SUB target line numbers in both their display text and the hidden floating-point number stored inline by the Spectrum’s tokenizer.

Program Structure

The program is organized as a menu dispatcher at line 2560 that routes to seven functional modules. Lines below 2560 contain the modules; lines above 2560 through 3700 hold shared subroutines; and lines 9958–9999 are a standalone BASIC renumberer appended at the top of the line-number space to avoid interfering with renumbering itself.

Lines	Module
1050–1400	Review MC in blocks (navigable grid)
1410–1530	Decimal address → Low/High byte splitter
1540–1780	Dec code pair → decimal value converter
1790–2000	Machine code loader (POKE loop)
2040–2470	Relocate machine code block
2480–2550	RAMTOP display
2560–2850	Main menu
2860–2950	Hex conversion subroutine
2970–3280	Input & calculate (N / S / E)
3350–3380	RAMTOP PEEK subroutine
3410–3450	Memory array builder (DIM M$)
3490–3560	UDG cursor definition
3570–3700	List MC by address with hex column
9958–9999	Self-modifying BASIC renumberer

Memory Array and Block Display

The block viewer (lines 1050–1400) stores up to 160 bytes as a string array M$ dimensioned to (N,4) at line 3410, where each element holds the decimal string representation of a POKEd byte (e.g., "255"). The display arranges bytes in a 20-column × 8-row grid; the cursor position (X,Y) maps to a byte index via SA = 8*X + INT(Y/4) + 1, reflecting the four-character-wide fields.

Three UDG characters \a\b\c (chars 144–146) are defined at lines 3520–3550 by POKEing 24 bytes starting at address 65368. They form a three-part cursor bracket drawn with PRINT AT X,Y; OVER 1;"\a\b\c", using OVER 1 (XOR mode) so the cursor can be erased by redrawing it without restoring the background explicitly.

Joystick and Keyboard Navigation

Lines 1360–1390 implement dual-input navigation combining STICK (port 2 joystick) with cursor keys 5/6/7/8. The STICK return value is decoded by checking ranges: values 1/5/9 = up, 2/6/10 = down, ST>7 = right, ST>3 AND ST<7 = left. Boundary clamping uses Boolean arithmetic rather than IF statements; for example, X = X + (X<0) - (...overflow condition...) keeps X within the valid grid row range, with separate logic for the final partial row controlled by XLIM and YLIM.

Hex Conversion Subroutine

Lines 2890–2950 convert a decimal byte value stored in M$(I) to a two-character hex string in H$. It splits the value into high and low nibbles, then converts each nibble to its ASCII character: digits 0–9 via CHR$(nibble+48) and letters A–F via CHR$(nibble+55). There is no built-in hex function, so this manual approach is the standard workaround.

Relocation Routine

The relocator (lines 2040–2470) handles both upward and downward moves. If the new address NS is below the source start S, it copies forward (low-to-high addresses, lines 2270–2300) to avoid overwriting unread source bytes; if NS > S, it copies backward (high-to-low, lines 2350–2380). After copying, the vacated region is zeroed. The zero-fill loop bound is computed with a conditional expression:

If the gap is smaller than the block: zero only the gap (S-NS-1 or NS-S-1 iterations).
If the gap equals or exceeds the block: zero the entire original block (E-S iterations).

This avoids zeroing bytes that were never part of the original block when the destination is far from the source.

Input and Calculation Subroutine

Lines 2970–3280 accept any two of three values — number of bytes N, starting address S, and ending address E — and derive the third. The logic at lines 3110–3270 handles all combinations. A guard at line 3110 detects the degenerate case where both N$ and S$ are empty and redirects to the error handler at 3280. The subroutine shares a Q variable with the menu to enforce the 160-byte limit only for the block viewer (option 1).

RAMTOP Subroutine

Lines 3350–3380 read RAMTOP from Spectrum system variables at addresses 23730 (low byte) and 23731 (high byte), combining them as RT = 256*RH + RL. The relocation routine at lines 3460–3480 (reachable but not called from the menu) would lower RAMTOP by POKEing the updated value back to the same addresses.

Self-Modifying BASIC Renumberer (Lines 9958–9999)

This module walks the BASIC program area using the PROG system variable at address 23635. It uses two inline functions: FN A(X) reads a little-endian 16-bit word (low byte first) and FN B(S) reads a big-endian 16-bit word (high byte first), used to read line lengths and line numbers respectively.

The first pass (9962–9975) scans all lines below 9958 for GO TO (token 236) and GO SUB (token 237) statements, collecting the memory address and current target line number of each into the string T$ in 9-character records: 5-character address + 4-character line number.

The second pass (9976–9987) walks the program again, renumbering lines starting at 1000 in steps of 10 by POKEing the new line number into the two header bytes of each line. For each line, it checks T$ for any GO TO/GO SUB targeting that line and calls the subroutine at 9990 if found.

The patch subroutine (9990–9999) updates both the display text of the target number (4 bytes via CODE(STR$ BASE)(J)) and the Spectrum’s hidden inline floating-point representation (5 bytes starting 6 bytes after the token), reconstructing the binary float from the new line number using LN to determine the exponent byte.

Bugs and Anomalies

Line 3230 recalculates N = E-S+1 and then checks IF E<S THEN GO TO 3175, but line 3175 does not exist; this would generate an error. However, the guard at line 3200 already prevents E<S from reaching line 3230 in practice.
Lines 3390–3400 (LET S$="RT+1-N") and 3460–3480 (lower RAMTOP) are defined but never called from any menu option or subroutine in the listing.
Line 3000 references Q=1 as a guard, but the subroutine at 2970 is entered for menu option 1 before Q is set at line 3000; for other options the condition is false, which is the intended behavior.
The “ADDESS” typo (missing R) at lines 2200 and 2210 appears in both screen and LPRINT output.
Line 1300 validates Q$ as an integer between 0 and 255, but if Q$ contains non-numeric text, VAL Q$ will return 0 rather than raising an error, silently POKEing 0.

Content

Appears On

Image Gallery

Source Code
REM ***********************
REM MCUTIL
REM ***********************
BORDER 5
GO TO 2560
REM ***********************
REM LIST BY BLOCK
REM ***********************
LET T$="1"
GO SUB 3010
GO SUB 3410
GO SUB 3490
CLS 
LET XLIM= INT ((N-1)/8)
LET YLIM=4*(N-1-8*XLIM)
FOR I=1 TO N
PRINT M$(I);
LPRINT M$(I);
NEXT I
PRINT AT 21,0;"\{20}\{1}\{20}\{1}ENTER E TO EXIT   M TO MODIFY\{20}\{1}   \{20}\{0}\{20}\{0}"\{20}\{0}
LET X=0:LET Y=0:LET X1=0:LET Y1=0
PRINT AT X,Y; OVER 1;"\a\b\c"
LET SA=8*(X)+ INT (Y/4)+1
LET SAO=8*(X1)+ INT (Y1/4)+1
PRINT AT X1,Y1;M$(SAO)
PRINT AT X,Y; OVER 1;"\a\b\c"
PRINT AT 20,12;"CURSOR ADDRESS ";S+SA-1
IF INKEY$="E" THEN GO TO 2560
IF INKEY$ <>"M" THEN GO TO 1330
INPUT "ENTER NEW BYTE: ";Q$
IF Q$="" OR VAL Q$<0 OR VAL Q$>255 OR VAL Q$ <> INT VAL Q$ THEN GO TO 1330
POKE (S+SA-1), VAL Q$:LET M$(SA)=Q$
PRINT AT X,Y;M$(SA)
LET ST=STICK (1,2)
LET X1=X:LET Y1=Y
LET X=X+(ST=2 OR ST=6 OR ST=10 OR INKEY$="6")-(ST=1 OR ST=5 OR ST=9 OR INKEY$="7")
LET X=X+(X<0)-((X>XLIM AND Y <=YLIM) OR (X>XLIM-1 AND Y>YLIM))
LET Y=Y+4*((ST>7 OR INKEY$="8")-((ST>3 AND ST<7) OR INKEY$="5"))
LET Y=Y+4*((Y<0)-((Y>28 AND X<(XLIM)) OR (Y>YLIM AND X=XLIM)))
GO TO 1220
REM ***********************
REM DECIMAL TO MC
REM ***********************
CLS 
PRINT "\{20}\{1}DECIMAL TO MC\{20}\{0}"
PRINT 
INPUT "ENTER ADDRESS (DECIMAL): ";Q$
LET H= INT ((VAL Q$)/256)
LET L= VAL Q$-256*H
PRINT "ADDRESS: ";Q$; TAB 16;"L: ";L; TAB 24;"H: ";H
INPUT "NEW ADDR?"'"HIT ENTER TO RET TO MENU   ";Q$
IF Q$="" THEN GO TO 2560
GO TO 1480
REM ***********************
REM DEC CODE TO DEC VALUE
REM ***********************
CLS 
PRINT 
PRINT AT 0,0;"\{20}\{1}DEC. CODE TO DEC. CONVERSION\{20}\{0}"
LPRINT AT 0,0;"\{20}\{1}DEC. CODE TO DEC. CONVERSION\{20}\{0}"
PRINT 
LPRINT 
PRINT AT 3,0;"LOW"; AT 3,5;"HIGH"; AT 3,12;"ADDR OR VALUE"
LPRINT AT 3,0;"LOW"; AT 3,5;"HIGH"; AT 3,12;"ADDR OR VALUE"
PRINT 
LPRINT 
INPUT "HIT ENTER TO RETURN TO MENU..."'"DECIMAL CODE: LOW ";L$
IF L$="" THEN GO TO 2560
PRINT L$;
LPRINT L$
INPUT "DECIMAL CODE: HIGH ";H$
IF H$="" THEN GO TO 2560
PRINT TAB 5;H$;
LPRINT TAB 5;H$
LET A=256*(VAL H$)+ VAL L$
PRINT TAB 12;A
LPRINT TAB 12;A
GO TO 1670
REM ***********************
REM MC LOADER
REM ***********************
CLS 
PRINT "\{20}\{1}MC LOADER\{20}\{0}"
GO SUB 2970
CLS 
PRINT "INPUT CODE (DEC) FOR EA ADDR"
LET SUM=0
FOR I=1 TO N
PRINT INK 3; VAL (S$)+I-1;
INPUT C$
IF C$="" THEN CLS :GO TO 2560
IF VAL C$>255 THEN GO TO 1900
PRINT TAB (10- LEN C$);C$
POKE (VAL (S$)+I-1), VAL C$
LET SUM=SUM+ VAL C$
NEXT I
PRINT 
PRINT "CHECKSUM= ";SUM
PRINT "HIT ANY KEY TO RETURN TO MENU":PAUSE 4E4
GO TO 2560
REM ***********************
REM RELOCATE MC
REM ***********************
CLS 
PRINT "RELOCATE MACHINE CODE"
PRINT 
GO SUB 2970
PRINT "CURRENT STARTING ADDRESS OF"'"BLOCK TO BE RELOCATED IS   ";S$
PRINT 
LPRINT "CURRENT STARTING ADDRESS OF"'"BLOCK TO BE RELOCATED IS   ";S$
LPRINT 
PRINT "ENDING ADDRESS OF BLOCK"'"TO BE RELOCATED ";E
LPRINT "ENDING ADDRESS OF BLOCK"'"TO BE RELOCATED ";E
PRINT 
LPRINT 
INPUT "ENTER NEW START ADDRESS   ";T$
IF T$="" THEN GO TO 2560
LET NS= VAL T$
IF NS<1 OR NS <> INT NS THEN GO TO 2160
PRINT "NEW STARTING ADDESS IS   ";NS
LPRINT "NEW STARTING ADDESS IS   ";NS
PRINT 
LPRINT 
PRINT "BLOCK BEING RELOCATED"
PRINT 
IF S<NS THEN GO TO 2350
FOR I=0 TO E-S
LET C= PEEK (S+I)
POKE (NS+I),C
NEXT I
FOR I=0 TO ((S-NS-1)*((S-NS) <=(E-S)))+((E-S)*((S-NS)>(E-S)))
POKE (E-I),0
NEXT I
GO TO 2450
FOR I=0 TO E-S
LET C= PEEK (E-I)
POKE (E+NS-S-I),C
NEXT I
PRINT "NOW ZEROING VACATED MEMORY LOCATIONS"
FOR I=0 TO ((NS-S-1)*((NS-S) <=(E-S)))+((E-S)*((NS-S)>(E-S)))
POKE (S+I),0
IF I/200= INT (I/200) THEN PRINT "STILL RUNNING"
NEXT I
PRINT 
PRINT "THE BLOCK OF MACHINE CODE HAS"'"BEEN RELOCATED TO START AT"'NS
PAUSE 600
GO TO 2560
REM ***********************
REM RAMTOP
REM ***********************
CLS 
GO SUB 3350
PRINT "RAMTOP IS AT ";RT
PAUSE 600
GO TO 2560
REM ***********************
REM MENU
REM ***********************
CLS 
PRINT TAB 10;"\{20}\{1}\  \  \  \m\e\n\u\  \  \  \{20}\{0}"
PRINT 
PRINT 
PRINT "1...REVIEW MC IN BLOCKS"
PRINT 
PRINT "2...REVIEW MC WITH ADDRESSES"
PRINT 
PRINT "3...CONVERT DECIMAL TO MC"
PRINT 
PRINT "4...CONVERT DEC CODE TO DEC VAL"
PRINT 
PRINT "5...MACH CODE LOADER"
PRINT 
PRINT "6...RELOCATE MACH CODE"
PRINT 
PRINT "7...RAMTOP LOCATION"
PRINT 
INPUT "ENTER SELECTION  ";Q
CLS :IF Q=1 THEN PRINT "REVIEW MC IN BLOCKS":PRINT :PRINT "JOYSTICK IS ALLOWED IN PORT 2":GO TO 1050
IF Q=2 THEN GO TO 3570
IF Q=3 THEN PRINT "CONVERT DECIMAL TO MC":PRINT :GO TO 1410
IF Q=4 THEN PRINT "CONVERT DEC CODE TO DEC VALUE":PRINT :GO TO 1540
IF Q=5 THEN PRINT "MACHINE CODE LOADER":PRINT :GO TO 1790
IF Q=6 THEN GO TO 2040
IF Q=7 THEN GO TO 2480
GO TO 2560
REM ******************
REM HEX CALCULATION
REM ******************
LET P= INT (VAL M$(I)/16)
LET Q= VAL M$(I)-16*P
IF P <=9 THEN LET H$= CHR$ (P+48)
IF P>9 THEN LET H$= CHR$ (P+55)
IF Q <=9 THEN LET H$=H$+ CHR$ (Q+48)
IF Q>9 THEN LET H$=H$+ CHR$ (Q+55)
RETURN 
REM ***********************
REM INPUT AND CALC ROUTINE
REM ***********************
IF Q=1 THEN PRINT AT 5,0;"MAXIMUM OF 160 BYTES"
PRINT AT 10,0;"ENTER ANY 2 OF 3 ITEMS"
PRINT AT 12,0;"NUMBER OF BYTES:"
PRINT AT 14,0;"STARTING ADDRESS:"
PRINT AT 16,0;"ENDING ADDRESS:"
PRINT AT 18,5;"HIT ENTER IF UNKNOWN"
INPUT "ENTER NUMBER OF BYTES  ";N$:IF N$="" THEN GO TO 3100
LET N= VAL N$:IF N<1 OR N <> INT N THEN GO TO 3060
IF Q=1 AND N>160 THEN GO TO 3060
PRINT AT 12,17;N
INPUT "ENTER STARTING ADDRESS  ";S$
IF N$="" AND S$="" THEN GO TO 3280
IF S$="" THEN GO TO 3160
LET S= VAL S$:IF S<1 OR S <> INT S THEN GO TO 3100
PRINT AT 14,18;S
IF N$ <>"" THEN LET E=S+N-1:PRINT AT 16,16;E:PRINT AT 18,0;"CREATING MEMORY ARRAY       ":PAUSE 180:RETURN 
INPUT "ENTER ENDING ADDRESS  ";E$:IF E$="" THEN GO TO 3280
LET E= VAL E$
IF E<1 OR E <> INT E THEN GO TO 3250
IF S$="" THEN LET S=E-N+1
IF E<S THEN PRINT AT 20,0; FLASH 1;"END ADDR MUST BE > START ADDR":PAUSE 180:PRINT AT 20,0,"                                ": GO TO 3160
PRINT AT 16,16;E
PRINT AT 14,18;S
LET N=E-S+1:IF E<S THEN GO TO 3175
IF Q=1 AND N>160 THEN PRINT FLASH 1; AT 5,0;"MAXIMUM OF 160 BYTES":PAUSE 180:PRINT AT 14,18;"       "; AT 16,16;"       ":GO TO 3000
PRINT AT 12,17;N
PRINT AT 12,17;N
PRINT AT 18,0;"CREATING MEMORY ARRAY       ":PAUSE 180:RETURN 
PRINT FLASH 1; AT 10,0;"ENTER ANY 2 OF 3 ITEMS":PAUSE 180
PRINT AT 12,17;"       "; AT 14,18;"       "; AT 16,16;"      ":GO TO 3010
GO SUB 3350
IF S$="" THEN LET S$="RT+1"
PRINT "STARTING ADDRESS IS "; VAL S$
PRINT 
RETURN 
LET RL= PEEK 23730
LET RH= PEEK 23731
LET RT=256*RH+RL
RETURN 
LET S$="RT+1-N"
RETURN 
DIM M$(N,4)
FOR I=1 TO N
LET M$(I)= STR$ PEEK (S-1+I)
NEXT I
RETURN 
GO SUB 3350
PRINT "RAMTOP BEING LOWERED TO ";RT-N:POKE 23730,(RT-N)-256* INT ((RT-N)/256):POKE 23731, INT ((RT-N)/256)
RETURN 
REM ***********************
REM CREATE CURSOR
REM ***********************
RESTORE 
FOR I=65368 TO 65391
READ D:POKE I,D
NEXT I
DATA 255,128,128,128,128,128,128,255,255,0,0,0,0,0,0,255,255,1,1,1,1,1,1,255
RETURN 
REM ***********************
REM LIST BY ADDRESS
REM ***********************
CLS :PRINT "\{20}\{1}LIST MC BY ADDRESS\{20}\{0}"
GO SUB 2970
GO SUB 3410
CLS :PRINT "ADDR"; TAB 7;"DEC"; TAB 13;"HEX":PRINT 
FOR I=1 TO N
PRINT S-1+I; TAB 7;M$(I);
GO SUB 2860
PRINT TAB 13;H$
LPRINT S-1+I; TAB 7;M$(I); TAB 13;H$
NEXT I
PRINT AT 21,0;"HIT ANY KEY TO RETURN TO MENU":PAUSE 4E4
GO TO 2560
CLS :PRINT "RENUMBERING STARTING AT 1000"
LET T$="":LET X=23635
DEF FN A(X)= PEEK X+256* PEEK (X+1)
DEF FN B(S)=256* PEEK S+ PEEK (S+1)
LET S= FN A(X)
LET LINE= FN B(S):IF LINE >=9958 THEN GO TO 9976
LET LENGTH= FN A(S+2)
IF PEEK (S+4)=234 THEN GO TO 9969
FOR I=S+4 TO S+LENGTH+2
IF PEEK I=236 OR PEEK I=237 THEN GO SUB 9971
NEXT I
LET S=S+LENGTH+4
GO TO 9963
IF PEEK (I+5)=14 THEN GO TO 9974
PRINT "N0N-STANDARD COMMAND, LINE ";LINE
STOP 
LET T$=T$+ STR$ I+ CHR$ PEEK (I+1)+ CHR$ PEEK (I+2)+ CHR$ PEEK (I+3)+ CHR$ PEEK (I+4)
RETURN 
LET BASE=1000:LET X=23635
LET S= FN A(X)
LET LINE= FN B(S):IF LINE >=9958 THEN BEEP 5,0:STOP 
LET LENGTH= FN A(S+2)
FOR I=1 TO LEN T$ STEP 9
IF VAL T$(I+5 TO I+8)=LINE THEN GO SUB 9990
NEXT I
POKE S, INT (BASE/256)
POKE S+1,BASE-256* INT (BASE/256)
LET BASE=BASE+10
LET S=S+LENGTH+4
GO TO 9978
FOR J=1 TO 4
POKE (VAL T$(I TO I+4)+J), CODE (STR$ BASE)(J)
NEXT J
LET BYTE1=128+ INT (LN BASE/ LN 2+1)
LET BYTE2=BASE*65536/(2^(BYTE1-128))
LET MEMORY= VAL T$(I TO I+4)
POKE MEMORY+6,BYTE1
POKE MEMORY+7, INT (BYTE2/256)-128
POKE MEMORY+8,BYTE2-256* INT (BYTE2/256)
RETURN 

Note: Type-in program listings on this website use ZMAKEBAS notation for graphics characters.

Program Structure

Memory Array and Block Display

Joystick and Keyboard Navigation

Hex Conversion Subroutine

Relocation Routine

Input and Calculation Subroutine

RAMTOP Subroutine

Self-Modifying BASIC Renumberer (Lines 9958–9999)

Bugs and Anomalies

Content

Appears On

Related Products

Related Articles

Related Content

Image Gallery

Source Code

Tags

People