Apple I Reference Manual January 1978 APPLE i Reference ManualAPPLE II Reference Manual January 1978 APPLE Computer Inc, 10260 Bandley Dr. Cupertino, CAAPPLE II Reference Manual TABLE OF CONTENTS A. GETTING STARTED WITH YOUR APPLE Ws ssee2sace 1 NOERED 8. 9. 10, " 12. 13, B. APPLE II INTEGER BASIC . BASIC Commands "1 12, { Wineraniy Registration cure 4 3. Check for Shipping Damage . Power Up PNeReaonn ). Data Read/Save Subroutines Unpacking ... APPLE Il Speaks Several Languages. APPLE Integer BASIC .... Running Your First and Second Programs Running 16K Startrek . Loading a Program Tape...... Breakout and Color Demos Tapes . . Breakout and Color Demos Program Listings ... How to Play Startrek ...... Loading HIRES Demo Tape . BASIC Operators BASIC Functions ........ BASIC Statements ..... a Special Control and Editing Table A — Graphics Colors ‘Special Controls and Features . BASIC Error Messages .... H Simplified Memory Map ......... Aas Simple Tone Subroutines . High Resolution Graphics Subroutines and Listings .... C. APPLE Il FIRMWARE ......... 1 2. si! 4 5, 13, Additional BASIC Program Examples ... . Rod's Color Pattern (4K)... Pong (4K) . Color Sketch (4K) .. |. Mastermind (8K) ............. Biorhythm (4k)... Dragon Maze (4K). =2aoge ‘System Monitor Commands . Control and Editing Characters . . Special Controls and Features . Annotated Monitor and Dis-assembler Listing ... Binary Floating Point Package..... 94 6. Sweet 16 Interpreter Listing . 96 7. 6502 Op Codes ....... 100 D. APPLE I! HARDWARE ...... 106 1. Getting Started with Your APPLE II Board. 107 APPLE II Switching Power Supply. 110 2 3, Interfacing with the Home TV .... 112 4, Simple Serial Output. 114 5, Interfacing the APPLE — Signals, Loading, Pin [Connections Minin MMMM 122 6. Memory — Options, Expansion, Map, Address i 133 7. System Timing . 140 8. Schematics 141GETTING STARTED WITH YOUR APPLE II Unpacking Don't throwaway the packing material. Save it for the unlikely event that you may need to return your Apple II for warrantee repair. Tf you bought an Apple II Board only, see hardware section in this manual on how to get started. You should have received the following: 1. Apple II system including mother printed circuit board with specified amount of RAM memory and 8K of ROM memory, switching power supply, keyboard, and case assembly. 2. Accessories Box including the following: a. This manual including warranty card. b. Pair of Game Paddles c. A.C. Power Cord d. Cassette tape with "Breakout"on one side and "Color Demos" on the other side. e. Cassette recorder interface cable (miniature phone jack type) 3. If you purchased a 16K or larger system, your accessory box should also contain: a. 16K Startrek game cassette with High Resolution Graphics Demo ("HIRES") on the flipside. b. Applesoft Floating Point Basic Language Cassette with an example program on the other side. c. Applesoft reference manual 4, In addition other items such as a vinyl carrying case or hobby board peripherial may have been included if specifically ordered as "extras". Notify your dealer or Apple Computer, Inc. immediately if you are missing any items. Warranty Registration Card Fill this card out immediately and completely and mail to Apple in order to register for one year warranty and to be placed on owners club mailing list. Your Apple II's serial number is located on the bottom near the rear edge. You model number is: A2SOOMMX MM is the amount of memory you purchased. For Example: A2S9998x is an 8K Byte Apple II system.Check for Damage Inspect the outside case of your Apple for shipping damage. Gently lift up on the top rear of the lid of the case to release the lid snaps and remove the lid. Inspect the inside. Nothing should be loose and rattling around. Gently press down on each integrated circuit to make sure that each is still firmly seated in its Socket. Plug in your game paddies into the Apple II board at the socket marked "GAME 1/0" at location J14. See hardware section of this manual for additional detail. The white dot on the connector should be face forward. Be careful as this connector is fragile. Replace the lid and press on the back top of it to re-snap it into place. Power Up First, make sure that the power ON/OFF switch on the rear power supply panel on your Apple II is in the "OFF" position. Connect the A.C. power cord to the Apple and to a 3 wire 12D volt A.C, outlet. Make sure that you connect the third wire to ground if you have only a two conductor house wiring system. This ground is for your safety if there is an internal failure in the Apple Power supply, minimizes the chance of static damage to the Apple, and minimizes RFI problems. Connect a cable from the video output jack on the back of the Apple to a TV set with a direct video input jack. This type of set is commonly called a "Monitor". If your Set does not have a direct video input, it is possible to modify your existing set. Write for Apple's Application note on this. Optionally you may connect the Apple to the antenna terminals of your TV if you use a modulator. See additional details in the hardware section of this manual under “Interfacing with the Home TV". Now turn on the power switch on the back of the Apple. The indicator light (it's not a switch) on the keyboard should now be ON. If not, check A.C. connections. Press and release the "Reset" button on the keyboard. The following should happen: the Apple's internal speaker should beep, an asterisk ("*") prompt character should appear at the lower left hand corner of your TV, and a flashing white square should appear just to the right of the asterisk. The rest of the TV screen will be made up of radom text characters (typically question marks). If the Apple beeps and garbage appears but you cannot see an "*" and the cursor, the horizontal or vertical height settings on the TV need to be adjusted. Now depress and release the "ESC" key, then hold down the “SHIFT key while depressing and releasing the P key. This should clear your TV screen to all black. Now depress and release the "RESET" key again. The "*" prompt character and the cursor should return to the lower left of your TV screen.Apple Speaks Several Languages The prompt character indicates which language your Apple is currently jin, The current prompt character, an asterisk ("*"), indicates that you are in the "Monitor" language, a powerful machine level language for advanced programmers, Details of this language are in the "Firmware" section of this manual. Apple Integer BASIC Apple also contains a high level English oriented language called Integer BASIC, permanently in its ROM memory. To switch to this Janguage hold down the "CTRL" key while depressing and releasing the "B" key. This is called a control-B function and is similiar to the use of the shift key in that it indicates a different function to the Apple. Control key functions are not displayed on your TV screen but the Apple still gets the message. Now depress and release the "RETURN" key to tell Apple that you have finished typing a Tine on the keyboard. A right facing arrow (">") called a caret will now appear as the prompt character to indicate that Apple is now in its Interger BASIC language mode. Running Your First and Second Program Read through the next three sections that include: 1, Loading a BASIC program Tape 2. Breakout Game Tape 3. Color Demo Tape Then load and run each program tape. Additional information on Apple II's interger BASIC is in the next section of this manual. Running 16K Startrek If you have 16K Bytes or larger memory in your Apple, you will also receive a "STARTREK" game tape. Load this program just as you did the previous two, but before you "RUN" it, type in "HIMEM: 16384" to set exactly where in memory this program is to run.LOADING A PROGRAM TAPE INTRODUCTION This section describes a procedure for loading BASIC programs successfully into the Apple II, The process of loading a program is divided ‘into three section; System Checkout, Loading a Tape and What to do when you have Loading Problems. They are discussed below. When loading a tape, the Apple II needs a signal of about 2 1/2 to 5 volts peak-to-peak. Commonly, this signal is obtained from the "Monitor" or “earphone” output jack on the tape recorder. Inside most tape recorders, this signal is derived from the tape recorder's speaker. One can take advantage of this fact when setting the volume levels. Using an Apple Computer pre-recorded tape, and with all cables disconnected, play the tape and adjust the volume to a loud but un-distorted level. You will find that this volume setting will be quite close to the optimum setting. Some tape recorders (mostly those intended for use with hi-fi sets) do not have an “earphone” or high-level "monitor" output. These machines have outputs labeled "line output" for connection to the power amplifier. The signal levels at these outputs are too low for the Apple II in most cases. Cassette tape recorders in the $49 - $59 range generally have ALC (Automatic Level Control) for recording from the microphone input. This feature is useful since the user doesn't have to set any volume controls to obtain a good recording. If you are using a recorder which must be adjusted, it will have a level meter or a little light to warn of excessive recording levels. Set the recording level to just below the level meter's maximum, or to just a dim indication on the level lamp. Listen to the recorded tape after you've saved a program to ensure that the recording is "loud and clear". Apple Computer has found that an occasional tape recorder will not function properly when both Input and Output cables are plugged in at the same time, This problem has been traced to a ground loop in the tape recorder itself which prevents making a good recording when saving a program. The easiest solution is to unplug the "monitor" output when recording. This ground loop does not ‘influence the system when loading a pre-recorded tape.Tape recorder head alignment is the most common source of tape recorder problems. If the playback head is skewed, then high frequency information on pre-recorded tapes is lost and all sorts of errors will result. To confirm that head alignment is the problem, write a short program in BASIC. >10 END is sufficient. Then save this program. And then rewind and Toad the program. If you can accomplish this easily but cannot load pre-recorded tapes, then head alignment problems are indicated. Apple Computer pre-recorded tapes are made on the highest quality professional duplicating machines, and these tapes may be used by the service technician to align the tape recorder's heads. The frequency response of the tape recorder should be fairly good; the 6 KHz tone should be not more than 3 db down from a 1 KHz tone, and a 9 KHz tone should be no more than 9 db down. Note that recordings you have made yourself with mis-aligned heads may not not play properly with the heads properly aligned. If you made a recording with a skewed record head, then the tiny magnetic fields on the tape will be skewed as well, thus playing back properly only when the skew on the tape exactly matches the skew of the tape recorder's heads. If you have saved valuable programs with a skewed tape recorder, then borrow another tape recorder, load the programs with the old tape recorder into the Apple, then save them on the borrowed machine. Then have your tape recorder properly aligned. Listening to the tape can help solve other problems as well. Flaws in the tape, excessive speed variations, and distortion can be detected this way. Saving a program several times in a row is good insurance against tape flaws. One thing to listen for is a good clean tone lasting for at least 3 1/2 seconds is needed by the computer to “set up" for proper loading. The Apple puts out this tone for anout 19 seconds when saving a program, so you normally have 6 1/2 seconds of leeway. If the playback volume is too high, you may pick up tape noise before getting to the set-up tone. Try a lower playback volume. SYSTEM CHECKOUT A quick check of the Apple II computer system will help you spot any problems that might be due to improperly placed or missing connections between the Apple II, the cassette interface, the Video display, and the game paddles. This checkout procedure takes just a few seconds to perform and is a good way of insuring that everything is properly connected before the power is turned on.1. POWER TO APPLE - check that the AC power cord is plugged into an appropriate wall socket, which includes a "true" ground and is connected to the Apple II. 2. CASSETTE INTERFACE - check that at least one cassette cable double ended with miniature phone tip jacks is connected between the Apple II cassette Input port and ‘the tape recorder's MONITOR plug socket. 3. VIDEO DISPLAY INTERFACE - a) for a video monitor - check that a cable connects the monitor to the Apple's video output port. b) for a standard television - check that an adapter (RF modulator) is plugged into the Apple II (either in the video output (K 14) or the video auxillary socket (J148), and that a cable runs between the television and the Adapter's output socket. 4, GAME PADDLE INTERFACE - if paddles are to be used, check that they are connected into the Game 1/0 connector (J14) on the right-hand side of the Apple II mainboard. 5. POWER ON - flip on the power switch in back of the Apple II, the "power" indicator on the keyboard will light. Also make sure the video monitor (or TV set) is turned on. After the Apple II system has been powered up and the video display presents a random matrix of question marks or other text characters the following procedure can be followed to load a BASIC program tape: 1, Hit the RESET key. An asterick, "*", should appear on the lefthand side of the screen below the random text pattern. A flashing white cursor will appear to the right of the asterick. 2. Hold down the CTRL key, depress and release the B key, ‘then depress the "RETURN" key and release the "CTRL" key. A right facing arrow should appear on the lefthand side of the screen with a flashing cursor next to it. If it doesn't, repeat steps 1 and 2. 3. Type in the word "LOAD" on the keyboard. You should see the word in between the right facing arrow and the flashing cursor. Do not depress the "RETURN" key yet. 4. Insert the program cassette into the tape recorder and rewind it. 5. If not already set, adjust the Volume control to 59-70% maximum. If present, adjust the Tone control to 89-1pp% maximum.6. Start the tape recorder in "PLAY" mode and now depress the "RETURN" key on the Apple IT. 7. The cursor will disappear and Apple II will beep in a few seconds when it finds the beginning of the program. If an error message is flashed on the screen, proceed through the steps listed in the Tape Problem section of this paper. 8. A second beep will sound and the flashing cursor will reappear after the program has been successfully loaded ‘into the computer. 9. Stop the tape recorder. You may want to rewind the program tape at this time. 10. Type in the word "RUN" and depress the "RETURN" key. The steps in loading a program have been completed and if everying has gone satisfactorily the program will be operating now. LOADING PROBLEMS Occasionally, while attenpting to load a BASIC program Apple IT beeps and a memory full error is written on the screen. At this time you might wonder what is wrong with the computer, with the program tape, or with the cassette recorder. Stop. This is the time when you need to take a moment and checkout the system rather than haphazardly attempt- ing to resolve the loading problem. Thoughtful action taken here will speed in a program's entry. If you were able to successfully turn on the computer, reset it, and place it into BASIC then the Apple II is probably operating correctly. Before describing a procedure for resolving this loading problem, a discussion of what a memory full error is in order. The memory full error displayed upon loading a program indicates that not enough (RAM) memory workspace is available to contain the incoming data. How does the computer know this? Information contained in the beginning of the program tape declares the record length of the program. The computer reads this data first and checks it with the amount of free memory. If adequate workspace is available program loading continues. If not, the computer beeps to indicate a problem, displays a memory full error statement, stops the loading procedure, and returns command of the system to the key- board. Several reasons emerge as the cause of this problem.Memory Size too Sma11 Attempting to load a 16K program into a 4K Apple II will generate this kind of error message. It is called loading too large of a program. The solution is straight forward: only load appropriately sized programs into suitably sized systems. Another possible reason for an error message is that the memory pointers which indicate the bounds of available memory have been preset to a smaller capacity. This could have happened through previous usage of the "HIMEN :" and “LOMEN :" statements. The solution is to reset the pointers by BC (CTRL 8) command. Hold the CTRL key down, depress and release the B key, then depress the RETURN key and release the CTRL key. This will reset the system to max- ‘imum capacity. Cassette Recorder Inadjustment If the Volume and Tone controls on the cassette recorder are not properly set a memory full error can occur. The solution is to adjust the Volume to 59-79% maximum and the Tone (if it exists) to 89-19% max imum.* ‘A second common recorder problem is skewed head azimuth. When the tape head is not exactly perpendicular to the edges of the magnetic tape some of the high frequency data on tape can be skipped. This causes missing bits in the data sent to the computer. Since the first data read is record length an error here could cause a memory full error to be generated because the length of the record is inaccurate. The solution: adjust tape head azimuth, It is recommended that a competent technician at a local stereo shop perform this operation. Often times new cassette recorders will not need this adjustment. *Apple Computer Inc. has tested many types of cassette recorders and so far the Panasonic RQ-309 DS (Tess than $4.9) has an excellent track record for program loading.Tape Problems A memory full error can result from unintentional noise existing in a program tape. This can be the result of a program tape starting on its header which sometimes causes a glitch going from a nonmagnetic to magnetic recording surface and is interpreted by the computer as the record length. Or, the program tape can be defective due to false erasure, imperfections in the tape, or physical damage. The solution is to take a moment and listen to the tape. If any imperfections are heard then replacement of the tape is called for. Listening to the tape assures that you know what a "good" program tape sounds like. If you have any questions about this please contact your local dealer or Apple for assistance. If noise or a glitch is heard at the beginning of a tape advance the tape to the start of the program and re-Load the tape. Dealing with the Loading Problem With the understanding of what a memory full errér is an efficient way of dealing with program tape loading problems is to perform the following procedure: Check the program tape for its memory requirements. Be sure that you have a large enough system. 2. Before loading a program reset the memory pointers with the B, (contro? B) command. 3. In special cases have the tape head azimuth checked and adjusted. 4. Check the program tape by listening to it. a) Replace it if it is defective, or b) start it at the beginning of the program. 5. Then re-LOAD the program tape into the Apple II. In most cases if the preceeding is followed a good tape load will result. UNSOLVED PROBLEMS If you are having any unsolved loading problems, contact your nearest local dealer or Apple Computer Inc.BREAKOUT GAME TAPE PROGRAM DESCRIPTION Breakout is a color graphics game for the Apple II computer. The object of the game is to "knock-out! all 160 colored bricks from the playing field by hitting them with the bouncing ball. You direct the ball by hitting it with a paddle on the left side of the screen. You control the paddle with one of the Apple's Game Paddle controllers. But watch out: you can only miss the ball five times! There are eight columns of bricks. As you penetrate through the wall the point value of the bricks increases. A perfect game is 729 points; after five balls have been played the computer will display your score and a rating such as "Very Good". "Terrible!", etc. After ten hits of the ball, its speed with double, making the game more difficult. If you break through to the back wall, the ball will rebound back and forth, racking up points. Breakout is a challenging game that tests your concentration, dexterity, and skill. REQUIREMENTS This program will fit into a 4k or greater system. BASIC is the programming language used. PLAYING BREAKOUT 1. Load Breakout game following instructions in the "Loading a BASIC Program from Tape" section of this manual. 2. Enter your name and depress RETURN key. 3. If you want standard BREAKOUT colors type in Y or Yes and hit RETURN. The game will then begin. 4. If the answer to the previous questions was N or No then the available colors will be displayed. The player will be asked to choose colors, represented by a number from f to 15, for background, even bricks, odd bricks, paddle and ball colors. After these have been chosen the game will begin. 105. At the end of the game you will be asked if they want to play again. A Y or Yes response will start another game. AN or No will exit from the program, NOTE: A game paddle (156k ohm potentiometer) must be connected ‘to PDL (8) of the Game 1/0 connector for this game. COLOR DEMO TAPE PROGRAM DESCRIPTION COLOR DEMO demonstrates some of the Apple II video graphics capabilities. In it are ten examples: Lines, Cross, Weaving, Tunnel, Circle, Spiral, Tones, Spring, Hyperbola, and Color Bars. These examples produce various combinations of visual patterns in fifteen colors on a monitor or television screen. For example, Spiral combines colorgraphics with tones to produce some amusing patterns. Tones illustrates various sounds that you can produce with the two inch Apple speaker, These examples also demonstrate how the paddle inputs (PDL(x)) can be used to control the audio and visual displays. Ideas from this program can be incorporated into other programs with a little modification. REQUIREMENTS 4K or greater Apple IT system, color monitor or television, and paddles are needed to use this program. BASIC is the pro- gramming language used. wwBREAKOUT GAME PROGRAM LISTING PROCEAY LISTING EB THEM YS (He HL PRIA E202 R/282 AL LSSeStL/2 Sy PRINT *S00RE = 1 PRINT + PORE 94,2 Salsas t9 58 COLOR FLO kb 16088) DPE (-16226)- PE PRINT Gg BALLS Leu TH am, sf: PRIAT « FOR I=L 10 + SSB A F eB fa 1128 THE I EH 1s SOE Pay CORSA ae IF 22 k 7p TF SERMEL08 THEN 195 PRENT “7008, 1 THRN sBbaHetote 148 PRIAT “FAIR, Test DLL NT “GRRE Kisii: cot 9 PRINT *LNVRLID, 55 INPUT * cou Ge 2 OR BIS BER = PRL BDU) TF 8 TE tu 2,39 aT I C04 S51 MND 4 10-39 STEP 4 12COLOR DEMO PROGRAM LISTING PROGRAM LISTING 18 BOR CC4)s PORE 2123s RE * J HOD 22s FUR 3A: PE 4158s PORE 5,165 0 129% CULOR=T He a7s ALOT 2 PORE 6,8: PME 7,22: POE 2D) 8D 37, UD) REG SS HEAT 8,16 PORE 5,082: FORE 16, anus taaaes ato 38 485: POME Lis PORE 12,288 Wo Si0edd= aH Ca E134 PORE 14,198: POE, HE 16,248 PORE 1? 18,1982 PORE 13,42 1 FBR Ast 16 OWE 28,76: PORE 21,2: PRE 4 22, PME 2,38 428 COLRSCC Finke Se RL AB PRINT 74K COLOR SEHOS*s PRIM PRINT *L LIMES": PRIAT "2 OOS Shy PRINT "3 BEAVIS ie a AU GL PRIA °6 SP SPIES os FRONT HLIN 1,5 AT GOSUR 648s YIN 1,3 AT Fs 68 688 818 MAW 19941 AT Je SOB 64 He,2 87 2s Gos 618 ‘5 PRINT *9 BYPEREOL 10 coLee BRS" 2 HEMET 628 COLER= HO C14ie FOR Tete 10 8 STF 2 wud be, Fa ies GSB 2,5 BT Js GU 648 "HICH DEMO VOWLD YOU LIKE G39 SLIM 1,0 AT J: SOSU8 648: HUI Re TET aD 128 THEN od AT Ie GOSUB 648: SERT Is B10 Wied: GOTO 38 SSR LEGHRs GOTO 688 We Tetsi aa 254 648 KeLo7oL ace ehetbo7 BL 2767 AM POL DMB PORE @, x POKE JL HID 2562 POKE 24, SoouR 24g L/QSbH: LL 2s SETUR TSG Ls GUSUR 28@es SI5UE eas GoTo 268 ALIN Te 13 788 T= GHD ANGE TeTvbeSeIaeoe CLETETI POL (BYE PORE ls PORE LK 10 2 1 FOWE 24, (2553413 CALL & to 72 ns Am 8 MENT Te SOU nee 2 aOTd aie B88 NeLeteList-tskéemets YL Re AT ets MUON LLAL2 A WIM Lz aT AD 18: FOR 1 FOR As TD G9; OOLOREI= 98 CERDDM BS CCEAY ZY 1: FLOT Ruts HEMT, bes GOTO 168 CALL 93% ‘ie Jets FU AOD @ THEN Goss see: save 2 COLE RAD C16): RA 2,59 AT Fe OWROR HAB (16s VLIM 8, 39 Me RET mee OF PEEK <-L63B8)C128 THEN RETR 1 POME 1525002 POF + Bt a16 15 SHORT DESCKIFTION OF HOW TO FLAY STAKTREN ON THE THOS IS" "SEAKCH AMD) PESTRUY RISGION. THE QKUECY 18.10 LOND-KawGe SSENSEFOR INFORHATION AB TO MERE KLINGON ¢K) BKE* OVE TO" THAT GUNGmANT + ES SRESRMESUE beter ek crag ae, 1S IMSTHEY CaN BE FIRED AGTORATIENCLY TP: THEY. ave Fs 6+ @ AND 10 ALL G3VE INFORMATION ABOUT THE STATUS OF THE’ SHI 9 SETS THE SHIELD ENERGY/AVATLANLE ENERGY RATIO. Setiale at 0 teat 6 eee THIS EXPLANATION was WRITTEN HY ELMOOD 14LOADING THE HI-RES DEMO TAPE PROCEDURE 1, Power up system - turn the AC power switch in the back of the Apple II on. You should see a random matrix of question marks and other text characters. If you don't, consult the operator's manual for system checkout pro- cedures. 2. Hit the RESET key. On the left hand side of the screen you should see an’ asterisk and a flashing cursor next to ‘it below the text matrix. Insert the HI-RES demo tape into the cassette and rewind it. Check VoTume (59-79%) and Tone (8)-199%) settings. Type in “COD.FFFR" on the Apple II keyboard. This is the address range of the high resolution machine language sub- program. It extends from $C) to $FFF. The R tells the computer to read in the data. Do not depress the "RETURN" key yet. Start the tape recorder in playback mode and depress the "RETURN" key. The flashing cursor disappears. A beep will sound after the program has been read in. STOP the tape recorder. Do not rewind the program tape yet. Hold down the "CTRL" key, depress and release the B key, then depress the "RETURN" key and release the "CTRL" key. You should see a right facing arrow and a flashing cursor. The BC command places the Apple into BASIC initializing ‘the memory pointers. Type in "LOAD", restart the tape recorder in playback mode and hit the "RETURN" key. The flashing cursor disappears. This begins the loading of the BASIC subprogram of the HI-RES demo tape. A beep will sound to indicate the program is being loaded. 1510. Ne 12. A second beep will sound, and the right facing arrow will reappear with the flashing cursor. STOP the tape recorder. Rewind the tape. Type in "HIMEM:8192" and hit the "RETURN" key. This sets up memory for high resolution graphics. Type in "RUN" and hit the "RETURN" key. The screen should clear and momentarily a HI-RES demo menu table should appear, The loading sequence is now completed. ‘SUMMARY OF HI-RES DEMO TAPE LOADING 1, RESET 2. Type in CO.FFFR 3. Start tape recorder, hit RETURN 4. Asterick or flashing cursor reappear Be (CTRL 8) into BASIC 5. Type in "LOAD", hit RETURN 6. BASIC prompt (7) and flashing cursor reappear. Type in "HIMEN:8192", hit RETURN 7. Type in "RUN, hit RETURN 8. STOP tape recorder, rewind tape. 16APPLE II INTEGER BASIC . BASIC Commands . BASIC Operators . BASIC Functions . BASIC Statements . Special Control and Editing . Table A — Graphics Colors . Special Controls and Features . BASIC Error Messages Simplified Memory Map . Data Read/Save Subroutines . Simple Tone Subroutines . High Resolution Graphics Additional BASIC Program ExamplesBASIC COMMANDS Conmands are executed inmediately; they do not require line numbers.Most Statenents (see Basic Statements Section) may also be used as commands. Remember to press Return key after each command so that Apple knows that you have finished that line. Multiple conmands (as opposed to statements) on same line separated by a": "are NOT allowed. COMMAND NAME AUTO rum AUTO. rund, mame DEL mont DEL meen, mum? HIMEM: expe GOTO expr LIST LIST veut LIST runt, mune Sets automatic line numbering mode. Starts at line number mun and increments line numbers by 10. To exit AUTO mode, type a control X*, then type the letters "MAN" and press the return key. Same as above execpt increments line numbers by number nun?. Clears current BASIC variables; undimensions arrays. Program is unchanged. Continues program execution after a stop froma control C*. Does not change variables. Deletes line number Deletes program from Tine numbermwn? through line number mum? Sets debug mode that will display variable var every- time that it is changed along with the line number that caused the change. (NOTE: RUN conmand clears DSP mode so that DSP conmand is effective only if program is continued by a CON or GOTO conmand.) Sets highest memory location for use by BASIC at location specified by expression exzin decimal. : may not be increased without destroying program. is automatically set_at maximum RAM memory when BASIC is entered by a control B*. Causes immediate jump to line number specified by expression expr. Sets mixed color graphics display mode. Clears screen to black. Resets scrolling window. Displays 40x49 squares in 15 colors on top of screen and 4 lines of text at. bottom. Lists entire program on screen. Lists program Tine number mun?. Lists program Tine number nun? through Tine number num. 18LOAD expr. way NeW NO _DSP. NO_TRACE RUN cape SAVE, TEXT TRACE Reads (Loads) a BASIC program from cassette tape. Start tape recorder before hitting return key. Two beeps and a">" indicate a good Toad. "ERR" or "MEN" FULL ERR" message indicates a bad tape or poor recorder performance. Similar to HIMEM: except sets lowest memory location available to BASIC. Automatically set at 2748 when BASIC is entered with a control B*. Moving LOMEM: destroys current variable values. Clears AUTO line numbering mode to al] manual line numbering after a control C* or control X*. Clears (Scratches) current BASIC program. Clears DSP mode for variable van. Clears TRACE mode. Clears variables to zero, undimensions all arrays and executes program starting at lowest statement line number. Clears variables and executes program starting at Tine number specified by expression expr. Stores (saves) a BASIC program on a cassette tape. Start tape recorder in record mode prior to hitting return key. Sets all text mode. Screen is formated to display alpha-numeric characters on 24 lines of 4 characters each. TEXT resets scrolling window to maximum. Sets debug mode that displays line number of each statement as it is executed. Control characters such as control X or control C are typed by holding down the CTRL key while typing the specified letter. This is similiar to how one holds down the shift key to type capital letters. Control characters are NOT displayed on the screen but are accepted by the computer. For example, type several control G's. We will also use a superscript C to indicate a control character as in x‘. 19BASIC Operators Symbol Sample Statement Prefix Operators () 19 X= 44(5 + x) + 29 X= 14485 - 39 ALPHA = = (BETA 42) NOT 49 IF A NOT B THEN 209 Arithmetic Operators + 66 Y= x43 * 70 LET DOTS=A*B*N2 / 80 PRINT GAMMA/S Noo 90 x = 12 MOD 7 199 X = x MoD(v#2) + lg P=L+G . 120 xv4 = H-D = 130 HEIGHT=15 140 LET SIZE=7*5 150 A(8) = 2 155 ALPHAS = “PLEASE” Explanation Expressions within parenthesis ( ) are always evaluated first. Optional; +1 times following expression. Negation of following expression. Logical Negation of following expression; if expression is true (non-zero), 1 if expression is false (zero). Exponentiate as in X°, NOTE: + is shifted letter N. Multiplication, NOTE: Implied multi- plication such as (2 + 3)(4) is not allowed thus N2 in example is a variable not N* 2. Divide Modulo: Remainder after division of first expression by second expression. Add Substract Assignment operator; assigns a value to a variable. LET is optionalRelational and Logical Operators The numeric values used in logical evaluation are “true” if non-zero, "false" if zero. Symbol Sample Statement = 169 IF DE THEN 500 = 179 IF AS(1,1)= "y" THEN 590 #or<> 180 IF THEN 500 # 199 TF THEN 500 ALPHA #X¥Y AS # "NO™ > 200 IF ADB THEN GO TO 50 < 210 IF THEN 108 ‘A+1 220 IF ADB THEN 100 « 230 IF THEN 200 At <=B-6 AND 24g IF A>B AND C not allowed with strings. Expression "is greater than" expression. Expression "is less than" expression. Expression "is greater than or equal to” expression. Expression "is less than or equal to” expression. Expression 1 "and" expression 2 must both be "true" for statements to be true. If either expression 1 or expression 2 is "true", statement is "true".BASIC FUNCTIONS Functions return a numeric result. of expressions. parenthesis signs. FUNCTION NAME ABS (expr) ASC (ated) LEN (etrs) POL (expr) PEEK (expr) RND (expr) SCRN(exprt, expr?) SGN (expr) 390 PRINT ABS(X) They may be used as expressions or as part PRINT is used for examples only, other statenents may be used. Expressions followina function name must be enclosed between two 310 PRINT ASC("BACK") 320 PRINT ASC(BS) 330 PRINT ASC(BS(4,4)) 335 PRINT ASC(BS(Y¥)) 340 PRINT LEN(B$) 35 PRINT PDL(X) 36 PRINT PEEK(X) 370 PRINT RND(X) 380 PRINT SCRN (X1,Y1) 39D PRINT SGN(X) 22 Gives absolute value of the expression expr. Gives decimal ASCII value of designated string variable stré. If more than one character is in designated string or sub-string, it gives decimal ASCII value of first character. Gives current length of designated string variable otrS;i.e., number of characters. Gives number between 6 and 255 corres~ ponding to paddle position on game paddle number designated by expression exp and must be legal paddle (,1,2,0r 3) or else 255 is returned. Gives the decimal value of number stored of decimal memory location specified by expression expr. For MEMORY locations above 32676, use negative number; i.e., HEX location FFFG is -16 Gives random number between @ and (expression expr -1) if expression expr is positive; if minus, it gives random number between J and (expression expr +1). Gives color (number between 0 and 15) of screen at horizontal location designated by expression expr? and vertical location designated by expression expr? Range of expression cavr! is P) to 39. Range of expression expr? is P) to.39 if in standar mixed colorgraphics display mode as set by GR command or f to 47 if in all color mode set by POKE -16304 ,P: POKE - 16392.. Gives sian (not sine) of expression expr i.e., -1 if expressionespr is negative, zero zero and +1 ifezpr is positive.‘ATEMENTS Each BASIC statement must have a line number between @ and 32767. Variable names must start with an alpha character and may be any number of alpha~ numeric characters up to 199. Variable names may not contain buried any of the following words: AND, AT, MOD, OR, STEP, or THEN. Variable names may not begin with the letters END, LET, or REM. String variables names must end with a $ (dollar sign). Multiple statements may appear under the same line number if separated by a : (colon) as long as the total number of characters in the Tine (including spaces) is less than approximately 159 characters Most statements may also be used as commands. BASIC statements are executed by RUN or GOTO conmands.. NAME CALL expr 1 CALL-936 Causes execution of a machine level Janguage subroutine at decimal memory location specified by expression expr Locations above 32767 are specified using negative numbers; i.e., location in example 1¢ is hexidecimal number $FC53 30 cOLOR=12 In standard resolution color (GR) graphics mode, this coniand sets screen TV color to value in expression expr in the range @ to 15 as described in Table A. Actually expressioneapy may be in the range @ to 255 without error message since it is implemented as if it were expressionespr MOD 16. DIM vari (expr1) 50 DIM A(2H) ,8(19) The DIM statement causes APPLE II to ers (expre) 60 DIM BS(30) reserve memory for the specified variables. var? (expr3) 7@ DIM C (2) For number arrays APPLE reserves Tegal: approximately 2 times exprbytes of memory 80 DIM A(30) limited by available memory. For string Leaal: arrays -str& (expe) must be in the range of 85 DIM C(1992) 1 to 255. Last defined variable may be redimensioned at any time; thus, example in line is illegal but 85 is allowed. DSP var Leqal: Sets debug mode that DSP variable var each y 5 time it changes and the line number where the Mleqal: change occured. 190 DSP AX,B 192 DSP ABS 104 DSP A(5) Legal: 195 ‘A(5): DSP A 23NAME exys1 TOexpr? StEbeapes ® GOSUE expr GOTO expr HLIN capt, epe2MTexprs Note: EXAMPLE 11 END 11p FOR L=p to 39 120 FOR X=¥1 TO Y3 139 FOR 1=39 TO 1 15 GOSUB 199 *J2 149 GOSUB 5p 162 GOTO 200 170 GOTO ALPHA+1O9 189 GR 199 GR: POKE -16392,9 200 HLIN 9,39 AT 20 219 HLIN Z,2+6 AT T HLIN B, 19 AT @ is a DESCRIPTION Stops program execution. Sends carriage return and ">" BASIC prompt) to screen. Begins FOR...NEXT loop, initializes variable var to value of expression expr then increments it by amount in expression expr each time the corresponding "NEXT" statement is encountered, until value of expression eepr2is reached. If STEP oxprs is omitted, a STEP of +1 is assumed. Negative numbers are allowed. Causes branch to BASIC subroutine starting at legal line number specified by expression expr Subroutines may be nested up to 16 levels. Causes inmediate jump to Tegal line number specified by expression expr. Sets mixed standard resolution color raphics mode. Initializes COLOR = p {btack) for. top 4x49 of Screen and sets scrolling window to lines 21 through 24 by 49 characters for four lines of text at bottom of screen. Example 190 sets all color mode (49x48 field) with no text at bottom of screen. In standard resolution color graphics mode, this conmand draws a horizontal line of a predefined color (set by COLOR=) starting at horizontal position defined by expression expr and ending at position expr2 at vertical position defined by expression expr3 .expri andeapr2 must be in the range of P to 39 and expri < = apne . cxprs be in the range of ® to 39 (or 9 to 47 if not in mixed mode). horizontal line at the top of the screen extending from left corner to center of screen and HLIN 20,39 AT 39 is a horizontal 1i center to right corne ne at the bottom of the screen extending from P. 24If expression 220 IF A> B THEN THEN atatementt PRINT A INPUT vat, vare, otré IN expr LET LIST mont, mn’ NEXT var?, vane NO_DSP va NO TRACE 230 IF X= THEN C=1 249 IF A#19 THEN GosuB 209 250 IF AS(1,1)# "Y" THEN 100 Mlegal: 200 IF L>5 THEN 59: ELSE 69 Legal: 270 IF L>5 THEN 50 GO TO 6p 280 INPUT X,Y,Z(3) 290 INPUT "AMT", OLLR 300 INPUT "Y or W » AS 319 INE 6 320 INE Y+2 330 INE 0 349 LET X=5 350 IF _X>6 THEN LIST 50 360 NEXT I 370 NEXT J,k 380 NO DSP 1 399 NO TRACE 25 If expression is true (non-zero) then execute statement, if false do not execute statement, If statement is an expression, then a GOTO expr type of statement is assumed to be implied. The "ELSE" in example 260 is illegal but may be implemented as shown in example 279. Enters data into memory from 1/0 device. If number input is expected, APPLE wil output "2"; if string inout is expected no "?" will be outputed. Multiple numeric inputs to same statement may be separated by a comma or a carriage return. String inputs must be separated by a carriage return only. One pair of "" may be used inmediately after INPUT to output prompting text enclosed within the quotatfor marks to the screen. Transfers source of data for subsequent INPUT statements to peripheral 1/0 slot (1-7) as specified as by expression expr. Slot ® is not addressable from BASIC. IN#D (Example 330) is used to return data source from peripherial 1/0 to keyboard connector. Assignment operator. "LET" is optional Causes program from line number num? through line number mun2 to be displayed on screen. Increments corresponding "FOR" variable and oops back to statement following "FOR" until variable exceeds limit. Turns-off DSP debug mode for variable Turns-off TRACE debug modePLOT exprt, expr? POKE expr, expr? 0? PRINT var7, var, str PRE expr RETURN 499 PLOT 15, 25 490 PLT XV,¥V 420 POKE 29, 49 430 POKE 7*256, XMOD255 449 POP 459 PRINT Li 460 PRINT L1, X2 479 PRINT “AMT=";DX 48) PRINT AS3BSs 499 PRINT 492 PRINT "HELLO" 494 PRINT 2+3 500 PRE 7 510 REN REMARK 529 RETURN 539 1FX= 5 THEN RETURN 26 In standard resolution color graphics, this conmand plots a small square of a predefined color (set by COLOR=) at horizontal location specified by expression expr? in range to 39 and vertical location specified by expressioncepr2 in range to 39 (or to 47 if in all graphics mode) NOTE: PLOT ® @ is upper left and PLOT 39, 39 (or PLOT 39, 47) is lower right corner. Stores decimal number defined by expression expr2 in range of DB 255 at decimal memory location specified by expression expri Locations above 32767 are specified by negative numbers. "POPS" nested GOSUB return stack address by one. Outputs data specified by variable var or string variable stré starting at current cursor location. If there is not trailing "," or "3" (Ex 459) a carriage return will be generated. Commas (Ex. 469) outputs data in 5 left justified columns. Semi-coton (Ex. 470) inhibits print of any spaces. Text imbedded in" " will be printed and may appear multiple times. Like INA, transfers output to 1/0 slot defined by expression expr PRE ® is video output not 1/0 slot p. No action. A11 characters after REM are treated as a remark until terminated by a carriage return. Causes branch to statement following Tast GOSUB; i.e., RETURN ends a subroutine. Do not confuse "RETURN" statement with Return key on keyboard.TAB expr TEXT TRACE VLIN expel, expr? AT expr VTAB expr 530 TAB 24 549 TAB 1+24 559 IF AgB THEN TAB 2p 550 TEXT 560 TEXT: CALL-936 570 TRACE 580_IFN > 32000 THEN TRACE 599 VLIN B, 39AT15 690 VLIN Z,Z+6ATY 619 VTAB 18 62D VTAB 7+2 27 Moves cursor to absolute horizontal position specified by expression expr in the range of 1 to 49. Position is left to right Sets all text mode. Resets scrolling window to 24 Tines by 49 characters. Example 560 also clears screen and homes cursor to upper left corner Sets debug mode that displays each Vine number as it is executed. Similar to HLIN except draws vertical line starting at expr? and ending at expr? at horizontal position exprs. Similar to TAB. Moves cursor to absolute vertical position specified by expression expr in the range 1 to 24. VTAB 1 is top line on screen; VTAB24 is bottom.SPECIAL CONTROL AND EDITING CHARACTERS “Control” characters are indicated by a super-scripted "C" such as G°. They are obtained by holding down the CTRL key while typing the specified letter. Control characters are NOT displaved on the TV screen. B° and C must be followed by a carriage return. Screen editing characters are indicated by a sub-scripted "E" such as De. They are obtained by pressing and releasing the ESC key then typing specified letter. Edit characters send information only to display screen and does not send data to memory. For example, UC moves to cursor to right and copies text while Ag moves cursor to right but does not copy text. CHARACTER DESCRIPTION OF ACTION RESET key Immediately interrupts any program execution and resets computer. Also sets all text mode with scrolling window at maximum, Control is transfered to System Monitor and Apple prompts with a "*" (asterisk) and a bell. Hitting RESET key does NOT destroy existing BASIC or machine language program. Control B If in System Monitor (as indicated by a "*"), a control B and a carriage return will transfer control to BASIC, scratching (killing) any existing BASIC program and set HINEM: to maximum installed user memory and LONEM: to 2048. Control ¢ If in BASIC, halts program and displays Tine number where stop occurred*. Program may be continued with a CON conmand. If in System Monitor, (as indicated by "* control C and a carraige Feturn will enter BASIC without killing current program. Control G Sounds bel (beeps speaker) Control K Backspaces cursor and deletes any overwritten characters from computer but not fron screen. Apply supplied keyboards have special key "«" on right side of keyboard that provides this functions without using contro? button. Control a Issues Tine feed only Contro? V Compliment to H®, Forward spaces cursor and copies over written characters. Apple keyboards have ">" key on Fight side which also performs this function. Control x Immediately deletes current line. * If BASIC program is expecting keyboard input, you will have to hit carriage return key after typing control C. 28CHARACTER Table A: Note: DESCRIPTION OF ACTION Move cursor to right Move cursor to left Move cursor down Move cursor up Clear text from cursor to end of Tine Clear text from cursor to end of page Home cursor to top of page, clear text to end of page. APPLE II COLORS AS SET BY COLOR = Colors may vary depending on TV tint (hue) setting and may also be changed by adjusting trimmer capacitor C3 on APPLE II P.C. Board. d = Black 8 = Brown 1 - Magenta 9 = Orange 2 = Dark Blue 19 = Grey 3 = Light Purple 11 = Pink 4 = Dark Green 12 = Green 5 = Grey 13 = Yellow 6 = Medium Blue 14 = Blue/Green 7 = Light Blue 15 = White 29Special Controls and Features Hex. BASIC Example Display Mode Controls p50 cps) ps2 p53 p54 p55 C056 p57 1) 20 30 40 50 68 i) 8p POKE POKE POKE POKE POKE POKE POKE POKE TEXT Mode Controls 99 POKE 32,L1 920 9921 9922 9923 9924 9925 9032 FC5B Fca2 -16304,9 -16303,p -16392,9 -16301 9 163009 -16299,9 16298 }9 1629739 190 POKE 33,W1 119 POKE 34,71 120 POKE 35,81 130 CH=PEEK(36) 149 POKE 36,CH 159 TAB(CH+1) 160 CV=PEEK(37) 170 POKE 37,CV 180 VTAB(CV+1) 199 POKE 59,127 200 POKE 59,255 219 CALL -936 220 CALL -958 Description Set color graphics mode Set text mode Clear mixed graphics Set mixed graphics (4 lines text) Clear display Page 2 (BASIC commands use Page 1 only) Set display to Page 2 (alternate) Clear HIRES graphics mode Set HIRES graphics mode Set left side of scrolling window to location specified by L1 in range of # to 39. Set window width to amount specified by WI. LIHWI<49. Wp Set window top to line specified by Tl in range of 9 to 23 Set window bottom to line specified by Bl in the range of @ to 23. BI>T1 Read/set cusor horizontal position in the range of @ to 39. If using TAB, you must add "1" to cusor position read value; Ex. 140 and 150 perform identical function. Similar to above. Read/set cusor vertical position in the range p to 23. Set inverse flag if 127 (Ex. 199) Set normal flag if 255(Ex. 209) (@) Home cusor, clear screen (Fe) Clear from cusor to end of page 30Hex FCOC 230 CALL -868 FC66 249 CALL -922 FC7g 259 CALL -912 Miscellaneous cp3p 360 X=PEEK(-16336) 365 POKE -16336,0 cope 379 X=PEEK(-16384) cpp 380 POKE -16368,0 p61 399) X=PEEK(16287) C62 499 X=PEEK(-16286) 063 419 X=PEEK(-16285) oss 420 POKE -16296,0 959 430 POKE -16295,0 cosa 449 POKE -16294,0 cos8 450 POKE -16293,0 case 460 POKE -16292,9 psp 470 POKE -16291,0 OSE 480 POKE -16290,0 cOSF 490 POKE -16289,0 BASIC Example 31 Description (Eg) Clear from cusor to end of line (0°) Line feed Scroll up text one Tine Toggle speaker Read keyboard; if X>127 then key was pressed. Clear keyboard strobe - always after reading keyboard. Read PDL(9) push button switch. If X>127 then switch is "on". Read PDL(1) push button switch. Read PDL(2) push button switch. Clear Game 1/0 ANO output Set Game 1/0 ANP output Clear Game 1/0 ANI output Set Game 1/0 ANI output Clear Game 1/0 AN2 output Set Game I/0 AN2 output Clear Game 1/0 AN3 output Set Game 1/0 AN3 outputAPPLE II BASIC ERROR MESSAGES. *** SYNTAX ERR *** > 32767 ERR HH > 285 ERR *** BAD BRANCH ERR *** BAD RETURN ERR wee BAD NEXT ERR *** 16 GOSUBS ERR *** 16 FORS ERR *+ NO END ERR ‘++ MEM FULL ERR *** TOO LONG ERR *** DIM ERR *** RANGE ERR #48 STR OVFL ERR +#* STRING ERR RETYPE LINE Results from a syntactic or typing error. A value entered or calculated was less than 32767 or greater than 32767. A value restricted to the range G to 255 was outside that range. Results from an attempt to branch to a non- existant line number. Results from an attempt to execute more RETURNS than previously executed GOSUBs. Results from an attempt to execute a NEXT state- ment for which there was not a corresponding FOR statement. Results from more than 16 nested GOSUBs. Results from more than 16 nested FOR loops. The last statement executed was not an END. The memory needed for the program has exceeded the memory size allotted. Results from more than 12 nested parentheses or more than 128 characters in input line. Results from an attempt to DIMension a string array which has been previously dimensioned. An array was larger than the DIMensioned value or smaller than 1 or HLIN,YLIN, PLOT, TAB, or VTAB arguments are out of range. The number of characters assigned to a string exceeded the DIMensioned value for that string. Results from an attempt to execute an illegal string operation. Results from illegal data being typed in response ‘to an INPUT statement. This message also requests that the illegal item be retyped. 32‘Simplified Memory Map. FFFF 64K Monitor and BASIC Routines in ROM 56K Future enhancement or user supplied 77 PROMS pope -- oon Peripheral 1/0 48k xx -1XX — —— User specified RAM memory size (HIMEM: ) User Workspace (LOMEM: ) TRF t-~ - a Screen Memory 406 ~ — 1 lg Internal Workspace 33READ/SAVE DATA SUBROUTINE INTRODUCTION Valuable data can be generated on the Apple II computer and sometimes it is useful to have a software routine that will allow making a permanent record of this information. This paper discusses a simple subroutine that serves this purpose. Before discussing the Read/Save routines a rudimentary knowledge of how variables are mapped into memory is needed. Numeric variables are mapped into memory with four attributes. Appearing in order sequentually are the Variable Name, the Display Byte, the Next Variable Address, and the Data of the Variable. Diagramatically this is represented as: WN DsP NVA DATA(g) DATA(1) DATA(N) 1 my hy byt VARIABLE NAME - up to 100 characters represented in memory as ASCII equi- valents with the high order bit set. DSP (DISPLAY) BYTE - set to 91 when DSP set in BASIC initiates a process that displays this variable with the Tine number every time it is changed within a program. NVA (NEXT VARIABLE ADDRESS) - two bytes (first low order, the second high order) indicating the menory location of the next variable. DATA ~ hexadecimal equivalent of numeric information, represented in pairs of bytes, low order byte first. 34String variables are formatted a bit differently than numeric ones. These variables have one extra attribute - a string terminator which desig- nates the end of a string. A string variable is formatted as follows: VN DSP NVA DATA(9) DATA(1),... DATA(n) st 1 hy hg baa VARIABLE NAME - up to 199 characters represented in memory as ASCII equi- valents with the high order bit set. OSP (DISPLAY) BYTE - set to #1 when DSP set in BASIC, initiates a process that displays this variable with the Tine number every time it is changed within a program. NVA (NEXT VARIABLE ADDRESS) - two bytes (first low order, the second high order) indicating the memory location of the next variable. DATA - ASCII equivalents with high order bit set. STRING TERMINATOR (ST) - none high order bit set character indicating END of string. There are two parts of any BASIC program represented in memory. One is the location of the variables used for the program, and the other is the actual BASIC program statements. As it turns out, the mapping of these within memory ‘is a straightforward process. Program statements are placed into memory starting at the top of RAM memory* unless manually shifted by the "HIMEM:" command, and are pushed down as each new (numerically larger) line numbered statement is entered into the system. Figure la illustrates this process diagramatically. Variables on the other hand are mapped into memory starting at the lowest position of RAM memory - hex $899 (2948) unless manually shifted by the "LOMEM :" command. They are laid down from there (see Figure 1b) and continue until all the variables have been mapped into memory or until they collide with the program statements. In the event of the latter case a memory full error will be generated *Top of RAM memory is a function of the amount of memory. 16384 will be the value of "HINEM:" for a 16K system. 35The computer keeps track of the amount of memory used for the variable table and program statements. By placing the end memory location of each into $CC-CD(294-205) and $CA-CB(293-204), respectively. These are the BASIC memory program pointers and their values can be found by using the statements in Figure 2. CM defined in Figure 1 as the location of the end of the variable tape is equal to the number resulting from statement a of Figure 2. PP, the program pointer, is equal to the value resulting from statement 2b. These statements (Figure 2) can then be used on any Apple II computer to find the limits of the program and variable table. FINDING THE VARIABLE TABLE FROM BASIC First, power up the Apple II, reset it, and use the CTRL 8 (control B) command to place the system into BASIC initializing the memory pointers. Using the statements from Figure 2 it is found that for a 16K Apple II CM is equal to 2948 and PP is equal to 16384. These also happen to be the values of LOMEN and HIMEN: But this is expected because upon using the BC command both memory pointers are initialized indicating no program statements and no variables. To illustrate what a variable table looks Tike in Apple IT memory suppose we want to assign the numeric variable A ($CI is the ASCII equivalent of a with the high order bit set) the value of -1 (FF FF in hex) and then examine the memory contents. The steps in this process are outlined in example I. Variable A is defined as equal to -1 (step 1). Then for convenience another variable - B - is defined as equal to @ (step 2). Now that the variable table has been defined use of statement 2a indicates that CM is equal to 296f (step 3). LOMEN has not been readjusted so it is equal to 248. Therefore the variable table resides in memory from 2048 ($82 hex) to 2069 ($89C). Depressing the "RESET" key places the Apple II into the monitor mode (step 4). We are now ready to examine the memory contents of the variable table. Since the variable table resides from $899 hex to $89C hex typing in "899.89C" and then depressing the "RETURN" key (step 5) will list the memory contents of this range. Figure 3 lists the contents with each memory location labelled. Examining these contents we see that Cl is equal to the variable name and is the memory equivalent of "A" and that FF FF is the equivalent of -1. From this, since the variable name is at the beginning of the table and the data is at the end, the variable table representation of A extends from $899 to $805. We have then found 36‘the memory range of where the variable A is mapped into memory. The reason for this will become clear in the next section. READ/SAVE ROUTINE The READ/SAVE subroutine has three parts. The first section (lines 9-10) defines variable A and transfers control to the main program. Lines 20 through 26 represents the Write data to tape routine and lines 39-38 represent the Read data from tape subroutine. Both READ and SAVE routines are executable by the BASIC "GOSUB X" (where X is 20 for write and 30 is for read) command. And as listed these routines can be directly incorporated into almost any BASIC program for read and saving a variable table. The limitation of these routines is that the whole part of a variable table is processed so it is necessary to maintain exactly the dimension statements for the variables used. The variables used in this subroutine are defined as follows: A= record length, must be the first variable defined CH= the value obtained from statement a of figure 2 LY» is equal to the value of "LOMEM: Nominally 2948 SAVING A DATA TABLE The first step in a hard copy routine is to place the desired data onto tape. This is accomplished by determining the length of the variable table and setting A equal to it. Next within the main program when it is time to write the data a GOSUB2P statement will execute the write to tape process. Record length, variable A, is written to tape first (line 22) followed by the desired data (line 24). When this process is completed control is returned to the main program. READING A DATA TABLE The second step is to read the data from tape. When it is time a GOSUB3) statement will initiate the read process. First, the record length is read in and checked to see if enough memory is available (line 32-34). If exactly the same dimension statements are used it is almost guaranteed that there will be enough memory available. After this the variable table is read in (Tine 34) and control is then returned to the main program (line 36). If not enough menory is available then an error is generated and control is returned to the main pro- gram (line 38) 37EXAMPLE OF READ/SAVE USAGE The Read/Save routines may be incorporated directly into a main program. To illustrate this a test program is listed in example 2. This program dimensions a variable array of twenty by one, fills the array with numbers, writes the data table to tape, and then reads the data from tape listing the data on the video display. To get a feeling for how to use these routines enter this program and explore how the Read/Save routines work. concLusion Reading and Saving data in the format of a variable table is a relatively straight forward process with the Read/Save subroutine listed in figure 4. This routine will increase the flexibility of the Apple II by providing a permanent record of the data generated within a program. This program can be reprocessed. The Read/Save routines are a valuable addition to any data processing program. 38Unused Memory Varn vay | vare Pr} Pp | Pg +++ Prog | Pot | | feove CM End of 1. beginning HIMEM, $890 Variable of Nax Systen Table Program Size : SS Nan b a Variable Data BASIC Program Figure 7 a) PRINT PEEK(204) + PEEK(295)*256 > PP b) PRINT PEEK(292) + PEEK(293)*256 > CM Figure 2 809 891 8p2 893 8f4 895 896 897 898 899 BPA 8pB BPC cll op a ee a i 9 99 Op HoL OW VAR SP NVA DATA VAR DSP NVA DATA NAM NAM 4 Figure 3 $899.89C rewritten with labelling 39FIGURE 4b READ/SAVE PROGRAM COMMENTS a) This must be the first statement in the program. It is initially 0, but if data is to be saved, it will equal the length of the data base. 10 GOTO 199 This statement moves command to the main program. 20 PRINT “REWIND TAPE THEN Lines 20-26 are the write data to tape START TAPE RECORDER": subroutine. INPUT "THEN HIT RETURN" , BS 22 ASCM-LM: POKE 69,4: POKE 61,8: POKE 62,5: POKE 63,8: CALL -307 24 POKE 69,LM MOD 256: Writing data table to tape POKE 61, LM/256: POKE 62, CM MOD 256: POKE 63, CM/256: CALL -397 26 PRINT "DATA TABLE SAVED": Returning control to main program. RETURN 30 PRINT "REWIND THE TAPE Lines 30-38 are the READ data from tape THEN START TAPE RECORDER": subroutine. a “AND HIT RETURN", B 32 POKE 69,4: POKE 61,8: POKE 62,5: POKE 63,8 CALL -259 34 IF Ac THEN 38: : Checking the record length (A) for memory IF P>HM THEN 38: CN=P: requirements if everything is satisfactory POKE 69, LM MOD 256: the data is READ in. POKE 61, LM/256: POKE 62, CM MOD 256: POKE 63, CN/256: CALL 259 36 PRINT "DATA READ IN": RETURN 38 PRINT "#*#T00 MUCH DATA Returning control to main program. BASE***" : RETURN NOTE: CM, LM and A must be defined within the main program. 40Mezcal 2 ae 3. >PRINT PEEK (204) + PEEK (205) * 256 computer responds with= 2060 es * 5 *899.80C Computer responds with: 9800- Cl 9p 86 9B FF FF C2 Op 9898 PC 98 BP OP OD Define variable A=-1, then hit RETURN Define variable B=, then hit RETURN Use statement 2a to find the end of ‘the VARIABLE TABLE Hit the RESET key, Apple moves into Monitor mode. ‘Type in VARIABLE TABLE RANGE and HIT the RETURN KEY. Example 1 aLdust ore 1 oro se ‘2 REA WRITE GATA 10 TAPE ROUTIRE 22 ReC-Lts POLE 68,42 POKE 6 8s POKE 62,5 PORE 63,88 CFL aa 24 BOE 6@,LK MOD 256: FOFE 61 AN AS6: PORE 62,0 HOD 256 + POE 6308256: CALL 287 TRH RN ERD OTA ROUTINE 4 PORE 64: POKE 61,82 POME 62,5: PORE 63,0: CRLL 269 IF BCG THEN SespoLtehe IF PD THER SbsCH=¥s PORE 6@LN RED 5b: FOHE 61 L256: POKE 62 NOB 256s PORE 63,08/256 ORL 259 6 FTN ‘PRINT ‘ese TOO NUCH ORTH BASE + 0 eg 4,428) 105 FOR Ist 10 ie exh Example 2 16@ PRINT "20 WUMBERS GENERATED 8 PRINT "WO WE AE. GOTRG TO SAVE THE DATAY: PREKT "WH YOU ARE R ROY START THE RECOROER 16 ECR D nes FRPUT “RAD HIT RETURN” $ 130 CHUL 926 PREAT MOD Ta 10 TRE: Game a 135 PRINT HOW THE DADA 15 SAVED* HOF we NT “HOW ME ARE GONE TO CLEAR THE N28) TABLE AAD HERD THE 02 1 Fa THEE "iC 6G PRINT "Now START TPE TAROT “WD THEW AIT RETURA Aft 15 PRINT "A 178 6OSUB 38 180 PRINT "ALL THE ORTR RERD Un 198 FOR H=1 10 28: PRINT *H("ads Se HCD HEAT 195 PRIKT "THIS 1S THE END* a EH 42‘A SIMPLE TONE SUBROUTINE INTRODUCTION Computers can perform marvelous feats of mathematical computation at well beyond the speed capable of most human minds. They are fast, cold and accurate; man on the other hand is slower, has emotion, and makes errors. These differences create problems when the two interact with one another. So to reduce this problem humanizing of the computer is needed. Humanizing means incorporating within the computer procedures that aid in @ program's usage. One such technique is the addition of a tone subroutine. This paper discusses the incorporation and usage of a tone subroutine within the Apple II computer. Tone Generation To generate tones in a computer three things are needed: a speaker, a circuit to drive the speaker, and a means of triggering the circuit. As it happens the Apple II computer was designed with a two-inch speaker and an efficient speaker driving circuit. Control of the speaker is accomplished through software. Toggling the speaker is a simple process, a mere PEEK - 16336 ($C939) in BASIC statement will perform this operation. This does not, however, Produce tones, it only emits clicks. Generation of tones is the goal, so describing frequency and duration is needed. This is accomplished by toggling the speaker at regular intervals for a fixed period of time. Figure 1 lists a machine language routine that satisfies these requirements. Machine Language Program This machine language program resides in page 9 of memory from $92 (2) to $14 (20). $0 (99) is used to store the relative period (P) between toggling of the speaker and $01 (91) is used as the memory location for the value of relative duration (D). Both P and 0 can range in value from $90 (0) to SFF (255). After the values for frequency and duration are placed into memory a CALL2 statement from BASIC will activate this routine. The speaker is toggled with the machine language statement residing at $92 and then a 43delay in time equal to the value in $9 occurs. This process is repeated until the tone has lasted a relative period of time equal to the duration (value in $91) and then this program is exited (statement $14). Basic Program The purpose of the machine language routine is to generate tones controllable from BASIC as the program dictates. Figure 2 lists the appropriate statement that will deposit the machine language routine into memory. They are in the form of a subroutine and can be activated by a GOSUB 32009 statement. It is only necessary to use this statement once at the beginning of a program. After that the machine Janguage program will remain in memory unless a later part of the main program modifies the first 20 locations of page 9. After the GOSUB 32999 has placed the machine language program into memory it may be activated by the statement in Figure 3. This statement is also in the form of a GOSUB because it can be used repetitively in a program. Once the fre- quency and duration have been defined by setting P and D equal to a value between 9 and 255 a GOSUB 25 statement is used to initiate the generation of a tone. The values of P and D are placed into $99 and $P1 and the CALL2 command activates the machine language program that toggles the speaker. After the tone has ended control is returned to the main program. The statements in Figures 2 and 3 can be directly incorporated into BASIC Programs to provide for the generation of tones. Once added to a program an infinite variety of tone combinations can be produced. For example, tones can be used to prompt, indicate an error in entering or answering questions, and supplement video displays on the Apple II computer system. Since the computer operates at a faster rate than man does, prompting can be used to indicate when the computer expects data to be entered. Tones can be generated at just about any time for any reason in a program. The programmer's imagination can guide the placement of these tones. CONCLUSION The incorporation of tones through the routines discussed in this paper will aid in the humanizing of software used in the Apple computer. These routines can also help in transforming a dull program into a lively one. They are relatively easy to use and are a valuable addition to any program. 44aooe- FF gagi- FF eege- AD Ba5- 88 Bagé- DB gaee- C6 BaGR- FE aeec- CR Beap- og SGGF- AS Bii- 4c BGi4- 66 22? 922 3606 LDR scaaa DEY a4 BNE sagac aL bec #01 88 BEO = saa14 DEX Fé BNE ¢aG05 85 Lox $80 o2 au JMP $g002 RTS FIGURE 1. Machine Language Program adapted from a program by P. Lutas. 32600 POE 2,173: PUKE 3,48: POKE 492 PORE 5,425: PUKE 6,289 1 POE 74 POLE 8,188: POKE Sole POKE 18,248 32605 POE HLS: PORE te,2nes POH 1,2 POKE 14,246: PORE 15 be POLE toes PIKE 2 PORE 18,22 PORE 15,0 POKE 20,9: RETR FIGURE 2. BASIC "POKES" FIGURE 3. GOSUB 45High-Resolution Operating Subroutines These subroutines were created to make programming for igh-Resolution Graphics easier, for both BASIC and machine- language programs. These subroutines occupy 757 bytes of memory and are available on either cassette tape or Read-Only Memory (ROM), This note describes use and care of these subroutines. There are seven subroutines in this package. With these, a programmer can initialize High-Resolution mode, clear the screen, plot a point, draw a line, or draw and animate a predefined shape. on the screen, There are also some other general-purpose subroutines to shorten and simplify programming. BASIC programsscan accéss these subroutines by use of ,the CALL statement, and can pass information by using the POKE state- ment. There are special entry points for most of the subroutines that will perform the same functions as the original subroutines without modifying any BASIC pointers or registers. For machine language programming, a JSR to the appropriate subroutine address vill perform the same function as a BASIC CALL. In the following subroutine descriptions, all addresses Riven will be in decimal, The hexadecimal substitutes will be preceded by a dollar sign ($). All-entzry points given are for the cassette tape subroutines, which load into addresses Cf to FFF (hex). Equivalent addresses for the ROM subroutines will be in italic type face. 46INIT Initializes High-Resolution Graphics mode, From BASIC: CALL 3972 (or CALL -12288) From machine language: JSR $COPp (or JSR $D999) This subroutine sets High-Resolution Graphics mode with a 288 x 160 trix of dots in the top portion of the screen and four lines of text in the bottom portion of the screen, INIT also clears the screen. CLEAR Clears the screen. From BASIC: CALL 3886 (or CALL -12274) From machine language: JSR $C#E (or JSR $D99E) This subroutine clears the High-Resdlution screen without resetting the High-Resdlution Graphics mode, PLOT Plots a point on the screen, From BASIC: CALL 3788 (or CALL -11586) From machine language: JSR $C7C (or JSR $D7C) This subroutine plots a single point on the screen, The X and Y coodinates of the point are passed in locations 898, 801, and 862 from BASIC, or in the A, X, and Y registers from machine language. The Y¥ (vertical) coordinate can be from a7 °High-Resloution Operating Subroutines PLOT (continued) (top of screen) to 159 (bottom of screen) and is passed in location 882 or the A-register; but the X (horizontal) coordinate can range from (left side of screen) to 279 (right side of screen) and must be split between locations 86 (X MOD 256) and 861 (1/256).or, from machine language, between registers X (X LO) and Y (X HI), The color of the point to be plotted must be set in location 812 ($32C). Four colors are possible: § is BLACK, 85 ($55) 4s GREEN, 176 ($AA) is VIOLET, and 255 ($FF) WHITE. POSN Positions a point on the screen. From BASIC: CALL 3761 (or CALL -11599] From machine language: JSR $C26 (or JSR $Dg26) This subroutine does all calculations for a PLOT, but does not plot a point (it leaves the screen unchanged). This is useful when used in conjumction with LINE or SHAPE (described later). To use this subroutine, set up the X and Y coordinates just the = as for PLOT, The color in location 812 ($32€) is ignored. LINE Draw a line on the screen. 48High-Resolution Operating Routines LINE Draws # line on the screen. From BASIC: CALL 3786 (or CALL -11574) From machine language: JSR $C95 for JSR $b995) This subroutine draws a line from the last point PLOTted er POSN'ed to the point specified. One endpoint is the last point PLOTted or POSN*ted; the other endpoint is passed in the same manner as for a PLOT or POSN. The color of the line is set in ‘location 812 ($32C). After the line is drawn, the new endpoint becomes the base endpoint for the next line drawn. SHAPE Draws a predefined shape on the screen. From BASIC: CALL 3865 (or CALL -11555) From machine language: JSR $DBC (or JSR $D1BC) This subroutine draws a predefined shape on the screen at the point previously PLOTted or POSN'ed, The shape is defined by a table..of vectors in memory.(How to create a vector table will be described later). The starting address of this table should be passed in locations 804 and 805 from BASIC or in“the Y and X registers from machine language. The color of the shape should be passed in location 28 ($1C). There are two special variables that are used only with shapes: the scaling factor and the rotation factor, The scaling factor determines the relative size of-the shape. A scaling factor of 49High-Resolution Operating Subroutines (SHAPE (continued) 1 vill cause the shape to be drawn true size, while # scaling factor of 2 will draw the shape double size, etc. The scaling factor is passed in location 896 from BASIC or $32F from machine language. The rotation factor specifies one of 64 possible angles of rotation for the shape. A rotation factor of # will cause the shape to be drawn right-side up, where a rotation factor if 16 will draw the shape rotated 90° clockwise, etc, The rotation factor is passed in location 867 foom BASIC of in the A-register fron machine language. The table of vectors which defines the shape to be drawn is a series of bytes stored in memory. Each byte is divided into three sections, and each section specifies whether or not to plot a point and also a direction to move (up, down, left, or Tight). The SHAPE subroutine steps through the vector table byte by byte, and then through each byte section by section, When it reaches a$$ byte, it is finished. The three sections are arranged in a byte like this: ops o& Move T 1o a v Seas Secten 3 Scchen & cement Ri © Each big ‘pair DD specifies 2’ direction to move, and the two bits P specify whether or not to plot a point before moving. Notice that the last section (most significant bits) does not have a P field, so it can only be # move without plotting, The SHAPE 50