VRename
BASIC variable renaming tool.
By Doug White
Clear up old BASIC programs and make your own programs more readable by renaming the variables with this handy BASIC utility. This BASIC program works on all 8-bit Atari computers of any memory size, with disk drive.
Have you ever gotten a BASIC program out of an old magazine or from a friend that was difficult to read because it had cryptic names for all of the variables? While Atari BASIC allows variable names up to 120 characters long, some of the more primitive BASIC interpreters on some computers allow a maximum of two characters for each variable name. If you didn't write the program how can you tell what names like R9, D$, L2 and X$ mean?
Or have you used a subroutine from an old program in a new BASIC program that you were writing? There'd be a good chance that some of the variables were not compatible between that subroutine and the rest of the program. You had two choicesÑ either change every occurance of each problem variable name throughout the entire program, or else add program lines to assign needed data from the variable names that the program uses to the corresponding variable names that the subroutine uses.
The first solution is time-consuming. The second creates confusing "spaghetti code," since the same piece of data will have a different name depending upon where it is in the program.
To help you (and me) write understandable programs and decipher programs already owned, I have constructed a programming utility that will let you rename any or all of the variables in a BASIC program.
This programming tool is simple in theory but powerful in practice. VRename can be used on completed programs stored on disk. But it is primarily designed to let you modify the variable names of a program that you are currently writing. For this reason the utility does not change the margins, colors, or any other feature of the display that you may have customized for your own convenience.
GETTING STARTED
Type in Listing 1, VRENAME.LST, check it with TYPO II. This utility will not work with SAVE and LOADÑso LIST a copy of it to disk before you use it the first time. The utility deletes itself from memory after it is finished, so once you RUN it you'll have to retype the whole program if you don't have a copy safe on disk.
Rather than making up a useless test program for demonstration purposes, I've included a program that contains a Shellsort routine in lines 500-680 for sorting numbers stored in an array named A() into descending order. Type in Listing 2, SHELSORT.BAS, check it with TYPO II, and SAVE a copy to disk.
The Shellsort is much faster than the commonly used bubble sort. If you want to use it in your programs, just rename A() to whatever name your program uses. If you need the numbers sorted in ascending order, change the < character in line 620 to a > character.
USING VRENAME.LST
Now you can RUN the Shellsort program to try it out. Then, with the sorting program still in memory, ENTER "D.VRENAME.LST:" and RUN it.
The first variable used in the sort program, A(, will be shown on the screen. To rename it, type [Y] and press [RETURN]. Now type in the new name and press [RETURN]. Since the variable A( is an array, your new array name must also end with a ( character. Type [Y] and press [RETURN] if the name is spelled correctly.
The next variable name will now be shown on the screen. If you don't want to rename it, just press [RETURN] and the following variable name will appear. This process will continue until the last variable name of the sort program has been displayed.
Now the program will prompt you for a name for the disk file in which you want to keep the modified program. For example, type in D:SHEL2, or if you don't need a permanent copy you could use D8:SHEL2 to store it to a RAMdisk.
After the utility finishes, it will delete itself from memory. Press [RETURN] one more time to ENTER the modified program back into memory. Now if you LIST the program to the screen it contains the renamed variables. RUN the program and it will execute just as it did before.
CHANGING YOUR OWN
VRename will work with almost any BASIC program, but your program must have line numbers greater than 0 and less than 31500. LOAD your program, then ENTER "D:VRENAME.LST" from disk. Then RUN the program, and rename variables as described above.
Be careful that you don't use reserved BASIC words (like LOAD, RUN, NEXT) as variable names. If you have a lot of variables, be sure you don't give different variables the same name by mistake. As always when modifying a program, it's a good idea to keep a backup copy on disk.
HELPFUL HINTS
While you are typing in a program, you can use variable names that are short and easy to type. After you finish you can substitute longer, more descriptive names. Simpler variable names mean less typing, and will not only save you time but will probably reduce the number of typing errors that you make.
When your program is running properly, you can use my variable renaming utility to add descriptive names that use these characters without causing any problems.
BASIC TOKENS
When you type in a program in Atari BASIC, the BASIC interpreter translates each program line into a line number and a series of string constants, floating-point constants, and, tokens. Tokens are numbers that stand for each of the variables and BASIC commands in the program. The tokens are stored in a table called the statement table, which contains a "shorthand" version of the program. The tokenized version of the program in the statement table takes up less space and executes much faster than the program would if it were still in the original ASCII form.
If the value of a token is less than 128, it represents one of the BASIC commands or BASIC operators. If a token value is greater than 128 it stands for one of the variables in the program. For example, if the program contains a SETCOLOR command, the statement table will contain a 48 which is the token value for this command. In similar fashion a variable name will be replaced by a one-byte token each time it appears in the statement table.
The characteristics of each of the variables are stored in three other system tablesÑthe variable name table (VNT) which contains the variable names that correspond to each of the variable tokens; the variable value table (WT) which indicates whether a variable is a string, an array, or a simple variable called a scalar; or the string and array table (START) which holds the contents of every string variable and the value of each element in every array variable in the program.
In the variable renaming utility we are primarily concerned with the VNT. After a program is stored in memory, BASIC works with the tokens, the VVT and the START and ignores the variable names for the most part. Only when you are manually entering a program, LlSTing it, or ENTERing it from disk or cassette are you directly working with the individual variable names. The SAVE and LOAD commands access the system tables only as a continuous block of data, and are of no use in renaming the variables.
All of the BASIC system tables that I've mentioned change size and move around in memory as different BASIC processes occur. The BASIC interpreter keeps track of the location of each of the tables using pointers.
Pointers are memory locations that contain the addresses of tables and other important data that move around in memory. While the address stored in a pointer may change, the pointer itself stays in the same place. The variable renaming utility uses two pointers called VNTP, which points to the beginning of the VNT, and VNTD, which points to the byte immediately following the end of the VNT.
HOW IT WORKS
When you ENTER the utility from disk, it merges itself around your progam. Your progam must therefore have line numbers greater than 0 and less than 31500. The utility jumps from line 0 directly to line 31500 and does not execute the original program. The utility then reads each variable name out of the VNT and asks if you want to change that name. The old variable name or the new variable name (if you just changed it) is then stored in VARNAME$.
The utility goes through all of the names in the VNT until it reaches VARNAMES, the first variable of the utility itself. (If no names were changed, the utility terminates and both the program and the utility remain in memory.)
Now there is a complete updated list of all of the variable names stored in VARNAME$. The utility puts the address of VARNAMES into VNTP to make BASIC look for variable names in VARNAME$ instead of looking in the old table.
After you type in the name of the disk file where you want to store the modified version of your program, the utility LISTs lines 1-31499 (the original program) out to that disk file. As the program is being converted from tokens back into ASCII, the address in VNTP tells BASIC to read the updated names stored in VARNAME$.
Finally the utility clears memory with a NEW command, which terminates the utility. Press the [RETURN] key and the modified program will be reentered into memory from the ASCII file now on disk.
An added benefit of LISTing and ENTERing your progam to and from disk is that it cleans up your program. Old unused variable names will be discarded. If your 800XL has Revision B BASIC ROM, 16 bytes of garbage are added to the end of your program each time you SAVE it to disk. Periodically LISTing the program to disk and ENTERing it removes this garbage. You have Revision B ROM if you PEEK(43234) and the result is 96.
PROGRAM TAKE-APART
31514 VNT is assigned the address of the variable name table. VNT is incremented to keep track of the current character being read from the table.
31518-31530 Read each variable name.
31531-31598 Change a variable name and put the new name in VARNAME$. If unchanged the old name is put in VARNAME$.
31606-31614 Store the old variable name table pointers.
31618-31648 Make the variable name table pointers point to VARNAME$.
31652-31688 LIST the modified program out to a disk file.
31690 NEW clears out user memory and resets the system table pointers.
31694-31706 TRAP routine. If an error occurs while LISTing the modified program to disk, the old VNT pointers are restored.
SPECIAL CASES
As I mentioned earlier, this utility is designed to merge itself around a program that is currently in memory. With a dimensioned size of 2000 characters, VARNAME$ will hold 128 names that average 15 characters in length, or 64 names that average 31 characters, or 32 names that average 63 characters, etc. If you have a particularly large program, both the program and the utility may not fit in available mernory at the same time. If this occurs feel free to decrease the dimension of VARNAME$.
Another problem might arise with programs that use a lot of variable names. Atari BASIC limits you to 128 variables in one program. The renaming utility itself uses three string variables and 13 scalar variables.
128 - (3 + 13) = 112 VARIABLE NAMES
If your program uses more than 112 variables, ENTERing the utility may cause an error since the total number of variables exceeds 128.
First, try to localize the section of the program that contains the variables that you wish to rename. Rename the variables in that section. Then recombine the program section with the rest of the program.
If this process does not solve the problem, you will have to create a special version of the renaming utility which uses the same variable names as your program. Use the following procedure:
1. LIST your program to disk and type NEW to clear memory.
2. ENTER the utility into memory.
3. Delete line 31534.
4. Modify line 31680 to read: 31680 LIST NAME$
5. Type RUN to run the utility on itself.
6. As each variable name is displayed, rename it to one of the variable names in your program.
7. When the utility is finished, ENTER the modified copy of the utility into memory
8. Modify line 31680 to read: 31680 LIST NAMES,1,31499
9. LIST the modified utility back out to a disk file.
When you ENTER this specially tailored copy of the utility into memory with your program, BASIC will not have to add any new variables, since they already exist in your program.
Doug White of Arlington, Texas uses his 1200XL as an aid in designing and testing loudspeakers. His article Equivalence appeared in the February 1989 Antic.
Listing 1: SHELSORT.BAS Download
Listing 2: SHELSORT.LST Download / View
Listing 3: VRENAME.LST Download / View