System Guide Commodore 128 Personal Computer Hosted at www.commodore.ca or text.commodore.ca SECTION 16 16. Introduction 16.1 ORGANIZATION OF ENCYCLOPAEDIA 16.2 COMMAND AND STATEMENT FORMAT 16.3 GRAPHIC AND SOUND COMMAND FORMAT 16.4 DISK COMMAND FORMAT 16.1 ORGANIZATION OF ENCYCLOPAEDIA This chapter lists BASIC 7.0 language elements and describe how to use those elements. It gives a complete list of the rules (syntax) of Commodore 128 BASIC 7.0, along with a concise description of each. Basic 7.0 includes all the elements of BASIC 2.0. The new commands, state- ments, functions and operators provided in Basic 7.0 are underlined and commands which have been modified are printed in plain and underlined text. The different types of BASIC operations are listed in individual sections, as follows: 1. COMMANDS AND STATEMENTS: the commands used to edit, store and erase programs; and the BASIC program statements used in the numbered lines of a program. 2. FUNCTIONS: the string, numeric and print functions. 3. VARIABLES AND OPERATORS: the different types of variables, legal names, arithmetic operators and logical operators. 4. RESERVED WORDS, SYMBOLS AND ABBREVIATIONS: the words, symbols and abbreviations reserved for use in the BASIC 7.0 language, and which cannot be used for any other purpose. 16.2 COMMAND AND STATEMENT FORMAT +-------------------------------------------------------------------------+ | command name -> AUTO | | ---- | | | | brief description -> Enable/disable automatic line numbering | | command format -> AUTO [line#] | | | | Discussion of This command turns on the automatic line-number- | | format and use -> ing feature. This eases the job of entering pro- | | grams, by automatically typing the line numbers | | for the user. As each program line is entered by | | pressing {return}, the next line number is prin- | | ted on the screen, and the cursor is positioned | | two spaces to the right of the line number. The | | line number argument refers to the desired incre- | | ment between line numbers. AUTO without an argu- | | ment turns off the auto line numbering, as does | | RUN. This statement can be used only indirect | | mode (outside of a program). | | | | EXAMPLES: | | AUTO 10 Automatically numbers program lines | | in increments of 10. | | Example(s) -> AUTO 50 Automatically numbers lines in | | increments of 50. | | AUTO Turns off automatic line numbering. | +-------------------------------------------------------------------------+ The boldface line that defines the format consists of the following elements: DLOAD "program name" [D0,U8] ^ ^ ^ | | | additional arguments keyword argument +-- (possibly optional) The parts of the command or statement that must be typed exactly are shown in capital letters. Words the user supplies, such as the name of a program, are not capitalized. When quote marks (" ") appear (usually around a program name or file name), the user should include them in the appropriate place, according to the format example. KEYWORDS, also called reserved words, appear in upper case letters. Key- words may be typed using the full word or the approved abbreviation (a full list is given in Appendix K). The keyword or abbreviation must be entered correctly or an error will result. The BASIC and DOS error messages are defined in Appendices A and B, respectively. Keywords are words that are part of the BASIC language. The are the central part of a command or statement, and the tell the computer what kind of action to take. These words cannot be used as variable names. A complete list of reserved words is given in Section 20. ARGUMENTS, also called parameters, appear in lower case letters. Arguments complement keywords by providing specific information to the command or statement. For example, the keyword LOAD tells the computer to load a pro- gram while the argument tells the computer which specific program to load. A second argument specifies from which drive to load the program. Arguments include filenames, variables, line numbers, etc. SQUARE BRACKETS [ ] show optional arguments. The user selects any or none of the arguments listed, depending on requirements. The user should not type the SQUARE BRACKETS, which are only there to describe the format. ANGLE BRACKETS < > indicate the user MUST choose one of the arguments lis- ted. The user should not type the ANGLE BRACKETS, which are only there to describe the format. A VERTICAL BAR | seperates items in a list of arguments when the choices are limited to those arguments listed. When the vertical bar appears in a list enclosed by SQUARE BRACKETS, the choices are limited to the items in the list, but the user still has the option not to use any arguments. ELIPSIS ... a sequence of three dots means an option or argument can be repeated more than once. The user should not type the ELIPSIS, which is only there to describe the format. QUOTATION MARKS " " enclose character strings, filenames and other expres- sions. When arguments are enclosed in quotation marks, the quotation marks must be included in the command or statement. Quotations marks are not con- ventions used to describe formats; they are required parts of a command or statement. PARENTHESES ( ) When arguments are enclosed in parentheses, they must be included in the command or statement. Parentheses are not conventions used to describe formats; they are required parts of a command or statement. VARIABLE refers to any valid BASIC variable name, such as X, A$, T%, etc. EXPRESSION refers to any valid BASIC expression, such as A+B+2, 5*(X+3), etc. COMMAS (,) COLONS (:) and SEMICOLONS (;) These MUST be included, they are required parts of the command or statement. 16.3 GRAPHIC AND SOUND COMMAND FORMAT Optional parameters in Graphics and Sound commands are represented like this: [,parameter] When parameters are omitted the comma MUST be included, this is because the parameters are position dependent. You must not, however, include commas after the last specified parameter. EXAMPLE: ENVELOPE n [,atk] [,dec] [,sus] [,rel] [,wf] [,pw] To alter just the rel parameter, use: ENVELOPE n,,,,rel The first three commas mark the positions of atk, dec, sus and the fourth is the comma for rel. The commas for wf and pw must not be entered. In the GRAPHICS commands whenever there is a coordinate specified by (X,Y) it is possible to replace this with a vector (X;Y). In this case: X is the distance (scaled) Y is the angle in degrees (0 = up; 90 = right etc.) For example: LOCATE 160,100 DRAW TO 40;45 will draw a line at 45 degrees of length 40. 16.4 DISK COMMAND FORMAT Optional parameters in disk commands are shown thus: [,parameter] The comma is not required if the parameter is the first after the command itself. If other parameters which require commas are omitted the commas should be omitted too. EXAMPLE: DIRECTORY [Ddrive][Udevice number] [,wildcard] would in full produce: DIRECTORY D0 ON U8,"AB*" To specify only the wild card, no comma is required, i.e. DIRECTORY "AB*" Whenever variables are used in disk commands the MUST be enclosed in paren- theses ( ). For example: DIRECTORY D(DV),(A$) SECTION 17 17. Basic Commands and Statements 17.1 APPEND ------ Append new data to the end of a sequential file. APPEND #logical file number, "filename" [,Ddrive number] [ Udevice] This command opens the file having the specified filename, and positions the pointer at the end of the file. Subsequent PRINT# (write) statements will cause data to be appended to the end of this file. Default values for drive number and device number are 0 and 8 respectively. Variables or Expressions used as filenames must be enclosed within paren- theses. EXAMPLES: APPEND#8,"MYFILE" OPEN logical file 8 called "MYFILE" for appending with subsequent PRINT# statements. APPEND#7,(A$),D0,U9 OPEN logical file named by the variable A$ on drive 0, device number 9 and prepare to APPEND. 17.2 AUTO ---- Enable/disable automatic line numbering. AUTO [line#] This command turns on the automatic line-numbering feature. This eases the job of entering programs, by automatically typing the line numbers for the user. As each program line is entered by pressing {return}, the next line number is printed on the screen, and the cursor is positioned on the second space to the right of the line number. The line number argument refers to the desired increment between line numbers. AUTO without an argument turns off the auto line numbering, as does RUN. This statement can be used only in direct mode (outside of a program). EXAMPLES: AUTO 10 Automatically numbers program lines in increments of 10. AUTO 50 Automatically numbers lines in increments of 50. AUTO Turns off automatic line numbering. 17.3 BACKUP ------ Copy the entire contents from one disk to another on a dual disk drive. BACKUP source Ddrive number TO destination Ddrive number [Udevice] This command copies all the data from the source diskette onto the desti- nation diskette using a dual diskdrive. With the BACKUP command, a new dis- kette can be used without first formatting it. This is because the BACKUP command copies all the information on the diskette, including the format. Because of this, the BACKUP command destroys any information already on the destination disk. Therefore, when backing up onto a previously used disket- te, make sure it contains no programs you mean to keep. As a precaution the computer asks "ARE YOU SURE?" before it starts the operation. Press the {y} key to perform the BACKUP, or any other key to stop it. You should always create a backup of all your disks, in case the original diskette is lost or damaged. Also see the COPY command in paragraph 17.21. The default device number is unit 8. NOTE: This command can be used only with a dual-disk drive. It will not allow you to make copies of protected disks (most prepackaged software). EXAMPLES: BACKUP D0 TO D1 Copies all data from the disk in drive 0 to the disk in drive 1, in dual disk drive unit 8. BACKUP DO TO D1 ON U9 Copies all data from drive 0 to drive 1, in disk drive unit 9. 17.4 BANK ---- Select one of the 16 banks, numbered 0-15. BANK bank number This statement specifies the bank number and corresponding memory configu- ration for the Commodore 128 memory. The default bank is 15. Here is a table of available BANK configurations in the Commodore 128 memory: BANK CONFIGURATION 0 RAM(0) only 1 RAM(1) only 2 RAM(2) only* 3 RAM(3) only* 4 Internal ROM, RAM(0), I/O 5 Internal ROM, RAM(1), I/O 6 Internal ROM, RAM(2), I/O* 7 Internal ROM, RAM(3), I/O* 8 External ROM, RAM(0), I/O 9 External ROM, RAM(1), I/O 10 External ROM, RAM(2), I/O* 11 External ROM, RAM(3), I/O* 12 Kernal and Internal ROM(LOW), RAM(0), I/O 13 Kernal and External ROM(LOW), RAM(0), I/O 14 Kernal and BASIC ROM, RAM(0), Character ROM 15 Kernal and BASIC ROM, RAM(0), I/O * For use on extended C128s with a larger internal memory eg: 256K. In un- expanded machines there is no RAM in these BANKs and 2 echoes 0 and 3 echoes 1. To access a particular bank, type BANK n (n=0-15) and then use PEEK/POKE or SYS. From within the monitor, precede the four-digit hexadecimal number of the address range you are viewing with a hexadecimal digit (0-F). 17.5 BEGIN/BEND ---------- A structure used with IF... THEN ELSE so that you can include several pro- gram lines between the start (BEGIN) and end (BEND) of the structure. Here is the format: IF Condition THEN BEGIN : statement statement statement BEND : ELSE BEGIN statement statement BEND EXAMPLE: 10 IF X=1 THEN BEGIN: PRINT "X=1 is True" 20 PRINT "So this part of the statement is performed" 30 PRINT "When X equals 1" 40 BEND: PRINT "End of BEGIN/BEND structure":GOTO 60 50 PRINT "X does not equal 1":PRINT "The statements between BEGIN/BEND are skipped" 60 PRINT "Rest of Program" If the Conditional (IF... THEN) statement in line 10 is true, the state- ments between the keywords BEGIN and BEND are performed, including all the statements on the same line as BEND. If the (IF... THEN) conditional state- ment in line 10 is False, all statements between the BEGIN and BEND, inclu- ding the ones on the same program line as BEND are skipped, and the program resumes with the first program line immediately following the line con- taining BEND. The BEGIN/BEND essentially treats line 10 through 40 as one long line. The same rules are true if the ELSE:BEGIN clause is specified. If the con- dition is true all statements between ELSE:BEGIN and BEND are performed, including all statements on the same line as BEND. If False, the program resumes with the line immediately following the line containing BEND. 17.6 BLOAD ----- Load a binary file starting at the specified memory location. BLOAD "filename" [,Ddrive number] [Udevice number] [,Bbank number] [,Pstart address] where: * filename is the name of your file * bank number lets you select one of the 16 banks * start address is the memory location where loading begins A binary file is a file, whether a program or data, that has been SAVEd either within the machine language monitor or by the BSAVE command. The BLOAD command loads the binary file into the location specified by the start address. EXAMPLES: BLOAD "SPRITES", B0, P3584 LOADs the binary file "SPRITES" starting in location 3584 in BANK 0. BLOAD "DATA1", D0, U8, B1, P4096 LOADs the binary file "DATA1" into location 4096 (BANK 1) from Drive 0, unit 8. If start address is not specified the file will load at the same address it was saved from. 17.7 BOOT ---- Load and execute a program which has been saved as a binary file. BOOT ["filename"] [,Ddrive number] [Udevice] The command loads an executable binary file and begins execution at the predefined starting address. The default device number is 8 drive 0. EXAMPLES: BOOT BOOT an executable program, (CP/M Plus for example). This is a special case and requires setting up a specific sector on the disk. BOOT"GRAPHICS 1", D0, U9 BOOTs the program "GRAPHICS 1" from unit 9, drive 0 and executes it. Execu- tion begins at the start address of the program (i.e. where it starts loading). 17.8 BOX --- Draw a box at specific position on screen. BOX [color source], x1, y1 [, x2, y2] [,angle] [,paint] where: color source 0=Background color 1=Foreground color 2=Multicolor 1 } 3=Multicolor 2 } Only in Graphics modes 3 and 4 x1, y1 Top left corner coordinate (scaled). x2, y2 Bottom right corner opposite x1, y1 (scaled); default is the PC location. angle Rotation in clockwise degrees; default is zero degrees. paint Paint shape with color 0=Do not paint 1=Paint (default 0) This statement allows the user to draw a rectangle of any size on the screen. Rotation is based on the centre of the rectangle. The pixel cursor (PC) is located at x2, y2 after the BOX statement is executed. The color source number must be zero (0) or one (1) if in standard bit map or a 2 or 3 if in multicolor bit map mode. Also see the GRAPHIC command, in paragraph 17.47, for selecting the appro- priate graphic mode to be used with the BOX color source number. Also see the LOCATE command, in paragraph 17. for information on the pixel cursor. EXAMPLES: BOX 1, 10, 10, 60, 60 Draws the outline of a rectangle. BOX 1, 10, 10, 60, 45, 1 Draws a painted, rotated box (a diamond). DRAW , 30, 90, , 45, 1 Draws a filled, rotated polygon (see note). BOX 1, 20, 20, , ,1 Draws a filled rectangle from 20, 20 to the current pixel cursor. Any parameter can be omitted but you must include a comma in its place, as in the last two examples. NOTE: x2, y2 count as one parameter so only one extra comma is required. Wrapping occurs if the degree is greater than 360, i.e. 360=0 (450=90). 17.9 BSAVE ----- Save a binary file from the specified memory locations. BSAVE "filename" [,Ddrive number] [Udevice number] [,Bbank number], Pstart address TO Pend address+1 where: * filename is the name you give the file * drive number is either 0 or 1 on a dual drive (0 is the default) * device number is the number of disk drive unit (default is 8) * bank number is the number of the bank you specify (0-15) * start address is the starting address where the program is SAVEd from * end address+1 is the end address of the program plus one, i.e. the end address you specify in BSAVE is one byte higher than the end address of the memory range This is the same as the SAVE command in the machine language monitor. EXAMPLES: BSAVE "SPRITE DATA",B0,P3584 TO P4096 Saves the binary file named "SPRITE DATA" starting at location 3584 through 4095 (BANK 0). BSAVE "PROGRAM.SCR",D0,U9,B0,P3182 TO P8000 Saves the binary file named "PROGRAM.SCR" in the memory address range 3182 through 7999 (BANK 0) on drive 0, unit 9. 17.10 CATALOG ------- Displays the disk directory. CATALOG [Ddrive number] [Udevice number] [,wildcard string] The CATALOG command displays the directory on the specified drive just as the directory command. See this command, in paragraph 17.28, for more examples (DIRECTORY and CATALOG are completely interchangeable). EXAMPLE: CATALOG Displays the disk directory on drive 0 of unit 8. 17.11 CHAR ---- Displays characters at the specific position on the screen. CHAR [color source], x, y [,string] [,rvs] This is primarily designed to display characters on a bit mapped screen, but it can also be used on a text screen. Here is what the parameters mean: color source 0=Background color 1=Foreground color 2=Multicolor 1 3=Multicolor 2 x Character column (0-79) (wraps around to the next line in 40-column mode) y Character row (0-24) string String to print RVS Reverse field flag (0=off, 1=on, default=0) Text (alphanumeric strings) can be displayed on any screen at a given loca- tion by the CHAR statement. Character data is read from Commodore 128 character ROM area. The user supplies the x and y coordinates of the star- ting position and the text string to be displayed. Color source and reverse imaging are optional. The string is continued on the next line if it attempts to print past the right hand edge of the screen. When used in text mode, the string printed by the CHAR command works just like a PRINT string, including cursor and color control. These control functions inside the string do not work when the CHAR command is used to display text in bit map mode. Upper/Lower case controls (CHR$(142) or CHR$(14)) also operate in bit map mode. Multicolor characters are handled differently from standard characters. The following table shows how to generate the possible combinations. +------------------------------------------+ | Reverse Flag | | ------------ | | 0(OFF) 1(ON) | +---------------------------+--------------+ | Text | 1 1 | | Color source 0 | | | Background | 2 3 | +---------------------------+--------------+ | Text | 1 0 | | Color source 1 | | | Background | 0 1 | +---------------------------+--------------+ | Text | 2 0 | | Color source 2 | | | Background | 0 2 | +---------------------------+--------------+ | Text | 3 0 | | Color source 3 | | | Background | 0 3 | +---------------------------+--------------+ EXAMPLE: 10 COLOR 2,3: REM multicolor 1=Red 20 COLOR 3,7: REM multicolor 2=Blue 30 GRAPHIC 3,1 40 CHAR 0,10,10,"TEXT",0 50 CHAR 0,10,11,"TEXT",1 17.12 CIRCLE ------ Draws circles, ellipses, arcs, etc. at specific positions on the screen. CIRCLE [color source],x,y,xr [,yr] [,sa] [,ea] [,angle] [,inc] where: color source 0=Background color 1=Foreground color 2=Multicolor 1 } 3=Multicolor 2 } Only in Graphics modes 3 and 4 x,y Centre coordinates of the CIRCLE. xr X radius (scaled). yr Y radius (scaled). sa Starting arc angle (default 0 degrees). ea Ending arc angle (default 360 degrees). angle Rotation in clockwise degrees (default is 0 degrees). inc Degrees between segments (default is 2 degrees). +++ +++ sa + + + / + + + + + xy xr+ + xy + + +---+ + + + + | + + + + |yr+ + + + | + + \ +++ +++ ea With the CIRCLE statement, the user can draw a circle, ellipse, arc, tri- angle, octagon, or other polygon. The final pixel cursor (PC) is left at the circumference of the circle at the ending arc angle. Any rotation is relative to the centre. Arcs are drawn from the starting angle clockwise to the ending angle. The increment controls the smoothness of the shape; using lower values results in more nearly circular shapes. Specifying the inc greater than 2 creates a rough-edged boxed-in shape. Also see the LOCATE command, in paragraph 17.57, for information on the pixel cursor. EXAMPLES: CIRCLE 1,160,100,65,10 Draws an ellipse CIRCLE 1,160,100,65 Draws a circle CIRCLE 1,60,40,20,18,,,,45 Draws an octagon CIRCLE 1,260,40,20,30,,,,90 Draws a diamond CIRCLE 1,60,140,20,18,,,,120 Draws a triangle You may omit a parameter, but you must still place a comma in the appro- priate position. Omitting parameters take on the default values. 17.13 CLOSE Close logical file. CLOSE file number This statement closes any files used by DOPEN or OPEN statements. The num- ber following the word CLOSE is the file number to be closed. EXAMPLE: CLOSE 2 Logical file 2 is closed. 17.14 CLR Clear program variables. CLR This statement erases any variables in memory, but leaves the program in- tact. This statement is automatically executed when a RUN or NEW command is given. 17.15 CMD Redirect screen output. CMD logical file number [,write list] This command sends the output, which normally goes to the screen (i.e. PRINT statements, LIST, but not POKES into the screen) to another device, such as a disk data file or printer. This device or file must be OPENed first. The CMD command must be followed by a number or numeric variable referring to the file or device. The write list can be any alphanumeric string or variable. This command is useful for printing at the top of program listings. EXAMPLES: OPEN 1,4 OPENs device #4, which is the printer. CMD 1 All normal output now goes to the printer. LIST The LISTing goes to the printer, not the screen - even the word READY. PRINT#1 Sends output back to the screen. CLOSE 1 Close the file. 17.16 COLLECT ------- Free inaccessible disk space. COLLECT [Ddrive number] [Udevice] Use this command to make available any disk space that has been allocated to improperly closed (splat) files, and to delete references to these files from the directory. Splat files are files that appear on the directory with an asterisk next to them. Defaults to device number 8. EXAMPLE: COLLECT D0 Free all available space which has been incorrectly allocated to improperly closed files. NOTE: It will also free space allocated for direct access and any boot sector. See your disk drive manual for more information. 17.17 COLLISION --------- Define handling for sprite collision interrupt. COLLISION type [, statement] type Type of interrupt as follows: 1 = Sprite-to-sprite collision 2 = Sprite-to-display collision 3 = Light pen statement BASIC line number of a subroutine When the specified situation occurs, BASIC will finish processing the cur- rent executing instruction and perform a GOSUB to the line number given. When the subroutine terminates (it must end with a RETURN), BASIC will re- sume processing where it left off. Interrupt action continues until a COLLISION of the same type without a line number is specified. More than one type of interrupt may be enabled at the same time, but only one inter- rupt can be handled at a time (i.e. there can be no recursion and no nes- ting of interrupts). The cause of an interrupt may continue causing interrupts for some time unless the situation is altered or the interrupt is disabled. To determine which sprites have collided since the last check, use the BUMP function. EXAMPLES: COLLISION 1, 5000 Detects a sprite-to-sprite collision and program control sent to subroutine at line 5000. COLLISION 1 Stops interrupt action which was initiated in above example. COLLISION 2,1000 Detect sprite-to-display collision and program control directed to subroutine in line 1000. NOTE: Sprites can still collide even if they are set off the screen, but not if they are switched off. 17.18 COLOR ----- Define colors for each screen area. COLOR source number, color number This statement assigns a color to one of the seven color areas: Source Numbers Area Source 0 40-column (VIC) background 1 40-column (VIC) foreground 2 multicolor 1 3 multicolor 2 4 40-column (VIC) border 5 character color (40- or 80-column screen) 6 80-column (VDC) background color Colors that are usable are in the range 1-16: Color Code Color Color Code Color 1 Black 9 Orange 2 White 10 Brown 3 Red 11 Light Red 4 Cyan 12 Dark Gray 5 Purple 13 Medium Gray 6 Green 14 Light Green 7 Blue 15 Light Blue 8 Yellow 16 Light Gray Color Numbers in 40-Column Format 1 Black 9 Dark Purple 2 White 10 Brown 3 Dark Red 11 Light Red 4 Light Cyan 12 Light Purple 5 Dark Cyan 13 Medium Gray 6 Dark Green 14 Light Green 7 Dark Blue 15 Light Blue 8 Light Yellow 16 Light Gray Color Numbers in 80-Column Format EXAMPLES: COLOR 0,1 Change background color of 40-column screen to black. COLOR 5,8 Change character color to yellow. 17.19 CONCAT ------ Concatenates two data files. CONCAT "file 2" [,Ddrive number] TO "file 1" [,Ddrive number] [Udevice] The CONCAT command attaches file 2 to the end of file 1 and retains the name of file 1. The device number defaults to 8 and the drive number defaults to 0. EXAMPLES: CONCAT "FILE B" TO "FILE A" FILE B is attached to FILE A and the combined file is designated FILE A. CONCAT (A$) TO (B$), D1, U9 The file named by B$ becomes a new file of the same name, with the file named by A$ attached to the end of B$ - this is performed on Unit 9, Drive 1 (a dual disk drive). Whenever a variable is used as a filename as in the last example, the file- name variable must be surrounded by parentheses. NOTE: Keep the filenames short (10 characters) because the command buffer is limited in some disk drives. 17.20 CONT Continue program execution. CONT This command is used to restart a program that has been stopped by either using the {stop} key, a STOP statement, or an END statement. The program resumes execution where it left off. CONT will not resume with the program if lines have been changed or added to the program or if any editing of the program is performed on the screen. If the program stopped due to an error, or if you have caused an error before trying to restart the program, CONT will not work. The error message in this case is CAN'T CONTINUE ERROR. 17.21 COPY ---- Copy files from one drive to another in a dual disk drive or within a single drive. COPY <["source filename"] [,Ddrive number]> TO <["destination filename"] [,Ddrive number]> [Udevice] This command copies files from one disk (the source file) to another (the destination file) on a dual-disk drive. It can also create a copy of a file on the same disk within a single drive, but the filename must be different. When copying from one drive to another, the filename may be the same. The COPY command can also COPY all files from one drive to another on a dual disk drive. In this case the drive numbers are specified and the source and destination filenames are omitted. The default parameters for the COPY command are device number 8, drive 0. NOTE: Copying between two single or double drive units cannot be done. See BACKUP, in paragraph 17.3. EXAMPLES: COPY "TEST",D0 TO "TEST PROG",D1 Copies "TEST" from drive 0 to drive 1, renaming it "TEST PROG" on drive 1. COPY "STUFF",D0 TO "STUFF",D1 Copies "STUFF" from drive 0 to drive 1. COPY D0 TO D1 Copies all files from drive 0 to drive 1. COPY "WORK.PROG" TO "BACKUP" Copies "WORK.PRG" as a file called "BACKUP" on the same disk (drive 0). 17.22 DATA Define data to be used by a program. DATA list of constants This statement is followed by a list of data items to be input into the computer's memory by READ statements. The items may be numeric or string and are seperated by commas. String data need not be inside quote marks, unless they contain any of the following characters: {space}, {colon}, or {comma}. If two commas have nothing between them, the value is READ as a zero if numeric or as an empty string. Also see the RESTORE statement, in paragraph 17.75, which allows the Commodore 128 to reREAD data. EXAMPLE: DATA 100,200, FRED, "HELLO MUM", , 3, 14, ABC123 17.23 DCLEAR ------ Clear all open channels on disk drive. DCLEAR [Ddrive number] [Udevice] This statement closes and clears all open channels on the specified device number. Default is U8. This command is analogous to OPEN 0,8,15,"I0": CLOSE 0. EXAMPLES: DCLEAR D0 Clears all open channels on drive 0, device number 8. DCLEAR D1,U9 Clears all open channels on drive 1, device number 9. NOTE: Files will be aborted, data may not be recoverable from files which were being written to. See CLOSE/DCLOSE, in paragraphs 17.13/17.24. 17.24 DCLOSE ------ Close disk file. DCLOSE [#logical file number] [Udevice] This statement closes a single file or all the files currently open on a disk unit. If no logical file number is specified, all currently open files are closed. The default device number is 8. Note the following examples: EXAMPLES: DCLOSE Closes all files currently open on unit 8. DCLOSE #2 Closes the file associated with the logical file number 2. DCLOSE ON U9 Closes all files curently open on unit 9. 17.25 DEF FN Define a user-defined function. DEF FN name(variable) = expression This statement allows definition of a complex calculation as a function. In the case of a long formula that is used several times within a program, this keyword can save valuable program space. The name given to the func- tion begins with the letters FN, followed by any legal numeric variable name (not integer or array). First, define the function by using the state- ment DEF, followed by the name given to the function. Following the name is a set of parentheses ( ) with a local variable name enclosed. This variable only has a value if it appears in the expression on the right of the equal sign. The same variable name can be used elsewhere in a program but it will be completely seperate from its use in the function. Other variables and/or functions can be used in the expression and these are evaluated as their value at the time the function is called. Next is an equal sign, followed by the formula to be defined. The function can be performed by sustituting any number for variable, using the format shown in lines 40 and 50 of the example below. EXAMPLE: 10 DEF FNEG(LO)=INT((V1*LO^2)*100)/100 LO is local to this line 20 LO=15 A normal program variable 30 V1=3.14159 Approximation of {pi} 40 PRINT FNEG(5) Assign 5 to the local value LO in the function. 50 PRINT FNEG(1) Use 1 in the function instead of LO. 60 PRINT INT(V1*LO^2)*100)/100 Variable LO used 70 PRINT LO Remains unchanged 17.26 DELETE ------ Delete lines of a BASIC program in the specified range. DELETE This command can be executed only in direct mode. EXAMPLES: DELETE 75 Deletes line 75. DELETE 10-50 Deletes lines 10 through 50, inclusive. DELETE-50 Deletes all lines from the beginning of the program up to and including line 50. DELETE 75- Deletes all lines from 75 to the end of the program, inclusive. 17.27 DIM Declare number of elements in an array. DIM variable(subscripts) [, variable(subscripts)] [...] Before arrays of variables can be used, the program must first execute a DIM statement to establish DIMensions of the array (unless there are 11 or fewer elements in each DIMension of the array). The DIM statement is fol- lowed by the name of the array, which may be any legal variable name. Then, enclosed in parantheses, the number (or numeric variable) of elements in each dimension. An array with more than one dimension is called a matrix. Any number of dimensions may be used, but keep in mind the whole list of variables being created takes up space in memory, and it is easy to run out of memory if too many are used. Here's how to calculate the amount of memo- ry used by an array: 5 bytes for the array name 2 bytes for each dimension 2 bytes/element for integer variables 5 bytes/element for normal numeric variables 3 bytes/element for string variables 1 byte for each character in each string element Integer arrays take up two-fifths the space of floating point arrays (e.g. DIM A%(100) requires 209 bytes; DIM A(100) requires 512 bytes). NOTE: Elements are numbered from 0, e.g. DIM A(100) gives 101 elements. More than one array can be dimensioned in a DIM statement by seperating the array variable names by commas. If the program executes a DIM statement for any array more than once, the message RE'DIM ARRAY ERROR is posted. It is good programming practice to place DIM statements near the beginning of the program. EXAMPLE: 10 DIM A$(40),B7(15),CC%(4,4,4) 41 elements, 16 elements, 125 elements. 17.28 DIRECTORY --------- Displays the contents of the disk directory on the screen. DIRECTORY [Ddrive number] [Udevice] [, wildcard] The {f3} function key in C128 mode displays the DIRECTORY for device number 8, drive 0. Use CONTROL S or NOSCROLL to pause the display. The DIRECTORY command should not be used to print a hard copy, because some printers interfere with the data coming from the disk drive. The disk directory should be loaded (LOAD "$",8) destroying the current program in memory in order to print a hard copy. The default device number is 8, and the default drive number is 0. EXAMPLES: DIRECTORY Lists all files on the disks in unit 8. DIRECTORY D1, U9, "WORK" Lists the file named "WORK" on drive 1 of unit 9. DIRECTORY "AB*" Lists all files starting with the letters "AB" like ABOVE, ABOARD, etc. on all drives of unit 8. The asterisk specifies a wild card, where all files starting with "AB" are displayed. DIRECTORY D0, "FILE ?.BAK" The ? is a wild card that matches a single character in that position. For example: FILE 1.BAK, FILE 2.BAK, FILE 3.BAK all mat- ching the string. DIRECTORY D1,U9,(A$) Lists the filename stored in the variable A$, on device number 9, drive 1. Remember whenever a variable is used as a filename, surround the variable in parentheses. NOTE: To print the DIRECTORY of the disk in drive 0, unit 8, use the fol- lowing example: LOAD"$0",8 OPEN4,4:CMD4:LIST PRINT#4:CLOSE4 17.29 DLOAD ----- Load a BASIC program from disk. DLOAD "filename" [,Ddrive number] [< ON | ,>Udevice number] This command loads a BASIC program from disk into current memory. (Use LOAD to load programs from tape.) The program must be specified by a file- name of up to 16 characters. DLOAD assumes device number 8, drive 0. EXAMPLES: DLOAD "BANKRECS" Searches the disk for the program "BANKRECS" and LOADs it. DLOAD (A$) LOADs a program from disk whose name is stored in the variable A$. An error message is given if A$ is empty. Remember, when a variable is used as a filename, it must be enclosed in parentheses. The DLOAD command can be used within a BASIC program to find another pro- gram on disk. This is called chaining. 17.30 DO/LOOP/WHILE/UNTIL/EXIT ------------------------ Define and control progam loop. DO [UNTIL condition | WHILE condition] statement [EXIT] LOOP [UNTIL condition | WHILE condition] This loop structure performs the statements between the DO statement and the LOOP statement. If no UNTIL or WHILE statements modifies either the DO or the LOOP statement, execution of the statements in between continues indefinitely. If an EXIT statement is encountered in the body of a DO loop, execution is transferred to the first statement following the LOOP state- ment. DO loops may be nested, following the rules defined by the FOR... NEXT structure. If the UNTIL parameter is specified, the program continues looping until the condition is satisfied (becomes true). The WHILE para- meter is basically the oposite of the UNTIL parameter: the program conti- nues looping as long as the condition is true. As soon as the condition is no longer true, program control resumes with the statement immediately fol- lowing the LOOP statement. An example of a condition (boolean operation) is A=1, or G>65. EXAMPLES: 10 X=25 20 DO UNTIL X=0 30 X=X-1 40 PRINT "X=";X 50 LOOP 60 PRINT "END OF LOOP" This example performs the statement X=X-1 and PRINTs "X=";X until X=0. When X=0 the program resumes with the statement following LOOP, PRINT "END OF LOOP" 10 DO WHILE A$="":GET A$:LOOP 20 PRINT "THE ";A$;" KEY HAS BEEN PRESSED" A$ remains null as long as no key is pressed. As soon as a key is pressed program control passes to the statement immediately following LOOP, PRINT "THE ";A$;" KEY HAS BEEN PRESSED". The example performs a GET A$ as long as A$ is a null character. This loop constantly checks to see if a key on the keyboard is being pressed. Note that the statement GETKEY A$ has the same effect as line 10. 10 OPEN #8,"SEQFILE" 20 DO 30 GET #8,A$ 40 PRINT A$; 50 LOOP UNTIL ST 60 DCLOSE #8 This program opens the file "SEQFILE" and gets data until the ST system variable indicates all data is input. A value of 0 indicates a FALSE con- dition, nonzero is true. ST is normally 0. 17.31 DOPEN ----- Open a disk file for a read and/or write operation. DOPEN #logical file number,"filename[,]" [,Lrecord length] [,Ddrive number] [Udevice number] [,w] where: S = Sequential file type. P = Program file type. L = Record length = the length of records in a relative file only. w = Write operation (if not specified a read operation occurs). This statement opens a sequential, program or relative file for a read or write operation. The record length (L) pertains to a relative file, which can be as long as 254. The w parameter is specified only during a write (PRINT#) operation in a sequential file. If not specified, the disk drive assumes the disk operation to be a read operation. Relative file are open for both read and write operations at the same time. The logical file number associates a number to a file for future disk operations such as a read (INPUT# or GET#) or write (PRINT#) operation. The logical file number can range from 1 to 255. Logical file numbers greater than 128 automatically send a carriage return and linefeed with each PRINT# command. Logical file number less than 128 send only a carriage return, which can be suppressed with a semicolon at the end of the PRINT# command. The default device number is 8, and the default drive is 0. EXAMPLES: DOPEN#1,"ADDRESS",W Open the sequential file number 1 (ADDRESS) for a write operation. DOPEN#2,"RECIPES",D1,U9 Open the sequential file number 2 (RECIPES) for a read operation on device number 9, drive 1. DOPEN#3,"BOOKS",L128 Open the relative file number 3 (BOOKS) for read and write on unit 8 drive 0. Record length is 128 characters. 17.32 DRAW ---- Draw dots, lines and shapes at specified positions on screen. DRAW [color source], x1,y1 [TO x2,y2] ... This statement draws individual dots, lines, and shapes. Here are the para- meter values: color source= 0 Background color 1 Foreground color 2 Multicolor 1 } 3 Multicolor 2 } Only in Graphics modes 3 and 4 x1, y1 Starting coordinate, scaled x2, y2 Ending coordinate, scaled Also see the LOCATE command, in paragraph 17.57, for information on the pixel cursor. EXAMPLES: DRAW 1,100,50 Draw a dot DRAW ,10,10 TO 100,60 Draw a line DRAW ,10,10 TO 10,60 TO 100,60 TO 10,10 Draw a triangle You may omit a parameter but you still must include the comma that would have followed the unspecified parameter. 17.33 DSAVE ----- Save a BASIC program file to disk. DSAVE "filename" [,Ddrive number] [Udevice number] This command stores (SAVEs) a BASIC program on disk. (See SAVE, in paragraph 17.80, to store programs on tape.) A filename up to 16 characters long must be supplied. The default device number is 8, while the default drive number is 0. EXAMPLES: DSAVE "BANKRECS" SAVEs the program "BANKRECS" to disk. DSAVE (A$) SAVEs the disk program named in the variable A$. DSAVE "PROG 3",D1,U9 SAVEs the program "PROG 3" to disk on unit 9, drive 1 (on a dual drive unit). 17.34 DVERIFY ------- Verify the program in memory against the one on disk. DVERIFY "filename" [,Ddrive number] [Udevice number] This command causes the Commodore 128 to check the program on the specified drive against the program in memory. The default drive number is 0 and the default device number is 8. NOTE: If graphic area is allocated or deallocated after a SAVE, an error occurs. Technically this is correct. Because BASIC text is moved from its original (SAVEd) location when a bit mapped graphics area is allocated or deallocated, the original location where the C128 verified the SAVEd pro- gram changes. Hence, VERIFY, which performs byte-to-byte comparisons, fails, even though the program is valid. To verify binary data, see VERIFY "filename",8,1 format, under VERIFY command description. EXAMPLES: DVERIFY "C128" Verifies program "C128" on drive 0, unit 8. DVERIFY "SPRITES",D0,U9 Verifies program "SPRITES" on drive 0, device 9. 17.35 END Define the end of program execution. END When the program encounters the END statement, it stops RUNning immediate- ly. The CONT command can be used to restart the program at the next state- ment (if any) following the END statement. 17.36 ENVELOPE -------- Define a musical instrument envelope. ENVELOPE n [,atk] [,dec] [,sus] [,rel] [,wf] [,pw] where: n Envelope number (0-9) atk Attack rate (0-15) dec Decay rate (0-15) sus Sustain level (0-15) rel Release rate (0-15) wf Waveform: 0 = triangle 1 = sawtooth 2 = variable pulse (square) 3 = noise 4 = ring modulation pw Pulse width (0-4095) A parameter that is not specified will retain its predefined or currently redefined value. Pulse width applies to the width of the variable pulse waveform (wf=2) only and is determined by the formula: pwout = pw/40.95, so that pw=2048 produces a square wave and values 0 and 4095 produce constant DC output. The Commodore 128 has initialized the following 10 envelopes: n, A, D, S, R, wf, pw instrument ENVELOPE 0, 0, 9, 0, 0, 2, 1536 piano ENVELOPE 1, 12, 0, 12, 0, 1 accordion ENVELOPE 2, 0, 0, 15, 0, 0 calliope ENVELOPE 3, 0, 5, 5, 0, 3 drum ENVELOPE 4, 9, 4, 4, 0, 0 flute ENVELOPE 5, 0, 9, 2, 1, 1 guitar ENVELOPE 6, 0, 9, 0, 0, 2, 512 harpsicord ENVELOPE 7, 0, 9, 9, 0, 2, 2048 organ ENVELOPE 8, 8, 9, 4, 1, 2, 512 trumpet ENVELOPE 9, 0, 9, 0, 0, 0 xylophone To play predefined musical instrument envelopes, you simply specify the envelope number in the PLAY command (see PLAY, paragraph 17.64). You do not need to use the ENVELOPE command. The ENVELOPE command is used only when you need to change the envelope. 17.37 FAST ---- Put machine in 2 Mhz mode of operation. FAST This command initiates 2 Mhz mode, causing VIC's 40 column screen to be turned off. All operartions (except I/O) are speeded up considerably. Graphics may be used, but will not be visible until a SLOW command is issued. 17.38 FETCH ----- Get data from expansion (RAM module) memory. FETCH #bytes, intsa, expsa, expb where #bytes = number of bytes to get from expansion memory (0-65535) intsa = starting address of host RAM (0-65535) expsa = starting address of expansion RAM (0-65535) expb = 64K expansion RAM bank number (0-15) 17.39 FILTER ------ Define sound (SID chip) filter parameters. FILTER [freq] [,lp] [,bp] [,hp] [,res] where: freq Filter cut-off frequency (0-2047). lp Low-pass filter on (1), off (0). bp Band-pass filter on (1), off (0). hp High-pass filter on (1), off (0). res Resonance (0-15). Unspecified parameters result in no change to the current value. You can use more than one type of filter at a time. For example, both low- pass and high-pass filters can be used together to produce a notch (or band- reject) filter response. For the filter to have an audible effect, at least one type of filter must be selected and at least one voice must be routed through the filter. EXAMPLES: FILTER 1024,0,1,0,2 Set the cutoff frequency at 1024, select the band pass filter and a resonance level of 2. FILTER 2000,1,0,1,10 Set the cutoff frequency at 2000, select both the low pass and high pass filters (to form a notch- reject) and set the resonance level at 10. 17.40 FOR/TO/STEP/NEXT Define a repetitive program loop structure. FOR variable = start value TO end value [STEP increment] NEXT [variable] The FOR statement works with the NEXT statement to set up a section of the program that repeats for a set number of times (i.e. a loop). This is use- ful when something needs to be counted or something must be done a certain number of times (such as printing). This statement executes all the commands enclosed between the FOR and NEXT statements repetitively, according to the start and end values. The start value and end value are the beginning and ending counts for the loop variable. The loop variable is added to or subtracted from during the FOR... NEXT loop. The logic of the FOR... NEXT statement is as follows. First, the loop variable is set to the start value. When the program reaches a program line containing the NEXT statement, it adds the STEP increment (default = 1) to the value of the loop variable and checks to see if it is higher than the end value of the loop. If the loop variable is less than or equal to the end value, the loop is executed again, starting with the statement imme- diately following the FOR statement. If the loop variable is greater than the end value, the loop terminates and the program resumes immediately fol- lowing the NEXT statement. The opposite is true if the step size is nega- tive. EXAMPLE A EXAMPLE B 10 FOR L=1 TO 10 10 FOR L=10 TO 1 STEP-1 20 PRINT L 20 PRINT L 30 NEXT L 30 NEXT L 40 PRINT "I'M DONE! L =";L 40 PRINT "I'M DONE! L =";L Program A prints the number from one to 10, followed by the message I'M DONE! L = 11. Program B prints the numbers down to one and them I'M DONE! L = 0. The end value of the loop may be followed by the word STEP and another num- ber or variable. In this case, the value following the word STEP is added each time, instead of the default value one. This allows counting back- wards, by fractions, or increments other than one. The user can set up loops inside one another. These are known as nested loops. Care must be taken when nesting loops so, that the last loop to start is the first one to end. EXAMPLE: 10 FOR L = 1 TO 100 20 FOR A = 5 TO 11 STEP .5 30 NEXT A 40 NEXT L The FOR... NEXT loop in lines 20 and 30 are nested inside the one in line 10 and 40. The STEP increment of .5 is used to illustrate the fact that floating point indices are valid. 17.41 GET Receive input data from the keyboard, one character at a time without waiting for a key to be pressed. GET variable list The GET statement reads each key typed by the user. As the user types, the characters are stored in the computer's memory (in an area called the key- board buffer). Up to 10 characters can be stored here1, any characters typed after the 10th character are lost. The GET statement reads the first character from the buffer and moves the rest up, allowing room for more. If there are no characters in the buffer a null (empty) character is returned. The word GET is followed by a variable name, either numeric or string. GET will not pause the program if no characters are in the buffer (see GETKEY, in paragraph 17.42). If the C128 intends to GET a numeric key and a key other than a number is pressed, the program stops and a TYPE MISMATCH error message is displayed. The GET statement may also be put into a loop, checking for an empty result. The GETKEY statement could also be used in this case. See GETKEY, in paragraph 17.42, for more information. The GET and GETKEY statements can be executed only within a program. EXAMPLES: 10 DO:GET A$:LOOP UNTIL A$="A" This line waits for the A key to be pressed to continue. 20 GET B, C, D Get numeric variables B, C and D from the keyboard without waiting for a key to be pressed. 17.42 GETKEY ------ Receive input data from the keyboard, one character at a time and wait for a key to be pressed. GETKEY variable list The GETKEY statement is very similar to the GET statement. Unlike the GET statement, GETKEY, if there is no character in the keyboard buffer, will wait for the user to type a character on the keyboard. This lets the com- puter wait for a single character to be typed. This statement can be exe- cuted only within a program. EXAMPLES: 10 GETKEY A$ This line waits for a key to be pressed. Typing any key continues the program. 10 GETKEY A$,B$,C$ This line waits for three alphanumeric characters to be entered from the keyboard. GETKEY can also be used to READ numeric keys. NOTE: GETKEY cannot return a null (empty) character. 17.43 GET# Receive input data from a tape, disk or RS232. GET#file number, variable list This statement inputs one character at a time from a previously opened file. Otherwise, it works like the GET statement. This statement can be executed only within a program. EXAMPLE: GET#1,A$ This example receives one character, which is stored in the variable A$, from file number 1. This example assumes that file 1 was previously opened. See the OPEN and DOPEN state- ments, in paragraphs 17.62 and 17.31,respectively. 17.44 GO64 ---- Switch to C64 mode. GO64 This statement switches from C128 mode to C64 mode. The question "Are You Sure?" is displayed in response to the GO64 statement. If {y} is typed, then the currently loaded program is lost and control is given to the C64 mode; otherwise, if any other key is pressed, the computer remains in C128 mode. This statement can be used in direct mode or within a program. The prompt is not displayed in program mode. 17.45 GOSUB Call a subroutine from the specified line number. GOSUB line number This statement is similar to the GOTO statement, except the Commodore 128 returns from where it came when the subroutine is finished. When a line with a RETURN statement is encountered, the program jumps back to the statement immediately following the GOSUB statement. The target of a GOSUB statement is called a subroutine. A subroutine is useful if a task is repeated several times within a program. Instead of duplicating the section of program over and over, set up a subroutine, and GOSUB to it at the appropriate time in the program. See also the RETURN statement, in paragraph 17.77. EXAMPLE: 20 GOSUB 800 : : 799 END 800 PRINT "HI THERE": RETURN This example calls the subroutine beginning at line 800 and executes it. All subroutines terminate with a RETURN statement. Line 799 stops the program accidentally falling into the subroutine. 17.46 GOTO/GO TO Transfer program execution to the specified line number. GOTO line number After a GOTO statement is encountered in a program, the computer executes the statement specified by the line number in the GOTO statement. When used in direct mode, GOTO executes (RUNs) the program starting at the specified line number, without clearing the variables. This is the same as the RUN command except it does not clear variable values. EXAMPLES: 10 PRINT"COMMODORE" 20 GOTO 10 The GOTO in line 20 makes line 10 repeat continuously until {run/stop} is pressed. GOTO 100 Starts (RUNs) the program starting at line 100, without clearing the variable storage area. 17.47 GRAPHIC ------- Select a graphic mode. GRAPHIC mode [,clear] [,s] GRAPHIC CLR This statement puts the Commodore 128 in one of the six graphic modes: Mode Description 0 40-column (VIC) standard text 1 Standard bit map 2 Standard bit map (split screen) 3 Multicolor bit map 4 Multicolor bit map (split screen) 5 80-column text The clear parameter specifies whether the bit mapped screen is cleared (equal to 1) upon running the program, or left intact (equal to 0). The s parameter indicates the starting line number of the split screen when in graphic mode 2 or 4 (standard or multicolor bit map split screen modes). The default starting line number of the split screen is 19. When executed, GRAPHIC 1-4 allocated a 9K bit mapped area. The start of BASIC text area is moved above the bit map area, and any BASIC program is automatically relocated. This area remains allocated even if the user returns to TEXT mode (GRAPHIC 0). If the clear option is specified as 1, the screen is cleared. The GRAPHIC CLR command deallocates the 9K bit mapped area, making it available again for BASIC text. Any BASIC program is relocated. EXAMPLES: GRAPHIC 1,1 Select standard bit map mode and clear the bit map. GRAPHIC 4,0,10 Select split screen multicolor bit map mode, do not clear the bit map and start the split screen at line 10. GRAPHIC 0 Select 40 column text. GRAPHIC 5 Select 80 column text. GRAPHIC CLR Clear and deallocate the bit map screen. 17.48 HEADER ------ Formats a diskette. HEADER diskname [,I i.d.] [,Ddrive number] [Udevice number] where: diskname - Any name up to 16 characters. i.d. - Any two alphanumeric characters. You must use two - you may not leave a space. Before a new disk can be used for the first time, it must be formatted with the HEADER command. The HEADER command can also be used to erase a pre- viously formatted disk, which can then be reused. When you enter a HEADER command in direct mode, the prompt ARE YOU SURE? appears. In program mode, the prompt does not appear. The command divides the disk into sections called blocks. It creates a table of contents of files, called a directory. Give each disk a unique i.d. number. Be careful when using the HEADER command because it erases all stored data. You can HEADER a diskette more quickly if it was already formatted (by a HEADER command), by omitting the new disk i.d. The old i.d. is used in- stead. The quick HEADER can be used only if the disk was previously format- ted, since it clears out the directory rather than formatting the disk. The default device number is 8 and the default drive is 0. As a precaution, the system asks ARE YOU SURE? before the Commodore 128 completes the operation. Press the {y} key to perform the HEADER, or press any other key to cancel it. The HEADER command reads the disk command error channel, and if any error is encountered, the error message ?BAD DISK is displayed. The HEADER command is analogous to the BASIC 2.0 command: OPEN 1,8,15,"N0:diskname,i.d." : CLOSE 1 EXAMPLES: HEADER "MYDISK",I51,D0 This HEADERs "MYDISK" using i.d. 51 on drive 0, (default) device number 8. HEADER "RECS",I45,D1 ON U9 This HEADERs "RECS" using i.d. 45, on Drive 1, device number 9. HEADER "C128 PROGRAMS",D0 This is a quick HEADER on drive 0, device number 8, assuming the disk in the drive was already formatted. The old i.d. is used. 17.49 HELP ---- Highlight the line where the error occurred. HELP The HELP command is used after an error has been reported in a program. When HELP is typed in 40-column format, the line where the error occurs is listed, with the portion containing the error displayed in reverse field. In 80-column format, the portion of the line where the error occurs is underlined. Pressing the {help} key types HELP{return} automatically. 17.50 IF/THEN/ELSE ---- Evaluate a conditional expression and execute portions of a program depen- ding on the outcome of the expression. IF expression THEN statements (BASIC 2.0) IF expression THEN statements [:ELSE else-clause] (BASIC 7.0) The IF... THEN statement evaluates a BASIC expression and takes one or two possible courses of action depending upon the outcome of the expression. If the expression is true, the statement(s) following THEN is executed. This may be any BASIC statement. If the expression if false, the program resumes with the program line immediately following the program line containing the IF statement, unless an ELSE clause is present. The entire IF... THEN statement must be contained within 160 characters (80 in C64 mode). Also see BEGIN/BEND, in paragraph 17.5. The ELSE clause, if present, must be on the same line as the IF... THEN portion of the statement, and separated from the THEN clause by a colon {:}. When an ELSE clause is present, it is executed only when the expres- sion if false. The expression being evaluated may be a variable or a for- mula, in which case it is considered true if nonzero, and false if zero. In most cases, there is an expression involving relational operators (=, <, >, >=, <>). The IF... THEN statement can take two alternate forms: IF expression THEN line number or IF expression THEN GOTO line number These forms transfer program execution to the specific line number if the expression is true. Otherwise, the program resumes with the program line number immediately following the line containing the IF statement. EXAMPLES: 50 IF X>0 THEN PRINT "OK": ELSE END This line checks the value of X. If X is greater than 0, the statement im- mediately following the keyword THEN (PRINT"OK") is executed and the ELSE clause is ignored. If X is less than or equal to 0, the ELSE clause is exe- cuted and the statement immediately following THEN is ignored. 10 IF X=10 THEN 100 20 PRINT"X does not equal 10" . . 99 STOP 100 PRINT "X equals 10" This example evaluates the value of X. If X equals 10, the program control is transferred to line 100 and the message "X EQUALS 10" is printed. If X does not equal 10, the program resumes with line 20, the C128 prints the prompt "X DOES NOT EQUAL 10" and the program stops. NOTE: The ELSE extension cannot be used in C64 mode. 17.51 INPUT Receive a data string or a number from the keyboard and wait for the user to press {return}. INPUT ["prompt string";] variable list The INPUT statement asks for data from the user while the program is RUNning and places the data into a variable or variables. The program stops, prints a question mark (?) on the screen, and waits for the user to type the answer and hit the {return} key. The word INPUT is followed by a prompt string and a variable name or list of variable names separated by commas. The message in the prompt string inside quotes suggests (prompts) the information the user should enter. If this message is present, there must be a semicolon (;) after the closing quote of the prompt. When more than one variable is INPUT, seperate them by commas. The compu- ter asks for the remaining values by typing two question marks (??). If the {return} key is pressed without INPUTting a value, the INPUT variable retains its previous value. The INPUT statement can be executed only with- in a program. EXAMPLE: 10 INPUT "PLEASE TYPE TWO NUMBER";A,B 20 INPUT "AND YOUR NAME";A$ 30 PRINT A$;", YOU TYPED THE NUMBER"A;"AND";B 17.52 INPUT# Inputs data from a file into the computer's memory. INPUT#file number, variable list This statement works like input, but takes the data from a previously OPENed file usually on a disk or tape instead of the keyboard. No prompt string is used. This statement can be used only within a program. EXAMPLE: 10 OPEN 2,8,2,"DATAFILE,S,R" 20 INPUT#2,A$, C, D$ 30 CLOSE 2 In line 20 data is INPUT from the file "DATAFILE" and stores it in varia- bles A$, C and D$. 17.53 KEY --- Define or list function key assignments. KEY [key number, string] There are eight function keys (F1 - F8) available to the user on the Commo- dore 128: four unshifted and four shifted. The Commodore 128 allows you to perform a function or operation for each time the specified function key is pressed. The definition assigned to a key can consist of data, or a command or series of commands. KEY with no parameters specified returns a listing displaying all current KEY assignments. If data is assigned to a function key, that data is displayed on the screen when that function key is pres- sed. The maximum length of all the definitions together is 246 characters. EXAMPLES: KEY 7,"GRAPHIC0" + CHR$(13) + "LIST" + CHR$(13) This tells the computer to select the (VIC) 40-column text screen and list the program whenever the {f7} key is pressed (in direct mode). CHR$(13) is the ASCII character for {return} and performs the same action as pressing the {return} key. Use CHR$(27) for the {esc} key. Use CHR$(34) to incor- porate the double quote character into a KEY string. The keys may be rede- fined in a program. For example: 10 KEY 2,"PRINT DS$" + CHR$(13) This tells the computer to check and display the disk drive error channel variable (PRINT DS$) each time the {f2} key is pressed. To restore all function keys to their BASIC default values, reset the Com- modore 128 by pressing the {reset} button (or switch off and then on). 17.54 LET Assigns a value to a variable. [LET] variable = expression The word LET is rarely used in programs, since it is not necessary. When- ever a variable is defined or given a value, LET is always implied. The variable name that receives the result of a calculation is on the left side of the equal sign. The number, string or formula is on the right side. You can only assign one value with each (implied) LET statement. For example, LET A=B=2 is not (normally) legal. EXAMPLES: LET A = 5 Assign the value 5 to numeric variable A. B = 6 Assign the value 6 to numeric variable B. C = A * B + 3 Assign the numeric variable C, the value resulting from 5 times 6 plus 3. D$ = "HELLO" Assign the string "HELLO" to string variable D$. 17.55 LIST List the BASIC program currently in memory. LIST [line | first- | first-last | -last] The LIST command displays a BASIC program listing that has been typed or LOADed into the Commodore 128's memory so you can read and edit it. When LIST is used alone (without numbers following it), the Commodore 128 gives a complete LISTing of the program on the screen. The listing process may be slowed down by holding the {C=} key, paused by {ctrl s} or {noscroll} key (and resumed by pressing any key), or stopped by hitting the {run/stop} key. If the word LIST is followed by a line number, the Commodore 128 shows only that line number. If LIST is typed with two line numbers seperated by a dash all lines from the first to the second number are displayed. If LIST is typed followed by a number and just a dash, the Commodore 128 shows all line from that number to the end of the program. And if LIST is typed with a dash, then a number, all lines from the beginning of the program to that line number are LISTed. By using these variations, any portion of a program can be examined or brought to the screen for modification. In Commodore 128 mode, LIST can be used in a program. EXAMPLES: LIST Shows entire program. LIST 100- Shows from line 100 until the end of the program. LIST 10 Shows only line 10. LIST -100 Shows all lines from the beginning to line 100 inclusive. LIST 10-200 Shows lines from 10 to 200, inclusive. 17.56 LOAD Load a program from a peripheral device such as the disk drive or Datas- sette. LOAD ["filename"] [,device number] [,relocate flag] This is the command used to recall a program stored on disk or cassette tape. Here, the filename is a program name up to 16 characters long, in quotes. The name must be followed by a comma (outside the quotes) and a number which acts as a device number to determine where the program is stored (disk or tape). If no number is supplied, the Commodore 128 assumes device number 1 (the Datassette tape recorder). The relocate flag is a number (0 or 1) that determines where a program is loaded in memory. A relocate flag of 0 tells the Commodore 128 to load the program at the start of the BASIC program area. A flag of 1 tells the com- puter to LOAD from the point where it was SAVEd. The default value of the relocate flag is 0. The relocate parameter of 1 is generally used when loading machine language programs. The device most commonly used with the LOAD command is the disk drive. This is device number 8, though the DLOAD command is more convenient to use when working with disk. If LOAD is typed with no arguments, followed by {return}, the C128 assumes you are loading from tape and you are prompted to "PRESS PLAY ON TAPE". When you press PLAY, the Commodore 128 starts looking for a program on tape. When the program is found, the Commodore 128 prints FOUND "filename", where the filename is the name of the first file which the datassette finds on the tape. Press the {C=} key to LOAD the found filename, or press the {spacebar} to keep searching on the tape. Once the program is LOADed, it can be RUN, LISTed or modified. NOTE: Pressing the {spacebar} does not cause the next file to be searched for in C64 mode. EXAMPLES: LOAD Reads in the next program from tape. LOAD "HELLO" Searches tape for a program called "HELLO", and LOADs it if found. LOAD A$,8 LOADs the program from disk whose name is stored in the variable A$. (This is the equivalent to DLOAD(A$).) LOAD"HELLO",8 Looks for the program called "HELLO" on disk drive number 8, drive 0. (This is equivalent to DLOAD "HELLO".) LOAD"MACHLANG",8,1 LOADs the machine language program called "MACHLANG" into the location from which it was saved. The LOAD command can be used within a BASIC program to find and RUN the next program on a tape or disk. This is called chaining. 17.57 LOCATE ------ Position the bit map pixel cursor on the screen. LOCATE x,y The LOCATE statement places the pixel cursor (PC) at any specified pixel coordinate on the screen. The pixel cursor (PC) is the coordinate on the bit map screen where drawing of circles, boxes, lines and points and where PAINTing begins. The PC ranges from x,y coordinates 0,0 throught 319,199 (scaled) in hi-res and 159,199 (scaled) in multicolor bit map. The PC is not visible like the text cursor, but it can be controlled through the graphics statements (BOX, CIRCLE, DRAW, etc.). The default location of the pixel cursor is the coor- dinate specified by the x and y portions in each particular graphics com- mand. So the LOCATE command does not have to be specified. EXAMPLE: LOCATE 160,100 Position the PC in the centre of the standard bit map screen. Nothing will be seen until something is drawn. The PC can be found by using RDOT(0) function to get the x-coordinate and RDOT(1) to get the y-coordinate. The color source of the dot at the PC can be found by PRINTing RDOT(2). 17.58 MONITOR ------- Enter the Commodore 128 machine language monitor. MONITOR See Appendix J for details on the Commodore 128 Machine Language Monitor. 17.59 MOVSPR ------ Position or move sprite on the screen. MOVSPR number,x1,y1 Place the specified sprite at absolute coordinate x,y (scaled). MOVSPR number,+/- x, +/- y Move sprite relative to its current posi- tion. MOVSPR number,X;Y Move sprite distance X at angle Y relative to its current position. MOVSPR number,x angle #y speed Move sprite at an angle relative to its original coordinates, in the specified clockwise direction and speed. where: number is sprite's number (1 through 8) <,x,y> is the coordinate of the sprite location (scaled) angle is the angle (0-360) of motion in the clockwise direction relative to the sprite's original coordinates speed is a speed (0-15) at which the sprite moves This statement locates a sprite at a specific location on the screen accor- ding to the SPRITE coordinate plane (not the bit map plane) or initiates sprite motion at a specific rate. See MOVSPR in paragraph 6.3.7 of Section 6 for a diagram of the sprite coordinate system. EXAMPLES: MOVSPR 1,150,150 Position sprite 1 near the centre ot the screen, x,y coordinate 150, 150. MOVSPR 1,+20,-30 Move sprite 1 to the right 20 coordinates and up 30 coordinates. MOVSPR 4,-50,+100 Move sprite 4 to the left 50 coordinates and down 100. MOVSPR 5,45 #15 Move sprite 5 at an 45 degree angle in the clockwise direction, relative to its original x and y coor- dinate. The sprite moves at the fastest rate (15). NOTE: Once you specify an angle and a speed in the fourth form of the MOVSPR statement, you must set a speed of zero to stop the sprite moving. 17.60 NEW Clear (erase) program and variable storage. NEW This command erases the entire program in memory and clears any variables that may have been used. Unless the program was stored on disk or tape, it is lost. Be careful with the use of this command. The NEW command also can be used as a statement in a BASIC program. However, when the Commodore 128 gets to this line, the program is erased and everything stops. 17.61 ON Conditional branch to a specified program line number according to the re- sults of the specified expression. ON expression line #1 [,line #2, ...] This statement can make the GOTO and GOSUB statements operate like special versions of the (conditional) IF statement. The word ON is followed by an expression, then either of the keywords GOTO or GOSUB and a list of line numbers separated by commas. If the result of the expression is 1, the first line number in the list is executed. If the result is 2, the second line number is executed on so on. If the result is 0, or larger than the number of line numbers in the list, the program resumes with the statement immediately following the ON statement. If the number is negative, an ILLEGAL QUANTITY error results. EXAMPLE: 10 INPUT X:IF X<0 THEN 10 20 ON X GOSUB 30, 40, 50, 60 25 GOTO 10 30 PRINT "X=1":RETURN 40 PRINT "X=2":RETURN 50 PRINT "X=3":RETURN 60 PRINT "X=4":RETURN When X=1, ON sends control to the first line number in the list (30). When X=2, ON sends control to the second line (40), etc. 17.62 OPEN Open files for input or output. OPEN logical file number, device number [,secundary address] [<,"filename, filetype, mode" | cmd string>] The OPEN statement allows the Commodore 128 to access files within devices such as a disk drive, a Datassette cassette recorder, a printer or even the screen of the Commodore 128. The word OPEN is followed by a logical file number, which is the number to which all other BASIC input/output statements will refer, such as PRINT# (write), INPUT# (read), etc. This number is from 1 to 255. The second number, called the device number follows the logical file num- ber. Device number 0 is the Commodore 128 keyboard; 1 is the cassette recorder; 3 is the Commodore 128 screen; 4-7 are normally the printer(s); 8-11 are reserved for disk drives. It is often a good idea to use the same file number as the device number, because it makes it easy to remember which is which. Following the device number may be a third parameter called the secundary address. In the case of the cassette, this can be 0 for read, 1 for write and 2 for write with END-OF-TAPE marker at the end. In case of the disk, the number refers to the channel number. See you disk drive manual for more information on channels and channel numbers. For the printer, the secundary addresses are used to select certain programming functions. There may also be a filename specified for disk or tape OR a string fol- lowing the secundary address, which could be a command to the disk/tape drive or the name of the file on tape or disk. If the filename is speci- fied, the type and mode refer to disk files only. File types are PROGRAM, SEQUENTIAL, RELATIVE and USER; modes are READ and WRITE. EXAMPLES: 10 OPEN 3,3 OPENs the screen as file number 3. 20 OPEN 1,0 OPENs the keyboard as file number 1. 30 OPEN 1,1,0,"DOT" OPENs the cassette for reading, as file number 1, using "DOT" as the filename. OPEN 4,4 OPENs the printer as file number 4. OPEN 15,8,15 OPENs the command channel on the disk as file 15, with secundary address 15. (Secundary address 15 is reserved for the disk drive error command channel.) 5 OPEN 8,8,12, OPENs a sequential disk file for writing called "TESTFILE,SEQ,WRITE" "TESTFILE" as file number 8, with secundary address 12. See also: CLOSE (17.13), CMD (17.15), GET# (17.43), INPUT# (17.52), and PRINT# (17.67) statements and system variables ST, DS and DS$ (19.1). 17.63 PAINT ----- Fill area with color. PAINT [color source], x, y [,mode] where: color source 0 Background color 1 Foreground color 2 Multicolor 1 3 Multicolor 2 x,y Starting coordinates, scaled (default at pixel cursor (PC)). mode 0 = Paint an area defined by the color source selected (default). 1 = paint an area defined by any non-background source. The PAINT command fills an area with color, the area is defined by a fully enclosed shape around, but not including the x,y coordinates specified. Points where the color source is the same as the source of the pixel are not PAINTed. (See example 3.) If mode=0 the area filled must be bounded by the color source, any other color sources which lie within this boundery are overPAINTed. (See example 1.) If mode=1 the boundery of the area is any color source (except 0). No color sources will be overPAINTed; i.e. only non-PAINTed areas can be filled when mode=1. (See example 2.) EXAMPLE 1: 10 COLOR 0,1:COLOR 1,2: COLOR 2,5:COLOR 3,7 20 GRAPHIC 3,1 multicolor graphics 30 CIRCLE 1,80,100,30 draw circle in color source 1 40 CIRCLE 3,80,100,35 draw circle in color source 3 50 BOX 2,80,100,90,110,45,1 draw filled box in color source 2 60 PAINT 3,70,100,0 paint inner circle in color source 3 bounded only by color source 3 EXAMPLE 2: As example 1, but change line 60 to: 60 PAINT 3,70,100,1 paint inner circle bounded by non-background color source EXAMPLE 3: As example 2, but add lines 70 and 80: 70 COLOR 2,8 change color source to yellow 80 PAINT 2,90,110,1 attempt to repaint the box fails, because color source in PAINT and at (90,100) are the same (2). 17.64 PLAY ---- Define and play musical notes and elements. PLAY "[Vn] [On] [Tn] [Un] [Xn] [elements] [...]" where: Vn = Voice (n=1-3) On = Octave (n=0-6) Tn = Tune Envelope (n=0-9) 0 = piano 1 = accordion For 2 = calliope default envelope 3 = drum settings 4 = flute (see ENVELOPE 5 = guitar command, paragraph 6 = harpsichord 17.36) 7 = organ 8 = trumpet 9 = xylophone Un = Volume (n=0-9) (0=off; 9=full (VOL 15)) Xn = Filter on (n=1), off (n=0) Elements: NOTES: A, B, C, D, E, F, G # Sharp* $ Flat* W Whole note H Half note Q Quarter note I Eighth note S Sixteenth note . Dotted* R Rest M Wait for all voices currently playing to end current measure The PLAY statement gives you the power to select voice, octave and tune envelope (including ten predefined musical instrument envelopes), the volume and the notes you want to PLAY. All these controls are enclosed in quotes. All elements except R and M precede the musical notes in a PLAY string. NOTE: * These must precede each musical note. EXAMPLES: PLAY "V1O4T0U5X0CDEFGAB" Play the notes C, D, E, F, G, A, and B in voice 1, octave 4, tune enve- lope 0 (piano - assuming you have not altered it with ENVELOPE), at volume 5, with the filter off. PLAY "V3O5T6U7X1#B$AW.CHDQEIF" Play the notes B-sharp, A-flat, a whole dotted-C note, a half D-note, a quarter E-note and an eighth F-note. NOTE: You will need to set up a filter before you can hear anything with this example - try FILTER 1024,1. 17.65 POKE Change the contents of a RAM memory location. POKE address, value The POKE statement allows changing of any value in the Commodore 128 RAM, and allows modification of many of the Commodore 128 Input/Output registers. The keyword POKE is always followed by two parameters. The first is a location inside the Commodore 128 memory, this can be a value from 0 to 65535. The second parameter is a value from 0 to 255, which is placed in the location, replacing any value that was there previously. The value of the memory location determines the bit pattern of the memory location. In C128 mode the POKE occurs into the current selected RAM bank. The POKE address depends on the BANK number. See BANK in paragraph 17.4 of this Ency- clopaedia for the appropriate BANK configurations. EXAMPLE: 10 POKE 53280,1 Changes VIC border color (BANK 15 in C128 mode). NOTE: PEEK, a function related to POKE, which returns the contents of the specified memory location is listed under BASIC Functions. 17.66 PRINT Output to text screen PRINT print list The PRINT statement is the major output statement in BASIC. While the PRINT statement is the first BASIC statement most people learn to use, there are many variations of this statement. The word PRINT can be followed by any of the following: Characters inside of quotes ("text" lines) Variable names (A, B, A$, X$) Functions (SIN(23), ABS(33)) Punctuation marks (; ,) The characters inside quotes are often called literals because they are printed literally, exactly as they appear. Variable names have the value they contain (either a number or a string) printed. Functions also have their number values printed. Punctuation marks are used to help format the data neatly on the screen. The comma tabs to the nearest tenth column, while the semicolon prints items next to each other. Either punctuation mark can be used as the last symbol in the statement. This results in the next PRINT statement acting as if it is continuing the previous PRINT statement. PRINT on its own moves to the start of the next line - leaving a blank line. EXAMPLES: RESULTS 10 PRINT "HELLO" HELLO 20 A$=" THERE":PRINT "HELLO";A$ HELLO THERE 30 A=4:B=2:PRINT A+B 6 40 J=41:PRINT J;:PRINT J-1 41 40 50 PRINT A;B;:D=A+B:PRINTD;A-B 4 2 6 2 See also POS, SPC and TAB Functions, in Section 18, paragraphs 18.24, 18.37, and 18.40, respectively. 17.67 PRINT# Output data to files. PRINT# file number, print list There are a few differences between this statement and the PRINT. Most im- portantly, the word PRINT# is followed by a number, which refers to the data file previously OPENed. The number is followed by a comma and a list of items to be output to the file. The semicolon acts in the same manner for spacing in printers as it does in the PRINT statement, commas output 10 spaces. Some devices may not work with TAB and SPC. EXAMPLES: 10 OPEN 4,4 20 PRINT#4,"HELLO THERE!",A$,B$ Outputs the data "HELLO THERE" and the variables A$ and B$ to the printer. 10 OPEN 2,8,2,"DATAFILES,S,W" 20 PRINT#2,A,B$,C,D This example outputs the data variables A, B$, C and D to the disk file number 2. NOTE: The PRINT# command is used by itself to clear the channel to a device after outputting via CMD and before closing the file as follows: OPEN 4,4 CMD 4 LIST PRINT#4 CLOSE 4 See also the CMD command, in paragraph 17.15. 17.68 PRINT USING ----------- Output using format PRINT[#filenumber,] USING "format list"; print list This statement defines the format of string and numeric items for printing to the text screen, printer or other device. The format is put in quotes. This is the format list. Then add a semicolon and a list of what is to be printed in the format for the print list. The list can be variables or the actual values to be printed, separated by commas. FORMAT STRING USED WITH CHARACTER NUMERIC STRING Hash sign (#) X X Plus sign (+) X Minus sign (-) X Decimal point (.) X Comma (,) X Dollar sign ($) X Four Carets (^^^^) X Equal sign (=) X Greater than sign (>) X The hash sign {#} reserves room for a single character in the output field. With Numeric Data if the data item contains more characters than there are # signs in the format field, the entire field is filled with asterisks {*}; no characters are printed. EXAMPLE: 10 PRINT USING "####";X For these values of X, this format displays: X = 12.34 12 X = 567.89 568 Note that the number is rounded up. X = 123456 **** For a STRING item, the string data is truncated at the bounds of the field. Only as many characters are printed as there are hash signs in the format item. Truncation occurs on the right. The plus (+) and minus (-) signs can be used in either the first or the last position of the format field, but not both. The plus sign is printed if the number is positive. The minus sign is printed if the number is nega- tive. If a minus sign is used and the number is positive, a blank is printed in the character position indicated by the minus sign. If neither a plus nor a minus sign is used in the format field for a nume- ric data item, a minus sign is printed before the first digit or dollar symbol if the number is negative. No sign is printed if the number is posi- tive. This means that one additional character, the minus sign, is printed if the number is negative. If there are too many characters to fit into the field specified by the hash signs and plus/minus sign, then an overflow oc- curs and the field is filled with asterisks {*}. A decimal point {.} symbol designates the position of the decimal point in the number. There can be only one decimal point in any format field. If a decimal point is not specified in the format field, the value is rounded to the nearest integer and printed without decimal places. When a decimal point is specified, the number of digits preceding the deci- mal point (including the minus sign, if the value is negative) must not exceed the number of hash signs before the decimal point. If there are too many digits, an overflow occurs and the field is filled with asterisks {*}. A comma {,} allows placing of commas in numeric fields. The position of the comma in the format list indicates where the commas appear in a printed number. Only commas within a number are printed. Unused commas to the left of the first digit appear as filler character. At least one hash sign must precede the first comma in the field. If commas are specified in a field and the number is negative, then a minus sign is printed as the first character, even if the character position is specified as a comma. A dollar sign ($) symbol shows that a dollar sign will be printed in the number. If the dollar sign is to float (always be placed before the num- ber), at least one hash sign must be specified before the dollar sign. If a dollar sign is specified without a leading hash sign, the dollar sign is printed in the position shown in the format field. If a plus or minus sign are specified in a format field with a dollar sign, the program prints the sign before the dollar sign. EXAMPLES: Field Expression Result Comment ##.# -.1 -0.1 Leading zero added. ##.# 1 1.0 Trailing zero added. #### -100.5 -101 Rounded to no decimal places. #### -1000 **** Overflow because four digits and a minus sign cannot fit in field. ###. 10 10. Decimal point added. #$## 1 $1 Leading dollar sign. The up arrows or caret symbols {^^^^} are used to specify that the number is to be printed in the E format (scientific notation). A hash sign must be used in addition to the four carets to specify the field width. The carets must appear after the hash sign in the format field. Four carets must be specified when a number is to be printed in E format. If fewer than four carets are specified, a syntax error results. If more than four carets are specified, only the first four are used. The fifth and subsequent carets are interpreted as text symbols. You can specify a {+} or {-} sign after the carets if you require a trailing sign. An equal {=} sign is used to centre a string in a field. The field width is specified by the number of characters (the hash signs and an equal sign) in the format field. If the string contains fewer characters than the field width, the string is cen- tered in the field. If the string contains more characters than can be fitted into the field, then the rightmost characters are truncated and the string fills the entire field. A greater than {>} sign is used to right justify a string in a field. Other characters can be included in a format string, these are treated as literals. This allows you to build up tables and charts. See line 30 in the program below for a specific example of this. EXAMPLE: 5 X=32: Y=100.23: A$="CAT": B$="COMPUTER" 6 F$=* #=########## * #$##.## *+CHR$(13) 10 PRINT USING "$##.##";13.25,X,Y 20 PRINT USING "###>#";"CBM",A$ 30 PRINT USING F$;A$,X,B$,Y (CHR$(13) is {return}) When this program is RUN, line 10 prints: $13.25 $32.00 $***** Five asterisks {*****} are printed instead of a Y value, because Y has five digits which does not con- form to the format list (as explained above). Line 20 prints this: CBM CAT Leaves two spaces before printing the string, as defined in the format list. Line 30 prints this: * CAT * $23.00 * * COMPUTER * $100.23 * 17.69 PUDEF ----- Redefine symbols in PRINT USING statements. PUDEF "nnnn" Where "nnnn" is any combination of characters, up to four in all, PUDEF allows you to redefine any of the following four symbols in the PRINT USING statement: blanks, commas, decimal points and dollar signs. These four sym- bols can be changed into some other character by placing the new character in the correct position in the PUDEF control string. Position 1 is the filler character. The default is a blank. Place a new character here for another character to appear in place of blanks. Position 2 is the comma character. Default is a comma. Position 3 is the decimal point. Default is a decimal point. Position 4 is the dollar sign. Default is a dollar sign. EXAMPLE: 10 PUDEF"*" PRINTs * in the place of blanks. 20 PUDEF" <" PRINTs < in the place of commas. NOTE: All positions up to the one(s) to be changed must be specified. For example PUDEF " $" would print the $ in place of the dollar sign, but the decimal point, comma and filler character would all be set to space. PUDEF only affects numeric formats i.e. PUDEF "0" will change filler spaces in numbers to leading 0s, but will not affect filler spaces in strings. The character to replace the $ has no effect unless the $ in the format string of PRINT USING is preceded by a # (i.e. is floating). 17.70 READ Read data from DATA statements and input it into the computer's memory (while the program is RUNning) READ variable list This statement takes information from DATA statements and stores them in variables, where the data can be used by the RUNning program. The READ statement variable list may contain both strings and numbers. Be careful to avoid reading strings where the READ statement expects a number, this pro- duces a TYPE MISMATCH ERROR message. The data in the DATA statements are READ in sequential order. Each READ statement can read one or more data items. Every variable in the READ statement requires a DATA item. If one is not supplied, an OUT OF DATA ERROR occurs. In a program, you can READ the data and the reREAD by issuing the RESTORE statement. The RESTORE statement sets the sequential data pointer back to the beginning, where the data can be READ again. See the RESTORE statement, in paragraph 17.75. EXAMPLES: 10 READ A, B, C 20 DATA 3, 4, 5 READ 3 data items (which must be numeric or an error will occur) into variables A, B and C. 10 READ A$, B$, C$ 20 DATA JOHN, PAUL, GEORGE READ three strings from DATA statements. 10 READ A, B$, C 20 DATA 1200, NANCY, 345 READ a numeric value, a string, and another numeric value. 17.71 RECORD ------ Position relative file pointers. RECORD#logical file number, record number [,byte] This statement positions a relative file pointer to select any byte (character) of any record in the relative file. The logical file number can be in the range between 1 and 255. The record number can be in the range 1 through 65535. Byte number is in the range 1 through 254. See your disk drive manual for details about relative files. When the record number value is set higher than the last record number in the file, the following occurs: For a write (PRINT#) operation, additional records are created to expand the file to the desired record number. For a read (INPUT# or GET#) operation, a null record is returned and a RECORD NOT PRESENT error occurs. EXAMPLE: 10 DOPEN #2,"CUSTOMER" 20 RECORD#2,10,1 30 PRINT#2,A$ 40 DCLOSE #2 This example opens an existing relative file called "CUSTOMER" as file number 2 in line 10. Line 20 positions the relative file pointer at the first byte in record number 10. Line 30 actually writes the data, A$, to the file. The RECORD command accepts variables for its parameters. It is often con- venient to place the RECORD command within a FOR... NEXT or DO loop. Also see DOPEN, in paragraph 17.31. 17.72 REM Comment or remark about the operation of a program line. REM [message] The REMark statement is a note to whoever is reading a listing of the pro- gram. REM may explain a section of the program, give information about the author, etc. REM statements do not affect the operation of the program, except to add length to it (and therefore use more memory). Nothing to the right of the keyword REM is interpreted by the computer as an executable instruction. Therefore, no other executable statement can follow a REM on the same line. EXAMPLE: 1010 NEXT X: REM END OF MAIN PROGRAM LOOP 17.73 RENAME ------ Change the name of a file on disk. RENAME [Ddrive number,] "old filename" TO "new filename" [Udevice number] This command is used to rename a file on disk, from the old filename to the new filename. The diskdrive does not RENAME a file if it is OPEN. EXAMPLES: RENAME D0, "TEST" TO "FINAL TEST" Change the name of the file "TEST" to "FINAL TEST". RENAME D0,(A$) TO (B$),U9 Change the filename specified in A$ to the filename specified in B$ on drive 0, device number 9. Remember, whenever a variable name is used as a filename, it must be enclosed in parentheses. 17.74 RENUMBER -------- Renumber lines of a BASIC program. RENUMBER [new starting line number] [,increment] [,old starting line number] The new starting line is the number of the first line in the program after renumbering; the default is 10. The increment is the interval between line numbers (i.e. 10, 20, 30, etc.); the increment default value is also 10. The old starting line number is the first line number before you renumber the program. The default in this case is the first line of the program. This command can only be executed from direct mode. An UNRESOLVED REFERENCE error occurs if any reference to number that does not exist is encountered. An OUT OF MEMORY occurs if RENUMBERing expands the program beyond its limits. A LINE NUMBER TOO LARGE error occurs if RENUMBER generates a line number of 64000 or higher. These errors leave the program unharmed. EXAMPLES: RENUMBER Renumbers the program starting at 10, and increments each additional line by 10. RENUMBER 20,20,15 Starting at line 15, renumbers the program. Line 15 becomes 20, and other lines are numbered in incre- ments of 20. RENUMBER,,65 Starting at line 65, renumbers in increments of 10. Line 65 becomes 10. If you omit a parameter, you must still enter a comma as a placeholder. There must be no line between 10 and 64 inclusive. ALWAYS SAVE YOUR PROGRAM BEFORE RENUMBERING, because very long programs can cause a SYSTEM crash when RENUMBERed with larger line numbers. Also note that long programs should be RENUMBERed in FAST mode as they will take a long time to renumber (up to 30 minutes for a 55K program in FAST). If you only have a 40 column display use FAST:RENUMBER... {return}. Then type SLOW {return}. While RENUMBERing is taking place you will not see any- thing happening. When RENUMBERing has finished, you display will return. If you have an 80 column display or 40/80 column display select the 80 column screen before typing FAST. 17.75 RESTORE/RESTORE ------- Reset READ pointer to DATA statement so the DATA can be reREAD. RESTORE (C64 mode) RESTORE [line #] (C128 mode) When executed in a program, the pointer to the item in a DATA statement that is to be READ next is reset to the first item in the DATA statement. This provides the capability to reREAD the data. If a line number follows the RESTORE statement the READ pointer is set to the first data item after the specified program line. Otherwise the pointer is reset to the beginning of the BASIC program. In C64 mode there is no option to specify the line number, i.e. you can only RESTORE to the beginning of the program. EXAMPLES: 10 FOR I=1 TO 3 20 READ X 30 T = X + T 40 NEXT 45 PRINT T 50 RESTORE 69 GOTO 10 70 DATA 10,20,30 This example READs the data in line 70 and stores it in numeric variable X. It adds the total (T) of all the numeric data items. Once all the data has been READ, three cycles through the loop, the READ pointer is RESTOREd to the beginning of the program and it returns to line 10 and performs repeti- tively. 10 READ A,B,C 20 DATA 100,500,750 30 READ X,Y,Z 40 DATA 36,24,38 50 RESTORE 40 60 READ S,P,Q 70 PRINT A,B,C 80 PRINT X,Y,Z 90 PRINT S,P,Q This example RESTOREs the DATA pointer to the first data item in line 40. When line 60 is executed, it will READ the DATA 36,24,38 from line 40, since you don't need to READ line 20's DATA again. NOTE: If a line number is specified the line must exist! A variable can be used e.g. RESTORE LR. 17.76 RESUME ------ Define where the program will continue (RESUME) after an error has been trapped. RESUME [line # | NEXT] This statement is used to restart program execution after TRAPping an error. With no parameters, RESUME attempts to re-execute the line in which the error occurred. RESUME NEXT resumes execution at the statement im- mediately following the one containing the error; RESUME followed by a line number will GOTO the specific line and resumes execution from that line number. RESUME can only be used in program mode. EXAMPLE: 10 TRAP 100 20 INPUT "ENTER A NUMBER";A 30 B=100/A 40 PRINT"THE RESULT=",B:PRINT"THE END" 50 PRINT"DO YOU WANT TO RUN IT AGAIN(Y/N)":GETKEYZ$:IF Z$="Y"THEN 20 60 STOP 100 INPUT"ENTER ANOTHER NUMBER (NOT ZERO)";A 110 RESUME This example traps a division by zero error in line 30 if 0 is entered in line 20. If zero is entered, the program goes to line 100, where you are asked to input another number besides 0. Line 110 returns to line 30 to complete the calculation. Line 50 asks if you want to repeat the program again. If you do, press the {y} key. 17.77 RETURN Return from subroutine. RETURN This statement is always paired with the GOSUB statement. When a program encounters a RETURN statement, it goes to the statement immediately fol- lowing the last GOSUB command executed. If no GOSUB was previously issued, the a RETURN WITHOUT GOSUB error message is displayed and the program stops. All subroutines end with a RETURN statement. EXAMPLE: 10 PRINT "ENTER SUBROUTINE" 20 GOSUB 100 30 PRINT "END OF SUBROUTINE" . . . 90 STOP 100 PRINT "SUBROUTINE 1" 110 RETURN This example calls the subroutine at line 100 which prints the message "SUBROUTINE 1" and RETURNs to line 30, the rest of the program. 17.78 RREG ---- Read the contents of the accumulator AC, X register XR, Y register YR and Status register SR. RREG [var1] [, [var2] [, [var3] [, [var4] ] ] ] After a SYS command is issued, the contents of the CPU registers AC, XR, YR and SR are stored in memory before the C128 returns to BASIC. The memory locations of these stores are: AC -> 6 XR -> 7 YR -> 8 SR -> 5 With the RREG command the values in these memory stores are loaded into the specified variables. The values range between zero and 255 (inclusive). Not all variables have to be specified. For instance, it is possible to only read the contents of YR: RREG , ,YR : PRINT YR EXAMPLE: 100 FOR I=4864 TO 4870 110 READ D : POKE I,D 120 NEXT I 130 DATA 169,6,162,7,160,8,96 131 REM ML PRG 132 REM 133 REM 01300 LDA #6 ; LOAD AC WITH VALUE 6 134 REM 01302 LDX #7 ; LOAD XR WITH VALUE 7 135 REM 01304 LDY #8 ; LOAD YR WITH VALUE 8 136 REM 01306 RTS ; END ML SUBROUTINE 140 SYS 4864 150 RREG AC, XR, YR 160 PRINT "AC=";AC, "XR=";XR, "YR=";YR 170 M6 = PEEK(6) : REM MEMORY LOCATION 6 180 M7 = PEEK(7) : REM MEMORY LOCATION 7 190 M8 = PEEK(8) : REM MEMORY LOCATION 8 200 PRINT "MEMORY LOCATIONS 6, 7 AND 8:"; M6;","M7;","M8 Line 160 prints this: AC= 6 XR= 7 YR= 8 Line 200 prints this: MEMORY LOCATIONS 6, 7 AND 8: 6 , 7 , 8 17.79 RUN/RUN --- Execute BASIC program. RUN [line #] RUN "filename" [,Ddrive number] [Udevice number] (BASIC 7.0 only) Once a program has been typed into memory or LOADed, the RUN command exe- cutes it. RUN clears all variables in the program before starting program execution. If there is a number following the RUN command, execution starts at that line number. If there is a filename following the RUN command, the named file is loaded from the disk drive and RUN, with no further action required by the user. RUN may be used within a program. The default drive number is 0 and default device number is 8. EXAMPLES: RUN Starts execution from the beginning of the program currently in memory. RUN 100 Starts program execution at line 100. RUN"PRG1" DLOADs "PRG1" from disk drive 8, and runs it from the first line. RUN(A$) DLOADs the program named in the variable A$ and runs it from the first line. 17.80 SAVE Store the program in memory to disk or tape. SAVE ["filename"] [,device number] [,EOT flag] This command stores the program currently in memory onto cassette tape or disk for later retrieval. If SAVE is typed alone an unnamed file will be saved to tape. Tape is a sequential system and, therefore, it is up to the user to ensure that there is nothing important on the tape before SAVEing (see VERIFY, in paragraph 17.100). To give your program a name simply en- close the chosen name in quotes (or use a string variable) immediately after typing SAVE. A filename can be up to 16 characters. NOTE: When SAVEing to disk you must specify a filename or you will get a MISSING FILE NAME ERROR. To specify the device number (e.g. 1 for tape) place a comma followed by the device number after the closing quote following the filename. The final parameter (EOT) follows the device number and is again seperated by a comma. It has no significance when used with disk and can have one of four values when used with tape. These options are: 0 Default - no action. 1 SAVE so that the relocate function of LOAD does not work, i.e. the file will always load back at the address from which it was SAVEd. 2 Write an END OF TAPE marker at the end of the file - attempts to LOAD beyond the end of a file saved this way will generate a FILE NOT FOUND ERROR. 3 SAVEs in non-relocatable format (1) and writes the EOT (2). NOTE: If you specify the device number or EOT parameter the filename (and device number) must be included. For tape this may be a null (""). See the following examples. EXAMPLES: SAVE "HELLO" Stores a program on tape, under the name HELLO SAVE A$,8 Stores on disk, with the name stored in variable A$. SAVE "HELLO",8 Stores on disk, with the name HELLO (equivalent to DSAVE "HELLO"). SAVE "HELLO", 1, 2 Stores on tape, with the name HELLO, and places an END-OF-TAPE marker after the program. SAVE "",1,3 Stores on tape, with no name, places an EOT marker after the program, does not allow the program to be relocated on loading. 17.81 SCALE ----- Alter scaling in graphics mode. SCALE n [,xmax,ymax] where: n = 1 (on) or 0 (off) xmax is in the range 320-32767, default 1023 (hi-res) default 2047 (multicolor) ymax is in the range 200-32767, default 1023 Changes the scaling of the bit map display coordinates in both multicolor and high resolution modes. Coordinates for the MOVSPR command are also scaled. Maps many logical points to one physical point. This is helpful when you need to plot data over a wide range of values - it will not help if you have a large cluster of data with only high values. Because multicolor uses 2 physical pixels on the x-axis per dot, its normal display is: X=0 to 159 ; Y=0 to 199 as opposed to X=0 to 319 ; y=0 to 199 If you wish to use the same coordinates for multicolor and hi-res use SCALE 1,640,200 after setting up a multicolor screen and use the default SCALE values for both types of screen. NOTE: The GRAPHIC command turns scaling off, i.e. using GRAPHIC (something) is equivalent to GRAPHIC...: SCALE 0. EXAMPLE: 10 GRAPHIC 1: GOSUB 100 20 SCALE 1: GOSUB 100 30 SCALE 1,5000,5000: GOSUB 100 40 END 100 CIRCLE 1,160,100,60: RETURN 17.82 SCNCLR ------ Clear screen. SCNCLR [mode number] Mode Number Mode 0 40 column (VIC) text. 1 bit map*. 2 split screen bit map*. 3 multicolor bit map*. 4 split screen multicolor bit map*. 5 80 column (VDC 8563) text. This statement with no arguments clears the graphics screen, if it is pre- sent, otherwise the current text screen is cleared**. EXAMPLES: SCNCLR 5 Clears 80 column text screen. SCNCLR 1 Clears the (VIC) bit map screen. SCNCLR 4 Clears the (VIC) multicolor bit map split screen. NOTE *: The bit map area is the same for both hi-res and multicolor, the different mode numbers select other parameters to clear e.g. 40 column text (2 and 4) and color RAM (3 and 4). NOTE **: If a graphics screen has been created but is not selected (GRAPHIC=0) it will not be cleared. If you are using 2 screens (80 column for text and 40 column for graphics) SCNCLR will clear both text and graphics screens if called from the 80 column screen. 17.83 SCRATCH ------- Delete a file from the disk directory. SCRATCH "filename" [,Ddrive number] [Udevice number] This command deletes a file form the disk directory. As a precaution, the system asks "Are you sure?" (in direct mode only) before the Commodore 128 starts the operation. Type a {y} to perform the SCRATCH or press any other key to cancel the operation. Use this command to erase unwanted files, and to create more space on the disk. The filename may contain template, or wildcards (?,*). The default drive number is 0 and default device number is 8. EXAMPLE: SCRATCH "MY BACK",D0 This erases the file "MY BACK" from the disk in drive 0 of unit 8. 17.84 SLEEP ----- Delay program for a specific period of time. SLEEP n where n is seconds (0 < n < 65536) If you select a delay which is too long for your program and you want to halt it, the {stop} key can be used to break into a delay. 17.85 SLOW ---- Return the Commodore 128 to 1 Mhz operation. SLOW The Commodore 128 is capable of running the 8502 microprocessor at a speed of 1 or 2 Megahertz (Mhz). The SLOW command slows down the microprocessor to 1 Megahertz from 2 Mega- hertz. The FAST command sets the Commodore 128 at 2 Mhz. The Commodore 128 can process commands substantially faster at 2 Mhz than at 1 Mhz. Note, however, that the 40 column screen cannot be used at 2 Mhz. 17.86 SOUND ----- Outputs sound effects and musical notes. SOUND v, f, d [, dir] [, m] [, s] [, w] [, p] where: v = voice 1, 2 or 3 f = frequency value (0-65535) d = duration (0-32767) dir = step direction (0 = up, 1 = down, 2 = oscillate), default=0 m = minimum frequency (0-65535) if the sweep is used, default=0 s = step value for sweep (0-65535), default=0 w = waveform (0 = triangle, 1 = sawtooth, 2 = pulse, 3 = noise), default=2 p = pulse width (0-4095), default=2048 The SOUND command is a fast and easy way to create sound effects and musi- cal tones. The three required parameters v, f and d select the voice, fre- quency and duration of the sound. The duration is in units called jiffies. Sixty jiffies equals 1 second. The SOUND command can sweep through a series of frequencies which allows sound effects to pass through a range of notes. Specify the direction of the sweep with the dir parameter. Set the minimum frequency of the sweep with m and the step value of the sweep with s. Select the appropriate wave- form with w and specify p as the width of the variable pulse waveform if selected in w. EXAMPLES: SOUND 1,40960,60 Play a SOUND at frequency 40960 in voice 1 for 1 second. SOUND 2,2000,5,0,2000,100 Output a sound by sweeping through the fre- quencies starting at 2000 and incrementing upward in units of 100. SOUND 3,5000,1,2,3000,500,1 This example outputs a range of sounds starting at a minimum frequency of 3000, through 5000, in increments of 500. The di- rection of the sweep is back and forth (oscillating). The selected waveform is saw- tooth and the voice selected is 3. 17.87 SPRCOLOR -------- Set multicolor 1 and/or multicolor 2 colors for all sprites. SPRCOLOR [smcr1] [, smcr2] where: smcr1 = multicolor 1 for all sprites. smcr2 = multicolor 2 for all sprites. These parameters may be any color from 1 through 16. EXAMPLES: SPRCOLOR 3,7 Sets sprite multicolor 1 to red and multicolor 2 to blue. SPRCOLOR 1,2 Sets sprite multicolor 1 to black and multicolor 2 to white. 17.88 SPRDEF ------ Enter the SPRite DEFinition mode to create and edit sprite images (40 column display only). SPRDEF The SPRDEF command defines sprites interactively. Entering the SPRDEF command, displays a sprite work area on the screen which is 24 characters wide by 21 characters tall. Each character position in the grid corresponds to a sprite pixel in the sprite displayed to the right of the work area. Here is a summary of the SPRite DEFinition mode operations and the keys that perform them: At the SPRITE NUMBER? prompt user input description {return} Exits SPRite DEFinition mode at the SPRITE NUMBER? prompt only. {1} - {8} Selects a sprite number and enters sprite edit mode. In the sprite edit mode user input description {a} Turns on and off Automatic cursor movement. {crsr} Moves cursor. keys {return} Moves cursor to start of next line. {home} Moves cursor to top left corner of sprite work area. {clr} Erases entire grid. {1}-{4} Selects color source: 1 = clear 2 = foreground 3 = multicolor 1 4 = multicolor 2 {ctrl 1} - Selects sprite foreground color (1-8). {ctrl 8} {C= 1} Selects sprite foreground color (9-16). - {C= 8} {stop} Cancels changes and returns to the READY prompt. {shift Saves sprite in memory and returns to the SPRITE NUMBER? return} prompt. {x} Expands sprite in X (horizontal) direction - Toggle. {y} Expands sprite in Y (vertical) direction - Toggle. {m} Standard sprite / Multicolor sprite - Toggle. {c} Copies sprite data from one sprite to another. NOTE: Using SPRDEF will clear the bit map screen. 17.89 SPRITE ------ Turn on or off, color, expand and set screen priorities for a sprite. SPRITE [,on/off] [,fgnd] [,priority] [,x-exp] [,y-exp] [,mode] The SPRITE statement controls most of the characteristics of a sprite. Parameter Description number Sprite number (1-8). on/off Turns sprite on (1) or off (0). fgnd Sprite foreground color (1-16). priority Priority is 0 if sprites appear in front of object on the screen; priority is 1 if sprites appear behind objects on the screen. x-exp Horizontal EXPansion on (1) or off (0). y-exp Vertical EXPansion on (1) or off (0). mode Select standard sprite (0) or multicolor sprite (1). (See SPRCOLOR, in paragraph 17.87) Unspecified parameters in subsequent sprite statements take on the charac- teristics of the previous SPRITE statement. You can check the characteris- tics of a SPRITE with the RSPRITE function. EXAMPLES: SPRITE 1,1,3 Turn on SPRITE number 1 and color it red. SPRITE 2,1,7,1,1,1 Turn on SPRITE number 2, color it blue, make it pass behind objects on the screen and expand it in horizontal and vertical directions. SPRITE 6,1,1,0,0,1,1 Turn on SPRITE number 6, color it black. The first appearing 0 tells the computer display the sprites are in front of objects on the screen. The second 0 and the following 1 tell the C128 to expand the sprite vertically only. The last 1 specifies the sprite to be displayed in multico- lor mode. Use the SPRCOLOR command to select the sprite's multicolor. SPRITE 7,,,,1 Set the horizontal expansion of SPRITE number 7 - all other options retain their previous settings. 17.90 SPRSAV ------ Store a sprite data from a text string variable into a sprite storage area or vice versa. SPRSAV origin,destination This command transfers a sprite image from a string variable to a sprite storage area. It can also tranfer data from the sprite storage area into a string variable. Either the origin or the destination can be a sprite num- ber or a string variable but they both cannot be string variables (they both CAN be sprite numbers, however). If you are moving a string into a sprite, only the first 63 bytes of data are used. The rest are ignored, since a sprite can only hold 63 data bytes. NOTE: SPRSAV sprite, string produces a string in the same format as SSHAPE so that it can be used with GSHAPE to 'fix' a sprite onto hi-res screen. The string will be 67 characters long. EXAMPLES: SPRSAV 1,A$ Transfers the image pattern from sprite 1 to the string named A$. SPRSAV B$,2 Transfers the data from the string variable B$ into sprite 2. SPRSAV 2,3 Transfers the data from sprite 2 to sprite 3. 17.91 SSHAPE/GSHAPE ------------- Save/retrieve shapes to/from string variables. SSHAPE and GSHAPE are used to save and load rectangular areas of multicolor or standard bit mapped screen to/from BASIC string variables. The command to save an area of the screen into a string variable is: SSHAPE string variable, x1, y1 [, x2, y2] where: string variable String name to save data in x1, y1 Corner coordinates (0,0 through 319,199) (scaled). x2, y2 Corner coordinates opposite (x1,y1) (default is the PC) Because BASIC limits strings to 255 characters, the size of the area that can be saved is limited. The string size required can be calculated using one of the following (unscaled) formulas: L(hi-res) = INT( (ABS(x1-x2) + 1) / 8 + .99) * (ABS(y1-y2) + 1) + 4 L(multicolor) = INT( (ABS(x1-x2) + 1) / 4 + .99) * (ABS(y1-y2) + 1) + 4 NOTE: The upper limits of the coordinates (319,199 for standard and 159,199 for multicolor bit mapped graphics) apply to the unSCALEd coordinate system. When SCALE is turned on, the limit are set by the SCALE command. The command to retrieve (load) the data from a string variable and display it on specified screen coordinates is: GSHAPE string variable, [x,y] [,mode] where: string Contains shape to be drawn. x,y Top left coordinates (0,0 through 319,199) telling where to draw the shape (scaled), default is the pixel cursor. mode Replacement mode: 0: place shape as is (default). 1: invert (reverse) shape. 2: OR shape with area. 3: AND shape with area. 4: XOR shape with area. The replacement mode allows you to change the data in the string variable so that you can invert it, perform a logical OR, exclusive OR or AND operation on the image. Also see the LOCATE command, in paragraph 17.57, for information on the pixel cursor. EXAMPLES: SSHAPE A$,10,10 Saves a rectangular area from the coordinates (10,10) to the location of the pixel cursor, into string variable A$. SSHAPE B$,20,30,47,51 Saves a rectangular area from top left coordinates (20,30) throught bottom coordinates (47,51) into string variable B$. GSHAPE A$,120,20 Retrieves shaped contained in string variable A$ and displays it at top left corner at coordinates (120, 20). GSHAPE B$,30,30,1 Retrieves shape contained in string B$ and displays it at top left coordinates (30,30). The shape is inverted due to the replacement mode being selected by the 1. NOTE: Beware using modes 1-4 with multicolor shapes. You may obtain unpre- dictable results. 17.92 STASH ----- Move contents of host memory to expansion RAM. STASH #bytes, intsa, expsa, expb Refer to FETCH command for description of parameters. 17.93 STOP Halt program execution. STOP This statement halts the program. A message, BREAK IN LINE xxx occurs (in program mode), where xxx is the line number containing the STOP command. The program can be restarted at the statement following STOP if the CONT command is used immediately, without any editing occuring in the listing. The STOP statement is often used while debugging a program. 17.94 SWAP ---- Swap contents of host RAM with contents of expansion RAM. SWAP #bytes, intsa, expsa, expb Refer to FETCH command for description of parameters. 17.95 SYS/SYS --- Call and execute a machine language subroutine at the specified address. SYS address (C64 mode) SYS address [, [a] [, [x] [, [y] [, [s] ] ] ] ] (C128 mode) This statement performs a call to a machine code subroutine at the given address in a memory configuration set up according to the BANK command. Optionally, arguments a, x, y and s are loaded into the accumulator, x, y and status registers respectively, before the subroutine is called. The address range is 0 to 65535 (both inclusive). The program begins exe- cuting the machine language program starting at that memory location. Also see the BANK command, in paragraph 17.4. EXAMPLES: SYS 40960 Calls and executes the machine language routine at location 40960. SYS 8192,0 Calls and executes the machine language routine at location 8192 and loads zero into the accumulator. 17.96 TEMPO ----- Define the speed of the song being played. TEMPO n where n is a relative duration between 1 and 255 (inclusive). The actual duration for a whole note is determined by using the formula given below: whole note duration = 23.06/n seconds The default value of n is 8, and note duration decreases with n. EXAMPLES: TEMPO 16 Defines the TEMPO at 16. TEMPO 1 Defines the TEMPO at the slowest speed. TEMPO 250 Defines the TEMPO at 250. 17.97 TRAP ---- Detect and handle program errors while a BASIC program is RUNning. TRAP [line#] When turned on, TRAP intercepts all error conditions (excluding DOS error messages, but including the {stop} key). In the event of any execution er- ror, the error flag is set and execution is transferred to the line number specified in the TRAP statement. The line number in which the error occurred can be found by using the system variable EL. The specific error condition is contained in system variable ER. The string function ERR$(ER) gives the error message corres- ponding to the error condition. The RESUME statement can be used to resume program execution. TRAP with no line number turns off error trapping. An error in a TRAP routine cannot be trapped, unless it contains a TRAP statement of its own. EXAMPLE: 100 TRAP 1000 If an error occurs, go to line 1000. 1000 ?ERR$(ER);EL Print the error message, and the error line number. 1010 RESUME Resume program execution. 17.98 TROFF ----- Turn OFF error TRacing mode. TROFF This statement turns off trace mode. 17.99 TRON ---- Turn ON error TRacing mode. TRON TRON is used in program debugging. This statement begins trace mode. When you RUN the program, the line numbers of the program appear in bracke