Page 6 Grab-Bag: Part 2
Easy soundtrack for your programs
BY MATT LOVELESS AND MIKE EGGERSHere are two more short, useful programming routines from the Page 6 Grab-Bag (Antic, March 1987). SlowList gives you one-key pause or slowdown of scrolling program listing displays. Musician makes it easy to insert short sound cues into your own programs. These BASIC programs work on all 8-bit Atari computers of any memory size, with disk or cassette.
"Protected" inside your 8-bit Atari is Page 6, 256 bytes of memory from location 1536 to 1791 ($0600 to $O6FF in hexadecimal). Untouched by the operating system or BASIC, Page 6 helps bridge the transition between BASIC and assembly language by providing a safe home for many fast, powerful USR (USeR) functions-machine language routines that can be called from your BASIC program.
Last month, Antic published two of the compact, handy Page 6 routines which were originally released on disk by Synapse Software in 1982. Now here are two more from the Page 6 Grab-Bag. You do not need to know assembly language to use the routines in this article.
SLOWLIST
SlowList lets you pause or slow a program listing by pressing just
one key Normally you'd stop a listing display by pressing [CONTROL] [1],
which can be cumbersome, especially if the listing is complex. With SlowList
you can either halt the listing or just slow it down a bit for easier reading.
Holding down [SELECT] slows the listing and you can adjust the scrolling
speed by changing a few characters in the program. Holding down [START]
halts the listing.
Type in Listing 1, SLOWLIST.BAS, check it with TYPO II and SAVE a copy before you RUN it. Place a disk containing DOS 2 or 2.5 in drive 1. When RUN, slowlist creates a file called SLOWLIST.EXE. Copy it to another disk, rename it AUTORUN.SYS and reboot. Antic disk subscribers will find SLOWLIST.EXE on the monthly disk. Listing 2, SLOWLIST.M65, is the assembly language source code. You do not need to type this in. It is presented to show how the program works.
SlowList works by checking the console buttons during the vertical blank interrupt. If the computer detects a keypress, it sets the flag SSFLAG ($2FF). Changing the contents of location 1619 ($653) changes the listing speed. To turn off the routine, hold down [OPTION] and press [RESET]. To reinstall the utility, just press [RESET].
MUSICIAN
Musician lets you add short tunes to your programs with very little
programming effort. This utility demonstrates how to use BASIC strings
for holding machine language subroutines. Since the BASIC ADR function
returns the address of a string variable, we can easily use it with the
USR function to locate and run the subroutine.
The first step is to create a completely relocatable routine-this means it must not make any references to specific memory locations (such as Page 6) or use any JMP (JuMP) instructions. Make sure your routine ends with an RTS (ReTurn from Subroutine) instruction too, or else it will never find its way back to your BASIC program.
Listing 3, MUSLCIAN.BAS, is a short demonstration program. The utility itself occupies lines 10 through 16- these are the lines you would need in another program. To use MUSICIAN, type in Listing 3, checking with TYPO II and SAVE a copy before you RUN it. The characters in the strings are the ATASCII equivalents of the machine language values of the routines. For example, a value of 65 would appear as an "A" in a string.
If you have trouble typing the special characters in lines 10-16, don't type them in. Listing 4 will create them for you. Type Listing 4, checking it with TYPO II, and SAVE a copy to disk. When RUN, Listing 4 creates these hard-to-type lines, and stores them in a disk file called D:LINES.LST.
To merge the two programs, LOAD "D:MUSICIAN.BAS" then ENTER "D:LINES.LST".
Finally, remember to SAVE the completed program before you RUN it.
Listing 5, MUSICIAN.M65 is the assembly language source code to show you how the program works. You do not need to type it in.
GAME SOUNDS
Musician was designed for BASIC game programmers. It's nice to have
a musical jingle at some point in your game, and this is where Musician
comes in. All you do is give Musician a string containing the notes to
be played.
For example, to play the notes C, D, E, F, G, A, B-in that order-you would pass Musician the string "CDEFGAB" in the variable STRING$. Musician does the rest.
The format for the USR statement is as follows:
X=USR(ADR(MUSIC$),ADR(STRING$),ADR(NT$),ADR(TIME$),VOLUME)
MUSIC$ holds the Musician routine and is 159 bytes long. NT$ contains the decimal values for all the notes, and TIME$ holds the different note durations. (MUSIC$, NT$ and TIME$ are supplied with the routine, so you need not worry about them.)
VOLUME is the same as the fourth number of a SOUND statement and must be between 0 and 15.
STRING$ contains the actual notes to be played, and may contain optional octave, tempo, and duration information. Here are the legal characters:
Notes A through G perform exactly as they do on a standard musical scale. Sharps are represented by a #, as in A#. Flats are denoted by a -, such as A-.
On determines which octave will be used. O is the capital letter "0," not zero, and n is a number between 3 and 6. The middle octave would be O3.
Tn determines the tempo, n being between 1 and 3. It is not the actual tempo, but a number which corresponds to another number found in a table of prestored tempo values. (See table below.)
Ln determines how long the notes will last, with n being between 1 and 4. L1 represents an eighth note, L2 a quarter, L3 a half, and L4 a whole note.
The following table shows the actual durations of the notes in jiffies (60ths of a second) based on both Ln and Tn:
L1 L2 L3 L4
T1 2 4
8 16
T2 5 10 20
40
T3 15 30 60 120
A comma [,] puts a rest or pause in your music, causing Musician to wait for the shortest time allowable in this tempo-two jiffies in T1, five in T2 and 15 in T3.
The semicolon [;] puts a one-twelfth-second delay between notes-just long enough to separate the notes, similar to releasing a key on a piano.
The period [.] ends Musician and returns control back to your BASIC program.
Musician ignores any characters that are not listed above. But it assumes that whatever values you give it are within bounds. If you make a mistake, you may hear some sour notes.
For learning more about assembly language and USR calls, helpful books are Atari Roots by Mark Andrews, published by Datamost, Inc., and De Re Atari, published by Atari. Although neither of these references is currently in print, they are available by mail from various sources. Check the ads in Antic.
Cousins Matt Loveless and Mike Eggers were both in their mid-teens when Page 6 was originally released on disk by Synapse Soft ware in 1982.
Listing 1 SLOWLIST.BAS
Listing 2 SLOWLIST.M65 Download / View
Listing 3 MUSICIAN.BAS Download
Listing 4 LINES.LST (NOT NEEDED)
Listing 5 MUSICIAN.M65 Download / View
On Disk SLOWLIST.EXE Download