TRS-80 String Packing and USR() Routines

General Framework and Explanation

Machine language routines in BASIC all follow the same general steps. You can either POKE it into RAM or pack it into a STRING. For the latter, you would set up a string of the length of the number of bytes in your machine language routine, find the LSB and MSB of that string, load the USR routine start address with that LSB and MSB, and then call the routine.

“Graphic packing” uses the same concepts as string packing, except graphics are packed into a string, using 1 byte instead of a lot more.

In both cases, there are a number of ways to set up the string. Let’s say you want 10 characters. You can set it:

1. As a straight declaration like A$=”XXXXXXXXXX” or A$(1)=”XXXXXXXXXX”
2. You can create the string by using the STRING$ command like A$=STRING$(10,”X”)
3. You can build the string character by character by something like
   FOR X = 1 TO 10: READ D : A$=A$+CHR$(D) : NEXT X.

These all work equally well for loading code into a string, although you can only use #1 if you want to do the packing just once and embed it into your program as an already packed string. #3 is usable only if you are generating the string at run time, but you need to recalculate the VARPTR just before you set the jump points because automated garbage collection at the system level might move the string during or after build.

Anyway, to pack a string, you tell the computer to replace each byte in the string (in this case, A$) with a different byte. You then need to figure out where the starting address for that string is, and that is to use the VARPTR instruction.

In general, the LSB of the address is found at address is found at PEEK(VARPTR(A$)+ 1) and the MSB of the address is found at PEEK(VARPTR(A$)+ 2). The MSB and LSB combined into one number would be found at PEEK(VARPTR(A$)+ 2)*256 + PEEK(VARPTR(A$)+ 1).

Graphics Packing

In graphics packing, you would write a separate program to pack the string, and then you would delete that program, except for the packed string, for further use. Because of this, you can’t build the string using example #3 above – you need it to be physically in your program. You also won’t ever need to know the location in memory of the string, so VARPTR isn’t needed at run time.

A sample program to pack graphics would start off like the following:

If you run this program and then list it, you will note that line 10 has changed to

That’s 49 characters long … BUT … if type ?LEN(A$) you will get 10 bytes, because the graphics have been packed into those 10 bytes

and if you type ?A$ you will now see graphics!

Once you have line 10 set up this way, you can delete lines 20-70 and get on with your program. But note, you CANNOT edit line 10. If you need to modify line 10 you are going to need to run the program again, with your fixes in the DATA line.

So an example of keeping the string you packed, delete lines 20-70 leaving only line 10, and then writing a program around it would be:

This will take that shape and move it across the top of the screen. No set/reset, no complex graphics controls … just a simple PRINT@!

Complex Graphics Example

Before moving onto machine language packing, let’s do a more complicated example. The following program will load 5 variables with 5 different 4 byte graphics of the familiar “Flagship” from the Big 5 games. I used an array to make the programming much shorter for purposes of this example.

10 A$(1)=”XXXX”
20 A$(2)=”XXXX”
30 A$(3)=”XXXX”
40 A$(4)=”XXXX”
50 A$(5)=”XXXX”
60 FOR I = 1 TO 5 : P(I) = PEEK(VARPTR(A$(I))+ 2)*256 + PEEK(VARPTR(A$(I))+ 1) : NEXT I
70 FOR I = 1 TO 5 : FOR J = 1 TO 4 : READ D : POKE P(I)+J-1,D : NEXT J : NEXT I
80 DATA 166,179,179,153 : ‘Flagship with no eye
90 DATA 166,183,179,153 : ‘Flagship with the eye in space 1
100 DATA 166,187,179,153 : ‘Flagship with the eye in space 2
110 DATA 166,179,183,153 : ‘Flagship with the eye in space 3
120 DATA 166,179,187,153 : ‘Flagship with the eye in space 4

If I used A$, B$, C$, D$, and E$ to match the above example instead of A$(1)…A$(5), I would need 5 different VARPTR lines with 5 different variables, and then would need 5 different loops to load the 4 bytes into the strings. Nothing really wrong with that, but it would make this page really long. You might say “why didn’t you use a loop to load the variables with the “XXXX”, instead of typing the same thing over and over from lines 10 to 50?”. That’s because we need those to be physically present in the program to do graphic packing, so they need to be individually defined.

So while we can’t use a FOR … NEXT loop to load the strings, we CAN us them everywhere else. With this, both lines 60 and 70 start with a FOR … NEXT loop for 5 elements, because there are 5 strings. Everything else on the line, matches the standard steps of using the VARPTR to find the POKE address, and then POKEing in the data.

If you run that and then were to enter FOR X = 1 TO 5 : PRINT A$(X); ” “;: NEXT X from the command line, you would see all 5 strings next to each other:

To get the flagship to move across the screen, you would then enter.

60 CLS
70 FOR I = 0 TO 55 STEP 5
80 FOR J = 1 TO 5
90 PRINT @ (I+J-1),” “;A$(J);
100 FOR K = 1 TO 10 : NEXT K
110 NEXT J
120 NEXT I

And you would wind up with this (NOTE: This is a repeating animated GIF, the flagship only goes from one side to the other in this program)

Machine Language / USR Packing

Machine language packing is the same theory as graphic packing, except that you need to know the variables location in memory to set up the USR call. It is also a good idea to implement some safety protocols into your program to check for cases of too much, or too little, data.

To point the USR to the string, DOS and non-DOS BASIC have different ways of implementation.

• In non-DOS BASIC, you need to poke the LSB of the string into 16526 and the MSB into 16527. Once you do that, X=USR(0) will run the program in the string.
• In DOS BASIC, you would use the DEFUSR0 command to set the call address for USR(0), but some DOS’s, like TRSDOS, won’t let you set a number higher than 32767. To get around this, you need to use a formula which calculates the entry point in the -32767 to 32767 range.

So, with this background, for machine language packing with a USR call, the routine generally would look like:

Once run, the routine is called by a simple X=USR(0) command.

Ready-to-Use Machine Language Routines

Multiple USR() Calls

The following heading in the machine program permits as many USR calls as memory allows. A call for USR(0) goes to program 0, a call for USR(1) goes to program 1, etc. As it stands it can be used for graphics. If data needs to be passed to the machine program then Memory Size should be set to the appropriate number of bytes below the origin of the heading, the data poked into this “scratchpad” before calling USR(n), and program (n) then loads from the “scratchpad” as desired.

The first line of each program should bear the appropriate label – PRGO, PRG1, etc. It is, of course, imperative that no changes be made between CALL 2687 and JP PRGn.

Assembly language heading for multiple USR calls: