Locate. (utility program for color adjustment and cursor control)
by Farid Ahmad
Programmers who use BASIC are familiar with the various tricks for positioning text on a screen. Most use various PRINT statements and a lot of trial and error, but now there's a better way.
Locate is short machine language routine for the 64 that provides BASIC programmers with two commands for cursor positioning and text color adjustment. Although the program is written in BASIC, it stores its machine language subroutine in a BASIC REM statement. This technique provides the speed of machine language with the convenience of BASIC.
Preparing Locate
Notice that Locate's first line contains a REM followed by 73 periods. It looks strange, but it's important not to change this line in any way. Since this line fills two screen lines, enter it without a space between the line number and the word REM. If you include the space, your cursor will drop down a line after you type the final period. Should that occur, cursor back up to the line and press Return.
Locate is written entirely in BASIC. To help avoid typing errors, use The Automatic Proofreader to enter the program. See "Typing Aids" elsewhere in this section. Be sure to save a copy of the program when you've finished.
Load and run the program. Now list it again. You'll see that Locate's first line number is missing and the line itself contains a number of meaningless characters. Next, delete lines 30-90. Delete a line by cursoring to an empty spot on the screen, typing 30, and then pressing Return. Do this for lines 30-90. Finally, the program will consist of only two lines: the unnumbered line 10, which contains the meaningless symbols, and line 20. Save this two-line program with the usual SAVE command.
Using the Program
Before starting to write a BASIC program, load this two-line program. Now start writing your program with a line number greater then 20. When you want to position text, the following two commands are available.
SYS AT, row, column, color
The row may be from 0-24 and the column from 0-39. The color may be from 0-15, the usual Commodore colors. This parameter will effect the color of following text. Values outside these limits will produce an ILLEGAL QUANTITY ERROR message.
For example, SYS AT, 5, 0, 1 will position the cursor at the beginning of the sixth screen line and change text color to white. The color parameter is optional. If you don't want to set the text color, omit this parameter and the preceding comma. SYS AT, 5, 0 will position the cursor at the same place but will not change the text color. Spaces after the commas are also optional. Any PRINT statement that follows this or the following command will begin printing at the cursor position that you have indicated.
SYS CL, row, column, color
The syntax of this command is exactly the same as that of SYS AT, but it clears the screen before positioning the cursor. For example, SYS CL, 0, 0, 1 will clear the screen, position the cursor at the upper left corner, and set text color to white. As with SYS AT, the color parameter is optional.
Other Considerations
The machine language routine in Locate is relocatable. It will work correctly even if the start of BASIC pointer has been changed. The only condition is that the two lines of Locate be the first two lines of the program. The line numbers, however, may be changed with a renumbering utility.
The variables AT and CL are defined by Locate as the starting addresses of the Locate routines. These variables must not be used elsewhere in the program, or the program might crash.
If you want to use Locate with an existing program, you'll need a merge utility, such as the MERGE command in METABASIC. Renumber your program so that the first line number is greater than 20. Then merge it with Locate.
A Demonstration
Demo is a demonstration program that illustrates some of the ways Locate commands can be used and modified. It's also written in BASIC and should be entered with Proofreader.
With a merge program, you can combine the two programs later. If you don't have a merge program, load and run Proofreader, load the two-line Locate program, and then enter Demo, starting with line 30.
The Technique
The technique used with Locate is a convenient way of adding short machine language routines to BASIC programs. A few things must be kept in mind, however. First, the ML routine must not contain the number 0. This is because 0 is reserved by the BASIC interpreter to mark the end of a BASIC line. Since 0 is the ML instruction for BRK, it's seldom required. It may be needed, however, as the argument of an ML command. It's usually possible to get around this problem. For example, to load the X register with 0, use LDX#1, :DEX.
Note the quotation mark at the beginning of the first line. If this is not included, the ML numbers will be interpreted as BASIC tokens. This will still work, but the resulting list may look a bit strange. The quote itself may also produce some problems. Once the quote is encountered, some of the graphic characters might be interpreted as control characters. When the program is listed, the list may change colors, or the screen may be cleared. This is irritating, but it doesn't do any harm to the program. The best way to avoid this problem is to list the program from the second (or higher) line. Whether or not the quote is used, once the ML is in the REM statement, do not reenter the line by pressing Return over it. This will enter the line incorrectly and garble the ML. If the quote has been used, the line may look the same after reentering, but the damage may still have been done. This is because many graphic symbols have more than one POKE code, and the BASIC editor always stores the lower value in memory. So if your ML contains the instruction JSR $AEFD, reentering the line will change this to JSR$ AEBD, as $FD and $BD are the POKE codes for the same graphic symbol.
Locate prevents this from happening by including enough delete characters in the line to delete the line number. Thus, the line cannot be reentered by mistake.