3.0. System Software 3.1. BASIC 10.0 C64DX BASIC 10.0 3.1.1. INTRODUCTION This section lists BASIC 10.0 commands, statements, and functions in alphabetical order. It gives a complete list of the rules (syntax) of BASIC 10.0, along with a concise description of each. COMMAND AND STATEMENT FORMAT The commands and statements presented in this section are governed by consistent format conventions designed to make them as clear as possible. In most cases, there are several actual examples to illustrate what the actual command looks like. The following example shows some of the format conventions that are used in the BASIC commands: EXAMPLE: DLOAD <"program name"|(file_name_var)> [,U#] [,D#] | | | | | | | | keyword argument (if any) optional arguments The parts of the command or statement that the user must type in exactly as they appear are in capital letters. Words that don't have to be typed exactly, such as the name of the program, are not capitalized. When quote marks (" ") appear (usually around a program or file name), the user should include them in the appropriate place according, to the format example. KEYWORDS, also called RESERVED WORDS, appear in uppercase letters. THESE KEYWORDS MUST BE ENTERED EXACTLY AS THEY APPEAR. However, many keywords have abbreviations that can also be used. Keywords are words that are part of the BASIC language that the computer understands. Keywords are the central part of a command or statement. They tell the computer what kind of action to take. These words cannot be used as variable names. ARGUMENTS (also called parameters) appear in lower case. Arguments are the parts of a command or statement; they complement keywords by providing specific information about the command or statement. For example, a keyword tells the computer to load a program, while the argument tells the computer which specific program to load and a second argument specifies which drive the disk containing the program is in. Arguments include filenames, variables, line numbers, etc. SQUARE BRACKETS [] show OPTIONAL arguments. The user selects any or none of the arguments listed, depending on the requirements. ANGLE BRACKETS <> indicates that the user MUST choose one of the arguments listed. VERTICAL BAR | separates items in a list of arguments when the choices are limited to those arguments listed, and no other arguments can be used. Then the vertical bar appears in a list enclosed in SQUARE BRACKETS, the choices are limited to the items in the list, but still have the option not to use any arguments. ELLIPSIS ..., a sequence of three dots, means that an option or argument can be repeated more than once. QUOTATION MARKS " " enclose character strings, filenames, and other expressions. When arguments are enclosed in quotation marks in a format, the quotation marks must be included in a command file or statement. Quotation marks are not conventions used to describe formats; they are required parts of a command or statement. PARENTHESES () When arguments are enclosed in parentheses in a format, they must be included in a 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$, or T%. EXPRESSION means any valid BASIC expression, such as A+B+2 or .5*(X+3). 3.1.2. ALPHABETICAL LIST OF COMMANDS, FUNCTIONS, and OPERATORS * Token = AC multiplication + Token = AA addition - Token = AB subtraction / Token = AD division < Token = B3 less-than = Token = B2 equal > Token = B1 greater-than ^ Token = AE exponentiation (PI) Token = FF return value of PI ABS Token = B6 absolute function AND Token = AF logical AND operator APPEND Token = FE,0E append file ASC Token = C6 string to PETSCII function ATN Token = C1 trigonometric arctangent function AUTO Token = DC auto line numbering BACKGROUND Token = FE,3B background color BACKUP Token = F6 backup diskette BANK Token = FE,02 memory bank selection BEGIN Token = FE,18 start logical program block BEND Token = FE,19 end logical program block BLOAD Token = FE,11 binary load file from diskette BOOT Token = FE,1B load & run ML, or BASIC autoboot BORDER Token = FE,3C border color BOX Token = E1 draw graphic box BSAVE Token = FE,10 binary save to disk file BUMP Token = CE,03 sprite collision function BVERIFY Token = FE,28 verify memory to binary file CATALOG Token = FE,0C disk directory CHANGE Token = FE,2C edit program CHAR Token = E0 display characters on screen CHR$ Token = C7 PETSCII to string function CIRCLE Token = E2 draw graphic circle CLOSE Token = A0 close channel or file CLR Token = 9C clear BASIC variables, etc. CMD Token = 9D set output channel COLLECT Token = F3 validate diskette (chkdsk) COLLISION Token = FE,17 enable BASIC event COLOR Token = E7 set screen colors CONCAT Token = FE,13 concatenate two disk files CONT Token = 9A continue BASIC program execution COPY Token = F4 copy a disk file COS Token = BE trigonometric cosine function CUT Token = E4 cut graphic area DATA Token = 83 pre-define BASIC program data DCLEAR Token = FE,15 mild reset of disk drive DCLOSE Token = FE,0F close disk channel or file DEC Token = D1 decimal function DEF Token = 96 define user function DELETE Token = F7 delete BASIC lines or disk file DIM Token = 86 dimension BASIC array DIR Token = EE disk directory DISK Token = FE,40 send disk special command DLOAD Token = F0 load BASIC program from disk DMA Token = FE,1F define & execute DMA command DMA Token = FE,21 " DMA Token = FE,23 " DMODE Token = FE,35 set graphic draw mode DO Token = EB start BASIC loop DOPEN Token = FE,0D open channel to disk file DPAT Token = FE,36 set graphic draw pattern DSAVE Token = EF save BASIC program to disk DVERIFY Token = FE,14 verify BASIC memory to file ELLIPSE Token = FE,30 draw graphic ellipse ELSE Token = D5 if/then/else clause END Token = 80 end of BASIC program ENVELOPE Token = FE,0A define musical instrument ERASE Token = FE,2A delete disk file ERRS Token = D3 BASIC error function EXIT Token = FD exit BASIC loop EXP Token = BD exponentiation function FAST Token = FE,25 set system speed to maximum FILTER Token = FE,03 set audio filter parameters FIND Token = FE,2B hunt for string in BASIC program FN Token = A5 define user function FOR Token = 81 start BASIC for/next loop FOREGROUND Token = FE,39 set foreground color FRE Token = B8 available memory function GCOPY Token = FE,32 graphic copy GENLOCK Token = FE,38 set video sync mode GET Token = Al receive a byte of input GO Token = CB program branch GOSUB Token = 8D program subroutine call GOTO Token = 89 program branch GRAPHIC Token = DE set graphic mode HEADER Token = F1 format a diskette HELP Token = EA display BASIC line causing error HEX$ Token = D2 return hexadecimal string function HIGHLIGHT Token = FE,3D set highlight color IF Token = 8B if/then/else conditional INPUT Token = 85 receive input data from keyboard INPUT# Token = 84 receive input data from channel (file) INSTR Token = D4 locate a string within a string INT Token = B5 integer function JOY Token = CF joystick position function KEY Token = F9 define or display function key LEFT$ Token = C8 leftmost substring function LEN Token = C3 length of string function LET Token = 88 variable assignment LINE Token = E5 draw graphic line, input line LIST Token = 9B list BASIC program LOAD Token = 93 load program from disk LOCATE Token = E6 (currently unimplemented) LOG Token = BC natural log function LOOP Token = EC end of do/loop LPEN Token = CE,04 lightpen position function MID$ Token = CA substring function MONITOR Token = FA enter ML Monitor mode MOUSE Token = FE,3E set mouse parameters MOVSPR Token = FE,06 set sprite position and speed NEW Token = A2 clear BASIC program area NEXT Token = 82 end of for-next loop NOT Token = A8 logical complement function OFF Token = FE,24 (subcommand) ON Token = 91 multiple branch or subcommand OPEN Token = 9F open I/O channel OR Token = B0 logical or function PAINT Token = DF graphic flood-fill PALETTE Token = FE,34 set palette color PASTE Token = E3 draw graphic area from cut buffer PEEK Token = C2 return memory byte function PEN Token = FE,33 set graphic pen color PIC Token = FE,37 graphic subcommand PLAY Token = FE,04 play musical notes from string POINTER Token = CE,0A address of string var function POKE Token = 97 change memory byte POLYGON Token = FE,2F draw graphic polygon POS Token = B9 text cursor position function POT Token = CE,02 return paddle position PRINT Token = 99 display data on text screen PRINT# Token = 98 send data to channel (file) PUDEF Token = DD define print-using symbols QUIT Token = FE,1E (currently unimplemented) RCLR Token = CD (currently unimplemented) RDOT Token = D0 (currently unimplemented) READ Token = 87 read program pre-defined program data RECORD Token = FE,12 set relative disk file record pointer REM Token = 8F BASIC program comment RENAME Token = F5 rename disk file RENUMBER Token = F8 renumber BASIC program lines RESTORE Token = 8C set DATA pointer, subcommand RESUME Token = D6 resume BASIC program after trap RETURN Token = 8E end of subroutine call RGR Token = CC (currently unimplemented) RIGHT$ Token = C9 rightmost substring function RMOUSE Token = FE,3F read mouse position RND Token = BB pseudo random number function RREG Token = FE,09 return processor registers after SYS RSPCOLOR Token = CE,07 return sprite color function RSPPOS Token = CE,05 return sprite position function RSPRITE Token = CE,06 return sprite parameter function RUN Token = 8A run BASIC program from memory or disk RWINDOW Token = CE,09 return text window parameter function SAVE Token = 94 save BASIC program to disk SCALE Token = E9 (currently unimplemented) SCNCLR Token = E8 erase text or graphic display SCRATCH Token = F2 delete disk file SCREEN Token = FE,2E set parameters or open graphic screen SET Token = FE,2D set system parameter, subcommand SGN Token = B4 return sign of number function SIN Token = BF trigonometric sine function SLEEP Token = FE,0B pause BASIC program for time period SLOW Token = FE,26 set system speed to minimum SOUND Token = DA perform sound effects SPC Token = A6 skip spaces in printed output SPRCOLOR Token = FE,08 set multicolor sprite colors SPRDEF Token = FE,1D (currently unimplemented) SPRITE Token = FE,07 set sprite parameters SPRSAV Token = FE,16 set or copy sprite definition SQR Token = BA Square root function STEP Token = A9 for-next step increment STOP Token = 90 halt BASIC program STRS Token = C4 string representation of number function SYS Token = 9E call ML routine TAB Token = A3 tab position in printed output TAN Token = C0 trigonometric tangent function TEMPO Token = FE,05 set tempo (speed) of music play THEN Token = A7 if/then/else clause TO Token = A4 (subcommand) TRAP Token = D7 define BASIC error handler TROFF Token = D9 BASIC trace mode disable TRON Token = D8 BASIC trace mode enable TYPE Token = FE,27 display sequential disk file UNTIL Token = FC do/loop conditional USING Token = FB define print output format USR Token = B7 call user ML function VAL Token = C5 numeric value of a string function VERIFY Token = 95 compare memory to disk file VIEWPORT Token = FE,31 (currently unimplemented) VOL Token = DB set audio volume WAIT Token = 92 pause program pending memory condition WHILE Token = ED do/loop conditional WIDTH Token = FE,1C (currently unimplemented) WINDOW Token = FE,1A set text screen display window XOR Token = CE,08 logical xor function 3.1.3. BASIC 10.0 COMMAND AND FUNCTION DESCRIPTION ABS -- Absolute value function ABS (expression) The ABSolute value function returns the unsigned value of the numeric expression. X = ABS(1) Result is X = 1 X = ABS(-1) Result is X = 0 AND -- Boolean operator expression AND expression The AND operator returns a numeric value equal to the logical AND of two numeric expressions, operating on the binary value of signed 16-bit integers in the range (-32768 to 32767). Numbers outside this range result in an 'ILLEGAL QUANTITY' error. X = 4 AND 12 Result is X=4 X = 8 AND 12 Result is X=8 X = 2 AND 12 Result is X=0 In the case of logical comparisons, the numeric value of a true situation is -1 (equivalent to 65535 or $FFFF hex) and the numeric value of a false situation is zero. X = ("ABC"="ABC") AND ("DEF"="DEF") Result is X=-1 (true) X = ("ABC"="ABC") AND ("DEF"="XYZ") Result is X= 0 (false) APPEND -- Open a disk file and prepare to append data to it APPEND# logical_file_number, "filename" [,Ddrive] [Udevice] Opens filename for writing, and positions the file pointer at the end of the file. Subsequent PRINT# statements to the logical_file_number will cause data to be appended to the end of this file. If the file does not exist, it will be created. APPEND#1, "filename" APPEND#1, (file$), ON U(unit) ASC -- PETSCII value function ASC (string) This function returns the PETSCII numeric value of the first character of a string. The PETSCII value of an empty (null) string is zero. This function is the opposite of the CHR$ function. Refer to the Table of PETSCII Character Codes. X = ASC("ABC") Result is X=65 X = ASC("") Result is X=0 ATN -- Arc tangent function ATN (expression) This function returns the angle whose tangent is the value of the numeric expression, measured in radians. The result is in the range of -PI/2 to PI/2 radians. X = ATN(45) Result is X=1.54050257 To get the arc tangent of an angle measured in degrees, multiply the numeric expression by PI/180. AUTO -- Enable or disable automatic line numbering AUTO [increment] Turns on the automatic line numbering feature which eases the job of entering programs by typing the line numbers for the user. As each program line is entered by pressing the next line number is printed on the screen, with the cursor in position to begin typing that line. The increment parameter refers to the increment between line numbers. AUTO with no increment given turns off auto line numbering. AUTO mode is also turned off automatically when a program is RUN. This statement is executable only in direct mode. AUTO 10 automatically numbers line in increments of ten. AUTO 50 automatically numbers line in increments of fifty. AUTO turns off automatic line numbering. BACKGROUND -- Set the background color of the display BACKGROUND color Sets the screen background color to the given color. The color given must be in the range (0-15). See the Color Table. BACKUP -- Backup an entire disk from one drive to another BACKUP Dsource_drive TO Ddestination_drive [Udevice] This command copies all the files on a diskette to another on a dual drive system only. It cannot backup diskettes using CBM serial bus type drives, for example. If the destination diskette is unformatted, BACKUP will automatically format it. BACKUP copies every sector, so any data already on the destination diskette will be overwritten. To copy specific files from one drive to another, use the COPY command. NOTE: This command can only be used with a dual disk drive, such as the built-in C64DX drive and optional F016-type expansion drive. To backup diskettes using different drives, such as the built-in drive and a 1581-type serial bus drive, use a utility program. BACKUP D0 to D1 Copies all files from the disk in drive 0 to the disk in drive 1. BACKUP D0 TO D1, ON U9 Copies all files from drive 0 to drive 1 in disk drive unit 9. BANK -- Set the memory bank number for PEEK, POKE, SYS, WAIT, LOAD, SAVE BANK memory_bank [*** THIS COMMAND MIGHT CHANGE ***] This command should be used before and BASIC command that has an address parameter. The address parameters are limited to the range (0-65535, $0000-$FFFF hex). The BANK command tells the computer which 64K byte memory bank the location you want is in. The memory_bank parameter is number from 0-255. Refer to the System memory map to see what is in each bank. A BANK number greater than 127 (i.e., has its most significant bit set) means "use the current system configuration", and must be used to access an I/O location. BASIC defaults to BANK 128. For examples, see PEEK, POKE, etc. BEGIN/BEND -- Extend an IF clause over more than one line BEGIN/BEND are used to define a block of code which is considered by the IF statement to be one statement. The normal usage of IF/THEN/ELSE would be along the following lines: IF boolean THEN statement(s) : ELSE statement(s) The main restriction is that the entire body of the IF/THEN/ELSE construct can only occupy one line. BEGIN/BEND allows either the 'THEN' or the 'ELSE' clause to run on for more than one line. IF boolean THEN BEGIN: statements... statements... statements... BEND : ELSE BEGIN statements... statements... BEND Remember, however, that this is only a way to extend the body for more than one line: all other 'IF/THEN' rules apply. For example: 100 IF x=1 THEN BEGIN : a=5 110 : b=6 120 : c=7 130 BEND : print "ah-ha!" In the above example, "ah-ha!" would be printed ONLY if the expression 'x=1' is TRUE, because the print statement is on the same logical line as the THEN clause. It is bad practice to GOTO a line in the middle of a BEGIN-BEND block. If BEGIN or BEND is encountered outside of an active IF statement, it is ignored. BLOAD -- loads a binary disk file into memory BLOAD "filename" [,Bbank] [,Paddress] [Udevice] Used to load a machine language program or other binary data (such as display pictures or sprite data) into memory. If a load address is not given, the load address given in the disk file will be used. If a bank number is not given, the bank given in the last BANK statement will be used. If a load overflows a bank (that is, the load address exceeds 65535 ($FFFF)), an 'OUT OF MEMORY' error is reported. Also see the LOAD command. BLOAD "sprites", P(dec("600")), B0 BOOT -- Load and execute a program BOOT BOOT SYS BOOT filename [,Bbank] [,Paddress] [,Ddrive] [Udevice] BOOT without a filename given causes the computer to look for a BASIC program called AUTOBOOT.C65* on the indicated diskette, LOAD it and RUN it (just like RUN "AUTOBOOT.C65*"). BOOT with a filename given will cause the executable binary file to be BLOADed and executed beginning at the load address. If a load address is not given, the file will be loaded and execution begun at the address stored on disk. BOOT SYS is a special command that copies the "home" sector (the very track and sector) of the C64DX built-in drive into memory at address $400 to $5FF (one physical sector, 512 bytes) and perform a machine language JSR (Jump SubRoutine) to it. It has the same function as turning on your C64DX while holding down the ALT key. It is used to boot an alternate operating system from either a CBM 3.5" diskette or an MSDOS (720K) diskette. If used in a BASIC program, and it fails, the system can be corrupted. BOOT SYS does *not* use the normal DOS to access the disk. BOOT Loads & runs BASIC program called AUTOBOOT.C65* on system disk. BOOT U9 Loads & runs BASIC program called AUTOBOOT.C65* on disk unit 9. BOOT "ml" Load & executes machine language program called ML, starting at address stored on disk. BORDER -- Set the exterior border color of the display BORDER color Sets the screen border color to given color. The color must be in the range (0-15). See the Color Table. BOX -- Draw a 4-sided graphical shape BOX x0,y0, x1,y0, x0,y1, x1,y1 [,solid] Requires two line segments to be specified, the order of which determines the shape drawn. The shape is drawn in the currently specified PEN color, on the currently specified SCREEN. The above command will draw the following shape: |0,<=0 +--------------------+ |1,<=0 | | | | |0,<=1 +--------------------+ |1,<=1 But if the order of the coordinates were given as: BOX x0,y0, x1,y0, x1,y1, x0,y1 a "bowtie" shape would be drawn. See the sample program at SCREEN. BSAVE -- Save an area of memory in binary disk file BSAVE "[@]filename", Pstart_adr TO Pend_adr [,Bbank] [,Ddrive] [Udevice] BSAVE copies an area of memory into a binary disk file called "filename", starting at start_adr and ending at end_adr-1 (i.e. end_adr must be one more than actual last address saved). If a bank number is not given, the bank given in the last BANK statement will be used. end_adr must be greater than start_adr, and area to be saved must be limited to the indicated memory bank. You cannot save data from more than one bank at a time. start_adr is saved on disk as the load address. If filename already exists on the designated diskette, memory is NOT saved and a 'FILE EXISTS' error is reported. Preceding the filename with an '@'-sign will allow you to overwrite an existing file, but see the cautions at DSAVE. BSAVE "sprites", P(dec("600")) TO P(dec("800")), B0 BUMP -- Sprite collision function BUMP (type) This function return a numeric summary of sprite collisions accumulated since the last time the BUMP function was used. You can use the COLLISION command to set up a special routine in your program to receive control whenever a sprite BUMPs into something, but a particular COLLISION does not have to be enabled to use BUMP. See the COLLISION command. To evaluate sprite collisions, where a BIT position (0-7) in the numeric result corresponds to a sprite number (0-7): BIT position: 7 6 5 4 3 2 1 0 | | | | | | | | BUMP value in binary: 0 0 0 0 0 1 0 1 = 5 decimal BUMP(1) returns a value representing sprite-to-sprite collisions. BUMP(2) returns a value representing sprite-to-data collisions. X = BUMP(1) Result is X=3 if sprites 0 & 1 collided, as shown above. (binary 101 = 5 decimal). Note that more than one collision can be recorded, in which case you should evaluate a sprite's position using the RSPPOS function to figure out which sprite collided with what. BUMP is reset to zero after each use. BVERIFY -- Compare a binary disk file to an area of memory BVERIFY "filename" [,Paddress] [,Bbank] [,Ddrive] [Udevice] BVERIFY compares a binary disk file called "filename" to an area of memory. In direct mode, if the areas contain the same data the message "OK" is displayed, and if the data differs the message 'VERIFY ERROR' is displayed. In program mode, an error is generated if a mismatch is found otherwise the program continues normally. The comparison starts with the address given, else it starts at the address stored on disk. The comparison ends when the last byte is read from the disk file. If a bank number is not given, the bank given in the last BANK statement will be used. The ending address is determined by the length of the disk file. The comparison halts on the first mismatch or at the end of the file. The area to be compared must be confined to the indicated memory bank. BVERIFY "sprites", P(dec("600")), B0 CATALOG -- see DIR (DIRECTORY) command CHANGE -- Find text in a BASIC program and change it. CHANGE :string1: TO :string2: [,line_range] CHANGE "string1" TO "string2" [,line_range] This is a direct (edit) mode command. CHANGE looks for all occurrences of string1 in the program, displays each line containing string1 with the target string highlighted, and prompts the user for one of the following: Y Yes, change it and look for more N No, don't change it, but look for more * Yes, change all occurrences from here on Exit command now, don't change anything Any character can be used for the string delimiter, but there are side effects: see comments at FIND command. If the line number range is not given (see LIST for description of range parameter), the entire program is searched. CHAR -- Draw a character string on a graphic screen CHAR column, row, height, width, direction, "string" [,charsetadr] [*** THIS IS SUBJECT TO CHANGE ***] CHAR displays text on a graphic screen at a given location. The character height, width, and direction are programmable. The parameters are defined as: column: Character position: For 320 wide screens, 0-39 For 640 wide screens, 0-79 row: Pixel line: For 200 line screens, 0-199 For 400 line screens, 0-399 height: Multiple of 8-bit character height: 1= 8 pixels high, 2= 16 pixels, etc. width: Multiple of 8-bit character width: 1= 8 pixels high, 2- 16 pixels, etc. direction: Bit mask: B0= up B1= right B2= down B3= left The string can consist of any printable character, as defined by the VIC character set. Non-text characters are ignored. If the address of the character set is not given, the upper/lower ROM character set is used ($29800). CHAR 18,96, 1,1,2, "C65D", DEC("9000") The above example will draw the characters "C65D" in the center of a 320x200 pixel screen using the system's uppercase/graphic character set. CHR$ -- Character string function CHR$ (value) This function returns a string of one character having the PETSCII value specified. This function is the opposite of the ASC function. It's often used in PRINT strings to output data that is not visible, such as control codes and escape sequences. Refer to the Table of PETSCII Character Codes. PRINT CHR$(27)"Q"; CHR$(27) is the escape character. This statement performs the clear-to-end-of-line escape function. CIRCLE -- Draw a circle on a graphic screen CIRCLE x_center, y_center, radius [,solid] The CIRCLE command will draw a circle with the given radius centered at (x_center,y_center) on the current graphic screen. The circle will be filled (i.e., a disc) if SOLID is non-zero. CIRCLE 160,100,50 The above example will draw a circle in the center of a 320x200 pixel screen (160,100) having a radius of 50 pixels. The aspect ratio of the screen may cause it to appear as an ellipse, however. See also the ELLIPSE command. CLOSE -- Close a logical I/O channel CLOSE logical_channel_number This command closes the input/output channel associated with the given logical_channel_number, established by an OPEN statement. In the case of buffered output (such as the serial bus or RS232) any data in the device's buffer will be transmitted before the channel is closed. Refer to specific I/O operations for details. The logical_channel_number is required; to close all channels on a given device, use the DCLOSE command. Note that RUN, NEW, and CLR commands will initialize the logical channel tables but will not actually close any channels. CLR -- Clear program variables CLR This statement initializes BASIC's variable list, setting all numeric variables to zero and string variables to null. It also initializes the DATA pointer, BASIC runtime stack pointer (i.e., clears all GOSUBs, DO/LOOPs, FOR/NEXT loops, etc.), and clears any user functions (DEF FNx). Any OPEN channels are forgotten (but a CLOSE is not performed; don't use if there are any open disk output files). A CLeaR is automatically performed by a RUN or a NEW command. CMD -- Set default output channel CMD logical_channel_number [,string] CMD changes the default output device, normally the screen, to that specified. The logical_channel_number can be any previously OPENed write channel, such as one to a disk file, printer, or RS232. When redirected via CMD, all output which normally would go to the screen (such as PRINT commands, LIST output, DIRECTORY lists, etc.) is sent to another device or file. The redirection is terminated by CLOSE-ing the CMD channel or executing a PRINT# to the CMD channel. Some output devices require a PRINT# to be performed before the CMD channel is closed, such as printers, to cause the device's buffer to be flushed (i.e., displayed). Any system error will redirect output back to the system default, normally the screen, but will not flush nor close the output channel. If the optional string is given, it is output immediately after the CMD device is established. This feature is normally used to set up printers (eg., set printer modes via escape codes) or to identify the output (eg., title printouts). OPEN 4,4 OPENS device #4, which is the printer. CMD 4 All normal output now goes to the printer. LIST The LISTing goes to the printer. PRINT#4 Set output back to the screen. CLOSE 4 Close the printer channel. COLLECT -- Check (validate) disk, delete bad files and free lost sectors COLLECT [Ddrive] [Udevice] Refer to the DOS 'V'alidate command. This command will cause the DOS to recalculate the Block Availability Map (BAM) of the diskette in the indicated drive, allocating only those sectors being used by valid, properly closed files. All other sectors are marked as "free" and improper files are automatically deleted. Note: COLLECT should be used with extreme care, and MUST NOT be used on diskettes with special boot sectors or direct access (eg., random) files. In any case, be sure the diskette has been BACKUP-ed first. COLLISION -- Setup subroutine to handle special events COLLISION type [,linenumber] [*** THIS MIGHT CHANGE ***] COLLISION is used to handle "interrupt" situations in BASIC, such as sprites bumping into things or lightpen triggers. When the specified situation occurs, BASIC will finish processing the currently executing instruction and perform an automatic GOSUB to the linenumber given. When the subroutine terminates (it must end with a RETURN) BASIC will resume processing where it left off. Interrupt handling continues until a COLLISION of the same type but without any linenumber is specified. More than one type interrupt may be enabled at the same time, but only one interrupt can be handled at a time (i.e., no recursion and no nesting of interrupts). The type interrupt can be: 1 = Sprite to sprite collision 2 = Sprite to display data collision 3 = Light pen Note that what caused an interrupt may continue causing interrupts for some time unless the situation is altered or the interrupt is disabled. This is especially true for BASIC, which is slow to respond to interrupts. Use the BUMP and RSPPOS functions to evaluate the results of sprite collisions, and the LPEN function to evaluate the position of a light pen. 10 COLLISION 1,90 20 SPRITE 1,1 : MOVSPR 1,100,100 : MOVSPR 1,0#5 30 SPRITE 2,1 : MOVSPR 2,100,150 : MOVSPR 2,180#5 40 DO : PRINT : LOOP 50 END 90 PRINT"BUMP! ";:RETURN In this example, sprite-to-sprite collisions are enabled (line 10), and two sprites are turned on, positioned, and made to move (lines 20 & 30). One sprite moves up and the other moves down while the program does nothing other than print blank lines to the screen (line 40). When the sprite collide, the subroutine at line 90 is called, it prints "BUMP!", and the computer goes back to printing blank lines. COLOR -- Enable or disable screen color (character attribute) control COLOR COLOR turns on or turns off the screen editor's attribute handler. When colors are turned off, whatever character attributes are being currently displayed (text color, underline, flash, etc.) are "stuck". The main purpose for doing this is to speed up screen handling (writing to the screen or scrolling the screen) about two times, since the screen editor no longer has to manipulate the attributes. Note that only FOREGROUND colors (and special VIC attributes) are affected. To change screen colors, use the following commands: FOREGROUND color# Set Foreground color (text) HIGHLIGHT color# Set Highlight color (text) BACKGROUND color# Set VIC background color BORDER color# Set VIC border color CONCAT -- Concatenate (merge) two sequential disk files CONCAT "file1"[,Ddrive1] TO "file2"[,Ddrive2] [Udevice] CONCAT merges two SEQuential files, appending the contents of "file1" to "file2". Upon completion, "file2" contains the data of both files, and "file1" is unchanged. Both files must exist on drives of the the same unit, and pattern matching is not allowed. Some disk drives handle CONCAT differently; refer to the DOS manual for specific details. CONT -- Continue program execution CONT CONTinue is used to re-start a BASIC program that was halted by a STOP or END statement, or interrupted by the key. The program will resume at the statement following the STOP or END instruction, or at the statement after the one that was interrupted by the key. CONT is typically used during program debugging. You can look at and alter variables while the program is halted. Programs halted as a result of an untrapped error condition cannot be CONTinued. Programs that have been edited in any way cannot be restarted. Any error condition that occurs since the program was halted will prevent it from being restarted. Programs that cannot be restarted via CONT can be restarted with a GOTO, as long as you don't need to resume execution in the middle of a line of commands and you recall where the halt occurred. Note that the key can interrupt some commands in mid-execution, such as file I/O, drawing commands, etc. In such cases, programs may not run correctly after a CONTinue. COPY -- Copy disk files COPY ["file1"][,Dd1] TO ["file2"][,Dd2] [Udevice] COPYs a disk file to another disk file. On single drive units, the filenames must be different. On dual drive units, copying can be done between two drives on the same unit, and the filenames can be the same or different. Pattern matching can be used. Copying files from one unit to a different unit cannot be done: use a copy utility program in such cases. Only legal type files can be copied; direct access data, boot sectors, and partitions cannot be copied. Refer to the DOS manual for your disk drive specific details. COPY "file1" TO (F2$) Copies "file1" to another file whose name is in F2$ on the same drive. Names must differ. COPY "file1",D0 TO D1,U9 Copies "file1" from unit 9 drive-0 to unit 9 drive-1. COPY D0 TO D1 Copies all files from drive-0 to drive-1 on the same unit. COPY "???.src",D0 TO "*",D1 Copies all files on drive-0 matching the pattern to a file of the same name on drive-1. COS -- Cosine function COS (expression) This function returns the cosine of X, where X is an angle measured in radians. The result is in the range -1 to 1. X = COS (pi) Result is X=-1 To get the cosine of an angle measured in degrees, multiply the numeric expression by pi/180. CUT -- Cut a graphic area into a temporary structure CUT x,y,dx,dy [*** NOT YET IMPLEMENTED ***] DATA -- Define program constant data to be accessed by READ command DATA [list of constants] DATA statements store lists of data that will be accessed during program execution by a READ statement. The DATA statement can appear anywhere in the program, and it is never executed. BASIC keeps a pointer to the earliest un-READ DATA statement, and data is read sequentially from first item in a DATA statement to the last item, from the earliest DATA statement in the program to the last DATA statement in the program. The list of constants can contain both numeric data (integer or floating point) and string data, but cannot contain expressions which must be evaluated (such as 1+2, DEC("1234"), or CHR$(13)). Items are separated by commas. String data need not be enclosed in quotes unless it contains certain characters, such as spaces, commas, colons, graphic characters, or control codes. If two commands have nothing between them, the data will be READ as 0 if numeric or a null string. The RESTORE command allows you to position BASIC's data pointer to a specific line number. If the program tries to read more DATA than exists in the program, an 'OUT OF DATA' error results. If a READ statement's variable type does not agree with the DATA being read, a 'TYPE MISMATCH' error results. DATA 100, 200, FRED, "HELLO, MOM", , 3.14, ABC123, -1.7E-9 DCLEAR -- Clear all open channels on disk drive DCLEAR [Ddrive] [Udevice] DCLEAR sends the indicated disk drive an 'I'nitialize command. This clears all open channels, closes all open files, and causes the DOS to re-read the diskette's Block Allocation Map (BAM). Note that DCLEAR DOES NOT close open channels on the computer's side (see the DCLOSE command). There are some other side affects caused by this command with different types of drives -- refer the DOS manual for your disk drive for specific details. DCLOSE -- Close a disk file, or close all channels on a device DCLOSE [#logical_file_number] [Udevice] DCLOSE is intended to close a file opened with the DOPEN command. Specific files can be closed by specifying a logical_file_number, or all files on a particular drive can be closed by not specifying a particular logical_file_number. It is possible to close channels on non-disk devices with this command by specifying only the device number. DCLOSE#1 Closes the file associated with logical logical file number 1. DCLOSE Closes all files currently open on the default system drive. DCLOSE U(U2) Closes all channels open to device U2. DEC -- Decimal value function DEC (hex_string) This function return the decimal value of a string representing a hexadecimal number in the range "0000" to "FFFF". The result is in the range 0-65535. If the string contains a non-hexadecimal digit or is more than four (4) characters in length an 'ILLEGAL QUANTITY' error is reported. VIC = DEC("D000") Result is VIC=53248, the address of the VIC chip DEF FN -- Define function DEF FN name(numeric_variable) = numeric_expression Define a user-written numeric function. The DEF FNx statement must be executed before the function can be used. Once a function has been defined, it can be used like any other numeric variable. The function name is the letters FN followed by any legal floating point (non-integer) variable name. A function can be defined only in a program. The numeric_variable is a "dummy" variable. It names the variable the numeric_expression which will be replaced when the function is used. It's not required to be used in the numeric_expression, and its value won't be changed by the function call. The numeric_expression performs the calculations of the function. It is any legal numeric expression that fits on one line. Variables used in the expression have their value at the time the function is used. Functions can be used only by the program which defines them. If one program chains to another program, the first program's functions cannot be used (usually a 'SYNTAX ERROR' results). Similarly, if the program is moved in any way after the function is defined, the function cannot be used. 10 DEF FN R(MAX) = INT(RND(0)*MAX)+1 20 INPUT "MAXIMUM"; MAX 30 PRINT FN R(MAX) In this example, we've defined a function which will return a pseudo random number between 1 and whatever MAX is. Instead of using the expression INT(RND(0)*MAX)+1 every time a random number is needed, we can now use FN R(MAX). When we use FN R(x), the value of 'x' will be substituted everywhere MAX is used in the function definition. 10 DEF FN I(X) = X+1 20 DEF FN L(Z) = LEN(A$) 30 DEF FN AVG(N) = (TOT*CNT+N)/(CNT+1) DELETE -- Delete lines of BASIC program, or Delete disk files DELETE [startline] [-[endline]] DELETE "filespec" [,Ddrive] [Udevice] [,R] There are two forms of DELETE. The first form is used in direct mode to remove lines from a BASIC program: DELETE 75 Deletes line 75 DELETE 10-50 Deletes line 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. The second form is used in program or direct mode to delete a disk file. See the SCRATCH command. DELETE "myfile" Deletes the file MYFILE on the system drive. DIM -- Declare array dimensions DIM variable(subscripts) [,variable(subscripts)]... Before arrays of variables can be used, the program must first execute a DIM statement to establish DIMensions of that array (unless there are 11 or fewer elements in the array). The statement DIM is followed by the name of the array, which may be any legal variable name. Then, enclosed in parentheses, put 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 that 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. To figure the number of variables created with each DIM, multiply the total number of elements in each dimension of the array. Note: each array starts with element 0, and integer arrays take up 2/5ths of the space of floating point arrays. More than one array can be dimensioned in a DIM statement by separating the arrays by commas. If the program executes a DIM statement for any array more than once, the message 'REDIM'D ARRAY' is reported. It is good programming practice to place DIM statements near the beginning of the program. 10 DIM A$(40),B7(15),CC%(4,4,4) | | | 41 elements 16 elements 125 elements DIRECTORY -- List the files of a diskette DIR DIRECTORY ["filespec"] [,R] [,Ddrive] [Udevice] A directory is a list of the names of the files that are on a diskette. The directory listing consists of the name of the diskette, the names, sizes, and filetypes of all the files on a diskette, and the remaining free space on the diskette. The filespec is used to specify a pattern match string to view selected files. Not all disk drives support the same options or filespecs; refer to your DOS manual for details. The C64DX allows you to print DIR listings without having to 'load' the directory; see example below. The commands DIR, DIRECTORY, and CATALOG have the exact same function. They can be used in direct or program mode. DIRECTORY List all files on the diskette in the default system drive DIR "*.src", U9 Lists the all the files ending with ".src" on unit 9. DIR "*,=p",R List all the deleted but recoverable PRG-type files on the system drive. OPEN 4,4:CMD 4:DIR:CLOSE 4 Print DIR listing to printer unit 4. The following program can be used to load the directory into variables for use within a program. In this case, the filename is simply printed to the screen: 10 OPEN 1,8,0,"$0:*,P,R" open dir as a file 20 : IF DS THEN PRINT DS$: GOTO 100 abort if error 30 GET#1,X$,X$ trash load address 40 DO read each line 50 : GET#1,X$,X$: IF ST THEN EXIT trash links, check EOF 60 : GET#1,BL$,BH$ get file size 70 : LINE INPUT#1, F$ get filename & type 80 : PRINT LEFT$(F$,18) print filename 90 LOOP loop until EOF 100 CLOSE 1 close dir DISK -- Send a disk command DISK "command_string" [Udevice] The DISK command is used to send special commands to the DOS via the disk drive's command channel. The DISK command is analogous to the following BASIC code: OPEN 1,n,15: PRINT#1,"command_string": CLOSE 1 Not all disk drives understand the same commands. Refer to your DOS manual for commands and command syntax for your drive. Note that the drive number, if any, must be included in the command_string. DISK "U0>10" Renumber system drive to 10. DISR "U0>V"+chr$[0) Turn off write verify DISK "S0:file",U(n) Scratch "file" on unit n DLOAD -- Load a BASIC program file from disk DLOAD "filename" [,Ddrive] [Udevice] This command copies a BASIC program from disk into the BASIC program area of the computer. It can then be edited, DSAVEd, or RUN. Used in program mode, it overlays the current program in memory and begin execution automatically at the first line of the new program. Variable definitions will be left intact, but any open data files and the disk command channel will be automatically closed. This is called CHAINING. See also RUN. Use BLOAD to load binary or machine language data. DLOAD "myprogram" Searches the default system disk drive for the BASIC program "myprogram", loads it, and relinks it. DLOAD (F$),U9 LOADs a program whose name is in F$ from disk unit 9. DMA -- Perform a DMA operation DMA command [,length,source(l/h/b),dest(l/h/b),subcmd,mod(l/h) [,...]] [*** THIS COMMAND IS SUBJECT TO CHANGE ***] The DMA command defines and executes a Direct Memory Access operation. The parameters are used to construct a DMA list, which is then passed to the DMA processor for execution. Refer to the DMA chip specification for details. Chained DMA commands are not allowed, but multiple DMA commands can be given and the DMA handler will set up and execute each one, one at a time. Refer to the system memory map to find out where things are. Because this command directly accesses system memory, extreme care should be taken in its use. Changing the wrong memory locations can crash the computer (press the reset button to reboot). DMA 3, 2000, ASC("+"), 0, DEC("800"), 0 Fill screen with '+' DMA 0, 2000, DEC("800"), 0, DEC("8000"), 1 Copy screen to $18000 DMODE -- Set graphic display mode DMODE jam, comp, inverse, stencil, style, thickness [*** THIS COMMAND IS SUBJECT TO CHANGE ***] jam 0-1 complement 0-1 inverse 0-1 stencil 0-1 style 0-3 thickness 1-8 DO/LOOP/WHILE/UNTIL/EXIT -- Program loop definition and control DO [UNTIL boolean_expression | WHILE boolean_expression] . . statements [EXIT] . LOOP [UNTIL boolean_expression | WHILE boolean_expression] Performs the statements between the DO statement and the LOOP statement. If no UNTIL or WHILE modifies either the DO or the LOOP statement, execution of the intervening statements continues indefinitely. If an EXIT statement is encountered in the body of a DO loop, execution is transferred to the first statement following the nearest LOOP statement. Do loops may be nested, following the rules defined for FOR-NEXT loops. If the UNTIL parameter is used the program continues looping until the boolean argument is satisfied (becomes true). The WHILE parameter is basically the opposite of the UNTIL parameter: the program continues looping as long as the boolean argument is TRUE. An example of a boolean argument is A=1, or G>65. DO UNTIL X=0 or X=1 This loop will continue : statements until X=0 or X=1. If LOOP X=0 or 1 at beginning the loop won't execute. 10 A$="": DO GETKEY A$: LOOP UNTIL A$="Q" This will loop until the user types 'Q' 10 DOPEN#1,"FILE" This program will 20 C=0 count the number of 30 DO: LINEINPUT#1,A$: C=C+1: LOOP UNTIL ST lines in FILE 40 DCLOSE#1 50 PRINT"FILE CONTAINS";C;" LINES." DOPEN -- Open a disk file DOPEN#lf,"filename[,]"[,L[reclen]] [,W] [,Ddrive] [Udevice] This command OPENs a file on disk for reading or writing. If is the logical file number, which you will use in PRINT#, INPUT#, GET#, RECORD#, and DCLOSE# commands to reference the channel to your file. The filename is required. The defaults are to OPEN a SEQuential file for Reading, in which case the file must exist or a 'FILE NOT FOUND' error results. To create an file and write to it, use the 'W'rite option. 'FILE EXISTS' error is report if an output file already exists. To read or write a RELative file, use the 'L'ength option. The 'reclen' record length is required only when creating a relative file. For more information regarding Relative files, see the RECORD command and refer to your DOS manual. See also APPEND. See the OPEN command for a discussion about channel and device numbers. DOPEN#1,"readfile" Opens sequential READFILE for reading. DOPEN#1,"writefile",W Creates & opens seq WRITEFILE for writing. DOPEN#1,"file,P",U(u) Opens a PRoGram type file for reading on unit U DOPEN#1,(rf$),L Open existing relative file whose name's in RF$ DOPEN#a,"rel",L80 Create a relative file with record length of 80 DPAT -- Set graphic draw pattern DPAT type [, # bytes, byte1, byte2, byte3, byte4] [*** THIS COMMAND IS SUBJECT TO CHANGE ***] type 0-63 # bytes 1-4 byte1 0-255 byte2 0-255 byte3 0-255 byte4 0-255 DSAVE -- Save a BASIC program into a disk file DSAVE "[@]filename" [,Ddrive] [Udevice] This command copies a BASIC program in the computer's BASIC memory area into a PRoGram-type disk file. If the file already exists, the program is NOT stored and the error message 'FILE EXISTS' is reported. If the filename is preceded with an '@', then if the file exists it will be replaced by the program in memory. Because of some problems with the 'save-with-replace' option on older disk drives, using this option is not recommended if you do not know what disk drive is being used. Use the DVERIFY to compare the program in memory with a program on disk. To save a binary program, use the BSAVE command. DSAVE "myprogram" Creates the PRG-type file MYPROGRAM on the default system disk and copies the BASIC program in memory into it. DSAVE "@myprogram" Replaces the PRG-type file MYPROGRAM with a new version of MYPROGRAM. If MYPROGRAM doesn't exist, it's created. DSAVE (F$),U9 Saves a program whose name is in F$ on disk unit 9. DVERIFY -- Compare a program in memory with one on disk DVERIFY "filename" [,Ddrive] [Udevice] This command is just like a DLOAD, but instead of LOADing the BASIC program file into computer memory the data is read from disk and compared to computer memory. If there's any difference at all a 'VERIFY ERROR' is reported. Note: If the BASIC program in memory is not located at the same address as the version on disk was SAVEd from, the files will not match even if the program is otherwise identical. The comparison ends when the last byte is read from the disk file. Use the BVERIFY command to compare memory with binary files. DVERIFY "myprogram" Good: SEARCHING FOR 0:myprogram Bad: SEARCHING FOR 0:myprogram VERIFYING VERIFYING OK ?VERIFY ERROR ELLIPSE -- Draw an ellipse on a graphic screen ELLIPSE x_center, y_center, x_radius, y_radius [,solid] The ELLIPSE command will draw an ellipse with the given radii centered at (x_center,y_center) on the current graphic screen. The ellipse will be filled (i.e., a disc) if SOLID is non-zero. ELLIPSE 160,100,65,50 The above example will draw an ellipse in the center of a 320x200 pixel screen (160,100) having radii of (65,50) pixels. The aspect ratio of the screen may cause it to appear as an circle, however. See also the CIRCLE command. ELSE -- See IF/THEN/ELSE END -- Define the end of program execution END The END statement terminates program execution. It does not close channels or files, and it does not clear any variables or reset any pointers. An END statement does not need to be put at the last line of a program. The CONTinue command can be used to resume execution with the next statement following the END statement. See also the STOP command. ENVELOPE -- Define musical instrument envelopes ENVELOPE n, [,[atk] [,[dec] [,[sus] [,[rel] [,[wf] [,pw] ]]]]] n............... Envelope number (0-9) atk ............ Attack rate (0-15) dec ............ Decay rate (0-15) sus ............ Sustain rate (0-15) rel ............ Release rate (0-15) wf ............. Waveform: 0 = triangle 1 = sawtooth 2 = pulse (square) 3 = noise 4 = ring modulation pw ............. Pulse width (0-4095) [*** THIS COMMAND IS SUBJECT TO CHANGE ***] A parameter that is not specified will retain its current value. Pulse width applies to pulse waves (wf=2) only and is determined by the formula (pwout = pw/40.95 %), so that pw = 2048 produces a square wave and values of 0 or 4095 produce constant DC output. The C64DX initializes the ten (10) tune envelopes to: 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 harpsichord 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 ERASE -- Delete disk files ERASE "filespec" [,Ddrive] [Udevice] [,R] This command is identical to DELETE and SCRATCH. See the SCRATCH command for details. ERASE "myfile" Deletes the file MYFILE on the system drive. ERR$ -- Error message function ERR$ (error_number) This function returns a string which is the BASIC error message corresponding to the given error_message. If the given number is too small (less than 1) or too large (greater than 41) an 'ILLEGAL QUANTITY' error is reported. This function is usually used to display a BASIC error condition in a TRAP routine, using the BASIC error word ER as the error_number. Note that when ER=-1, no BASIC error has occurred and ERR$(-1) results in an 'ILLEGAL QUANTITY' error. See the example at TRAP. EXIT -- See DO/LOOP/WHILE/UNTIL/EXIT EXP -- Function to return e^x EXP (number) This function returns the numeric value of e (2.71828183), the base of natural logarithms) raised to the power of given number. If the number is greater than 88.0296919 an 'OVERFLOW' error is reported. X = EXP(4) Result is X=54.5981501 FAST -- Set system speed to 3.58MHz FAST is the default state of the system. FAST is used to restore this state following direct access of "slow" I/O devices such as the SID sound chips. FETCH -- (see the DMA command) FILTER -- Define sound filter parameters FILTER [freq] [,[lp] [,[bp] [,[hp] [,res] ]]] 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) [*** THIS COMMAND IS SUBJECT TO CHANGE ***] Unspecified parameters result in no change to the current value. The filter output modes are additive. For example, how low pass and high pass filters can be selected to produce a notch (or band reject) filter response. For the filter to have an audible effect at least one filter output mode must be selected and at least one voice must be routed through the filter. FIND -- Find text in a BASIC program. FIND :string: [,line_range] FIND "string" [,line_range] This is a direct (edit) mode command. FIND looks for all occurrences of string in the program and displays each line containing string, with string highlighted. Use the key to slow the display, or the key to pause the display. Press to cancel. Any character can be used for the string delimiter, but there are side effects. Using a non-quote delimiter will cause the string to be tokenized, and FIND will find only tokenized strings in the program that match. Using a quote character as the delimiter will cause the string to be interpreted as plain PETSCII, and any matches found will therefore be plain PETSCII. Searching for some tokens such as DATA statements may require the use of colons as delimiters due to the special affect these commands have upon the interpreter. If the line number range is not given (see LIST for description of range parameter), the entire program is searched. FN xx -- User defined function FN xx (expression) The result of this numeric function is determined by the BASIC program in a DEF FN statement. See the example at DEF FN. FOR/TO/STEP/NEXT -- Program loop definition and control FOR index = start TO end [STEP increment] | NEXT index [,index] This command group performs a series of instructions a given number of times. The loop index is a floating point (non-integer) variable which will initially be set to the start value and be incremented by the STEP increment when the NEXT statement is encountered. The loop continues until the index exceeds the end value at the NEXT statement. The start, end, and increment values can be numeric variables or expressions. If the STEP increment is not specified, it is assumed to be one (1). The STEP increment can be any value, positive, negative, or non-integer. If the STEP increment is negative, the loop continues until the index is less than the end value at the NEXT statement. Note that, regardless of the start, end, or increment values, the loop will always execute at least once. The index can be modified within the loop, but it is bad practice to do so. It is also bad practice to GOTO a line inside a loop structure, or to similarly jump out of a loop structure (which can cause an 'OUT OF MEMORY' error). Loops may be nested. If too many are nested, an 'OUT OF MEMORY' error is reported (depends upon stack size, room for about 28 nested loops). The index variable can be omitted from the NEXT statement, in which case the NEXT will apply to the most recent FOR statement. If a NEXT statement is encountered and there is no preceding FOR statement, the error 'NEXT WITHOUT FOR' is reported. 10 FOR L = 1 TO 10 20 PRINT L 30 NEXT L 40 PRINT "I'M DONE! L = "L This program prints the numbers from one to ten, followed by the message I'M DONE! L = 11. 10 FOR L = 1 TO 100 20 FOR A = 5 TO 11 STEP .5 30 NEXT A 40 NEXT L This program illustrates a nested loop. FOREGROUND -- Set the text color of the display FOREGROUND color Sets the text color to the given color index. Color must be in the range (0-15). See the Color Table. COLOR must be ON (see the COLOR command). FRE -- Free byte function FRE (x) This function returns the number of available ("free") bytes in a specified area. PRINT FRE(0) Shows the amount of memory left in the program area, C64DX bank 0 X = FRE(1) X= the amount of available memory in variable area C64DX bank 1. This causes a "garbage collect" to occur, a process which compacts the string area. X = FRE(2) X= the number of expansion RAM banks present. GCOPY -- Copy a graphic area [*** NOT YET IMPLEMENTED ***] GENLOCK -- Enable or disable video sync mode & colors GENLOCK ON [,color#]... GENLOCK OFF [,color#,R,G,B]... To enable video sync mode and specify which colors are affected, use the GENLOCK ON command, and list the palette color indices (0-255) which will display external video. To disable video sync mode and restore the associated palette colors use the GENLOCK OFF command, and list the color index and its RGB values to restore them (see the SET PALETTE command for details). Also see the PALETTE RESTORE command. GET -- Get input data from the keyboard GET variable_list The GET statement is a way to get data from the keyboard one character at a time. When the GET is executed, the character that was typed is received. If no character was typed, then a null (empty) character is returned, and the program continues without waiting for a key. There is no need to hit the key, and in fact the key can be received with a GET. The word GET is followed by a variable name, usually a string variable. If a numeric were used and any key other than a number was hit, the program would stop with an error message. The GET statement may also be put into a loop, checking for an empty result, that waits for a key to be struck to continue. The GETKEY statement could also be used in this case. This statement can only be executed within a program. 10 DO: GET A$: LOOP UNTIL A$ ="A" This line waits for the A key to be pressed to continue. GETKEY -- Get input character from keyboard (wait for key) GETKEY variable_list The GETKEY statement is very similar to the GET statement. Unlike the GET statement, GETKEY waits for the user to type a character on the keyboard. This lets it be used easily to wait for a single character to be typed. This statement can only be executed within a program. 10 GETKEY A$ This line waits for a key to be struck. Typing any key will continue the program. GET# -- Get input data from a channel (file) GET# logical_channel_number, variable_list Used with a previously OPENed device or file to input one character at a time. Otherwise, it works like the GET statement. This statement can only executed within a program. 10 GET#1,A$ GO64 -- Exit C64DX mode and switch to C64 mode GO64 This statement switches from C64DX mode to C64 mode. The question 'ARE YOU SURE?' (in direct mode only) is posted for the user to respond to. If Y and return is typed then the currently loaded program is lost and control is given to C64 mode. This statement can be used in direct mode or within a program. GOSUB -- Call a BASIC subroutine GOSUB line This statement is like the GOTO statement, except that the computer remembers from where it came. When a line with a RETURN statement is encountered, the program jumps back to the statement immediately following the GOSUB. The target of a GOSUB statement is called a subroutine. A subroutine is useful if there is a section of the program that can be used by several different parts of the program. Instead of duplicating the section over and over, it can be set up as a subroutine and called with a GOSUB statement from different parts of the program. This also make the main part of your program much more readable. See also the RETURN statement. Variables are shared with the main program and all subroutines. You can pass information to, and get information back from, subroutines by using variables as messengers. GOSUB statements can be nested. That is, one subroutine can call another subroutine, and the computer automatically keeps track of all the calls. It's important not to jump into or out of subroutines since this can confuse the computer. If too many GOSUBs are nested (usually cause by jumping out of them) an 'OUT OF MEMORY' error is reported because the computer ran out of room to keep track of all the calls. 10 DIR : GOSUB 100 show directory, check status 20 GOSUB 200 print gap 30 LIST "PROGRAM": GOSUB 100 show listing, check status 40 GOSUB 200 print gap 50 etc... 90 END 99 : 100 REM SUBROUTINE TO CHECK DISK STATUS 110 IF DS THEN GOSUB 200: PRINT "DISK ERROR: ";DS$ 120 RETURN 199 : 200 REM SUBROUTINE TO PRINT A SPACER ON THE SCREEN 210 PRINT 220 FOR I=1 TO 39: PRINT"-";: NEXT 230 PRINT 240 RETURN GOTO -- Transfer program execution to specified line number GOTO line_number GO TO line_number After a GOTO statement is executed, the next line to be executed will be the one with the line number following the word GOTO. When used in direct mode, GOTO line number allows starting of execution of the program at the given line number without clearing the variables. 10 PRINT"COMMODORE" 20 GOTO 10 The GOTO in line 20 makes line 10 repeat continuously until STOP is pressed. GRAPHIC -- select graphic mode GRAPHIC CLR GRAPHIC command# [,args] Basically this is a modified C64-type SYS command, minus the address. In the C64DX system, this will represent the ML interface, not the BASIC 10.0 interface which is implemented in the development system. [*** THIS COMMAND IS SUBJECT TO CHANGE ***] GRAPHIC CLR initializes (warm-starts) the BASIC graphic system. It clears any existing graphic modes, screens, etc. and allows a program to commence graphic operations from scratch. HEADER -- Format a diskette HEADER "diskname" [,Iid] [,Ddrive] [Udevice] The HEADER command prepares a new diskette for use, sometimes called FORMATting a diskette. There are two types of "newing" a diskette -- a long form and a quick (or short) form. You must use the long form when preparing a new diskette for its first use. Thereafter you can use the quick form. WARNING: Formatting a diskette (long or short) will destroy all existing data on the diskette! In direct mode, you are asked to confirm what you are doing with 'ARE YOU SURE?'. Type 'Y' and press return to proceed, or TYPE ANY OTHER CHARACTER AND PRESS RETURN TO CANCEL the command. In program mode there is no confirmation prompt. The long HEADER form requires a diskname and an ID. The diskette will be completely (re)sectored, zeros written to all blocks, and a new system track (directory, BAM, etc.) will be created. HEADER "newdisk",I01 prepares a new diskette The short HEADER form is performed when the ID option is omitted. The diskette is assumed to have been previously formatted, and only a new system track (directory, BAM, etc.) is installed. This is roughly equivalent to deleteing all the files, but much quicker. HEADER "makelikenew" re-news an working diskette The diskname is limited to 16 characters and the ID string to two characters. The same rules apply for the diskname as for a filename. Some Disk Systems use the ID string to tell if you have swapped a diskette in a drive, so it's recommended that the ID string be unique for each of your diskettes. Some more examples: HEADER "QUICK" HEADER "MYDISK", I23 HEADER "RECS", I"FB", U9 HEADER (FILES), I(ID$), U(UNIT) HELP -- Show the BASIC line that cause the last error HELP The HELP command is used after an error has been reported in a program. When HELP is typed, the line where the error occurred listed, with the portion containing the error highlighted. Print ERR$(ER) for the error message, and print EN or EL for the error number and error line, respectively. HELP can be used in direct mode or in program mode. Note that, in the case of many I/O errors, there is no associated BASIC error. Check ST or DS$ errors in these cases. HEX$ -- Hexadecimal value function HEX$ (decimal_expression) This function returns a 4-character string that represents the hexadecimal value of the numeric decimal expression. The expression must be in the range (0-65535, $0000-$FFFF hex) or an 'ILLEGAL QUANTITY' error is reported. PRINT HEX$(10) The string "000A" is printed. PRINT RIGHT$(HEX$(10),2) The string "0A" is printed. HIGHLIGHT -- Set the text highlight color of the display HIGHLIGHT color Sets the highlight color to the given color index. The color value must be in the range (0-15). See the Color Table. COLOR must be ON (see the COLOR command). The highlight color is used in HELP messages and FIND/CHANGE strings. IF/THEN/GOTO/ELSE -- Conditional program execution IF expression [:ELSE else_clause] IF...THEN lets the computer analyze a BASIC expression preceded by IF and take one of two possible courses of action. If the expression is true, the statement following THEN is executed. This expression can be any BASIC statement. If the expression is false, the program goes directly to the next line, unless an ELSE clause is present. The ELSE clause, if present, must be in the same line as the IF-THEN part. When an ELSE clause is present, it is executed when the THEN clause isn't executed. In other words, the ELSE clause executes when the expression is FALSE. See BEGIN/BEND to spread the IF statement out over several lines. An ELSE statement is matched to the closest THEN statement in the case of nested IF/THEN statements. The expression being evaluated may be a variable or formula, in which case it is considered true if nonzero, and false if zero. Usually expressions involve relational operators =, <, >, <=, >=, <>. 50 IF X>0 THEN PRINT "X>0": ELSE PRINT "X<=0" If X is greater than 0, the THEN clause is executed, and the ELSE clause isn't. If X is less than or equal to 0, the ELSE clause is executed and the THEN clause isn't. INPUT -- Get input from the keyboard [LINE] INPUT ["prompt"<,l;>] variable_list The INPUT statement pauses the BASIC program, prints the prompt string if present, prints a question mark and a space, and waits for data to be typed by the user, terminated by a return character. If the prompt string ends with a comma instead of a semicolon, a question mark and space is not printed. Input is gathered and assigned to variables in the variable_list. The type of variable must match the type of input typed or a 'TYPE MISMATCH' error is reported. Separate data items typed by the user must be separated with commas. String data with imbedded spaces or commas must be surrounded with quotes. If insufficent data to satisfy the variable-list is typed, two question marks are displayed by the computer to prompt for additional data to be input. If the computer does not understand the input (such as the user typing cursor up or down keys) the computer responds with the message 'REDO FROM START?' and waits for acceptable data to be entered. Input is limited to 160 characters (two screen lines in 80-column mode), which is the size of the input buffer. The INPUT statement can only be executed from within a program. LINE INPUT allows the program to input a string which includes any PETSCII character (including colons, commas, imbedded spaces, etc.) up to but not including a null or return character. There should be only one string-type variable name in the variable_list in this case, but if there are more the computer prompts as usual with two question marks for more data to assign to the additional variables. 10 INPUT "WHAT'S YOUR FIRST NAME AND AGE"; NA$,A 20 PRINT "YOUR NAME IS ";NAS;" AND YOU ARE";A;" YEARS OLD" The above INPUT is the traditional BASIC form. 10 LINE INPUT "WHAT'S YOUR ADDRESS"; AD$ 20 PRINT "YOUR ADDRESS IS: ";AD$ The above INPUT allows an entire line of data to be assigned to a string variable, including commas and other common punctuation marks. 10 INPUT "ENTER YOUR NAME HERE: ", NA$ The above INPUT suppresses the traditional '? ' prompt by using a comma instead of a semicolon after the prompt string. To suppress the '?' without a prompt string, make the prompt string null. INPUT# -- Input data from an I/O channel (file) [LINE] INPUT#logical_channel_number, variable_list The INPUT# command works like the INPUT command, except no prompt string is allowed and input is gathered from a previously OPENed channel or file. This command can only be used in a program. The logical channel number is the number assigned to the device (file) in an OPEN (or DOPEN) statement. Items in the variable list must agree with the type of data input, or a 'FILE DATA ERROR' will resuit. On the C64DX, an End Of File (EOF) condition or bad I/O status will terminate input, as if a return character was received. It's good practice to examine the I/O status byte (and the DS disk status for file I/O) after every I/O instruction to check for problems or errors. 10 DOPEN#1, "FILE" This program will 20 C=0 count the number of 30 DO: LINE INPUT#1,AS: C=C+1: LOOP UNTIL ST lines in FILE 40 DCLOSE#1 50 PRINT"FILE CONTAINS";C;" LINES." INSTR -- Get the location of one string inside another string INSTR (string_1, string_2 [,starting_position]) This function searches for the first occurrence of string_2 in string_1 and returns its location. A value of zero (0) is returned if no match is found, if either string is null (empty), or if string_2 is longer than string_1. If the starting position is given, the search begins at that location, otherwise the search begins at the first character of string_1. The strings can be literals, variables, or string expressions. X = INSTR("123456","4") Result is X= 0 X = INSTR("123456","X") Result is X= -1 X = INSTR("123123","2") Result is X= 123 X = INSTR("123123","2",3) Result is X=-124 INT -- Greatest integer function INT (expression) This function returns the greatest integer less than or equal to the numeric expression. JOY -- Joystick function JOY (port) This function returns the state of a joystick controller in the specified port. When port=l returns position of joystick 1 When port=2 returns position of joystick 2 The value returned is encoded as follows: Fire = 128 + 1 8 2 7 0 3 6 4 5 A value of zero (0) means that the joystick is not being manipulated. A value of 128 or more means that the fire button is being pressed. The possible vales returned are: 0 No activity 128 fire 1 up 129 fire + up 2 up + right 130 fire + up + right 3 right 131 fire + right 4 right + down 132 fire + right + down 5 down 133 fire + down 6 down + left 134 fire + down + left 7 left 135 fire + left 8 left + up 136 fire + left + up KEY -- Enable, disable, display, or define function keys KEY ON KEY OFF KEY [key#, string] There are 14 function keys available on the C64DX (seven unshifted and seven shifted). The user can assign a string consisting of BASIC commands, control codes, escape functions, or a combination of each to function key. The data assigned to a key is typed out when that key is pressed, just as if the characters were typed one by one on the keyboard. The user can enable ("turn on") or disable ("turn off") the function keys. When they are disabled, pressing a function key return that key's normal character code instead of the string assigned to it. This includes the HELP and (shifted) RUN keys. It is also possible to redefine the HELP and (shifted) RUN keys, as function keys 15 and 16, respectively. The system has default assignments for all function keys. KEY with no parameters displays a listing of the current assignments for all the function keys. The maximum length for all the definitions together is 240 characters. If an assignment would be too big to fit, an 'OUT OF MEMORY' error is reported and the assignment is not made. KEY 2, "DIR U9"+CHR$(13) This causes the computer to display the directory from disk unit #9 when function key 2 is pressed. This is equivalent to typing 'DIR U9' and pressing the key directly. The CHR$(13) is the character for . Other often used control codes are CHR$(141) for 'shifted RETURN', CHR$(27) for 'ESCape', and CHR$(34) to incorporate a double quote into a KEY string. KEY 2, "DIR"+CHR$(34)+"*=P"+CHR$(34)+CHR$(13) This is equivalent to typing DIR"*=P" and pressing at the keyboard. Note the way quotes can be incorporated into an assignment. When function key 2 is pressed, a directory of all program files on the default system disk will be displayed. KEY OFF This turns off function key strings. Pressing a function key now would return the character codes associated with F-keys as on the VIC-20 and C64 computers. KEY ON would re-enable function key strings, unchanged from their previous assignments. To restore the system default assignments, reset the computer. LEFT$ -- Get the leftmost characters of a string LEFT$ (string,count) This function returns a string containing the leftmost 'count' number of characters of the string expression. Count is an numeric expression in the range (0-255). If count is greater than the length of the string, the entire string will be returned. If count is zero, a null (empty) string will be returned. A$ = LEFT$("123ABC",3) Result is A$="123" LEN -- Get the length of a string LEN (string) This function returns the number of characters in a string expression. Nonprinting characters and blanks are counted. A = LEN("ABC") Result is A=3 LET -- Assign a value to a variable [LET] variable = expression The LET command is optional, since the equal sign by itself is understood by the computer to mean assignment. Multiple assignments on LET statements are not allowed. 10 LET A=1: LET B=A+1: LET C$=" THREE" 20 : D=1: E=D+1: F$=" THREE" 30 PRINT A;B;C$ 40 PRINT D;E;F$ Output: 1 2 THREE 1 2 THREE LINE -- Draw a line on a graphic screen LINE x0, y0, x1, y1 LINE draws a line on the currently defined graphic screen with the currently defined draw modes. The line is draw from (x0,y0) to (x1,y1). LIST -- List a BASIC program from memory or disk LIST [startline] [- [endline] ] LIST "filename" [,Ddrive] [<,|ON>Udevice] LIST is used to view part or all of a BASIC program in memory or all of a BASIC program on disk (without affecting the program that is currently in memory). The display can be slowed down by holding down the key or it can be paused by pressing the key or . A listing that is paused can be restarted by pressing again or by pressing . The display can be stopped by pressing . If the word LIST is followed by a line number, the computer shows only that line number. If LIST is typed with two numbers separated by a dash, the computer shows all lines from the first to the second line number. If LIST is typed followed by a number and just a dash, it shows all lines from that number to the end of the program. And if LIST is typed, a dash, and 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 easily brought to the screen for modification. LIST can be used in direct mode or in a BASIC program. 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 lines from the beginning until line 100. LIST 10-200 Shows lines from 10 to 200, inclusive. LOAD -- Load a program or data into memory from disk LOAD "filename" [,device_number [,relocate_flag]] This command loads a file into the computer's memory. The filename must be given, and pattern matching may be used. In the case of dual drive systems, the drive number must be part of the filename. If a device number is given, the file is sought on that unit, which must be a disk drive. If a device number is not given, the default system drive is used. See also DLOAD and RUN commands. The relocate_flag is used to LOAD binary files. If the relocate_flag is present and non-zero, the file will be copied into memory starting at the address stored on disk when the file was SAVEd. See BLOAD. Do not use the relocate_flag to load BASIC programs: they will be automatically relocated to the start of the BASIC program area and relinked. To compare a program in memory to a disk file, use the VERIFY or DVERIFY command. To compare a binary file, use BVERIFY. See the discussion at DLOAD regarding CHAINING programs. LOAD "PROG" Loads BASIC program PROG from the system drive. LOAD FILE$,DRV Loads a program whose name is in the variable called F$ from the unit whose number is in DRV. LOAD "0:PROG" 8 Loads BASIC program PROG from unit 8, drive 0. LOAD "BIN",8,1 Loads a binary file into memory. LOCATE -- [*** NOT YET IMPLEMENTED ***] LOG -- Get the natural logarithm of a number LOG (number) This function returns the natural logarithm of a numeric expression. A natural log is a log to the base e (2.71828183). See the EXP function. To convert to log base 10, divide by LOG(10). A = LOG(123) Result is A=4.81218436 A = LOG(123) / LOG(10) Result is A=2.08990511 LOOP -- See DO/LOOP/WHILE/UNTIL/EXIT LPEN -- Get the position of a lightpen PEN (position) This function returns the current position of a lightpen on the screen. When position=0, the X position is returned, and when position=1 the Y position is returned. Note that lightpen coordinates, like sprite coordinates, are offset from the normal graphic coordinate map. This means you have to calculate where the lightpen is with respect to the screen display. The electronics of each lightpen also introduces a skew which must be factored into your calculations. The X resolution is limited to every 2 pixels, and will always be an even number in the approximate range (60-320). The Y position is in the approximate range (50-250). If either the X or the Y position is zero, the lightpen is off-screen. Note that a lightpen COLLISION need not be enabled to use LPEN. A bright background color, such as white, is usually required to stimulate the light pen. Lightpens only work in game port 1. 10 TRAP 40 We're done if STOP key 15 BACKGROUND 1 Make background color white 16 FOREGROUND 0 Make text color black 20 COLLISION 3,100 Enable lightpen interrupt 30 DO:LOOP Hang here until done 40 END Done 100 COLLISION 3 Got one, don't want more 110 PRINT LPEN(0),LPEN(1) Display lightpen position 120 COLLISION 3,100 Re-enable interrupt 130 RETURN MID$ -- Substring function MID$ (string, position [,length]) This function can appear on the left or the right side of an assignment statement: Case 1: string_var = MID$ (string_expression, position [,length]) This form returns a piece of another string. The function returns a string of the specified length taken from the string_expression beginning at the indicated position. The position must be in the range (1-255), one (1) being the first character. The length can be any number in the range (0-255), or it can be omitted. If the position specified is greater than the number of characters in the string_expression, a null (empty) string is returned. If the length is greater than the number of characters from the given position to the end of the string_expression, or the length is omitted, then all the rightmost characters beginning at the position are returned. A$ = MID$("TICTACTOE",4,3) Result is A$="TAC" A$ = MID$("TICTACTOE",4) Result is A$="TACTOE" A$ = MID$("TICTACTOE",10,1) Result is AS="" (empty) Case 2: MID$ (string_var, position [,length]) = string_expression This form replaces a portion of the string contained in string_var with data from another string_expression, beginning at the specified position in the string_var. If the length is given only, that many characters from the string_expression are taken, otherwise all the characters in the string_expression will replace characters in the string_var beginning at the position specified. The there are too many characters to fit in the string_var, an 'ILLEGAL QUANTITY' error is reported. If the length given is zero, no characters will be replaced. A$="TICTACTOE": MID$(A$,4,3)="123456" Result is A$="TIC123TOE" A$="TICTACTOE": MID$(A$,4) ="123456" Result is A$="TIC123456" A$="TICTACTOE": MID$(A$,5) ="123456" Result is 'ILLEGAL QUANTITY' MONITOR -- Enter the built-in machine language monitor SEE SECTION 3.2 ON THE C64DX MONITOR. MOUSE -- Enable or disable the mouse driver MOUSE ON [,port [,sprite [,position] ] ] MOUSE OFF port = joyport 1, 2, or either (both) (1-3) sprite = sprite pointer (0-7) position = initial pointer location (x,y) normal, relative, or angular coordinate defaults to sprite 0, port 2 ???? add min/max x/y positions [*** THIS COMMAND IS SUBJECT TO CHANGE ***] Mouse ON enables the built-in mouse driver. The user must load a pointer into the proper sprite area ($600-$7FF). The driver assumes the "hot point" is the top left corner of the sprite, and does not allow this point to leave the screen. Mouse OFF will turn off the driver and the currently associated sprite. Use the RMOUSE function to get the current pointer position and button status. See the sample program at RMOUSE. MOVSPR -- Position sprite or set sprite in motion MOVSPR sprite <,x,y> Use the SPRITE command to turn on a sprite and MOVSPR to position it. Sprites are numbered 0-7. The sprite's position can be specified using one of the following coordinate types: [+/-]x, [+/-]y = [relative] position x#y = angle and speed x;y = distance and angle Angles are specified as 0-360 degrees, with 0 being straight up. Speeds are specified as a number of pixels per frame, 0-255. Sprites are moved through each pixel so that collisions are accurately detected. NEW -- Delete program in memory and clear all variables NEW [RESTORE] This command erases the entire program in memory and clears all variables and open channels (but it does NOT properly close open disk write files -- used DCLOSE or DCLEAR beforehand). NEW also resets the runtime stack pointer (clears GOSUB & FOR/NEXT stacks), the DATA pointer, and the PRINTUSING characters. The BASIC program in memory is lost unless it was previously SAVEd to disk. If you have not entered or loaded any BASIC programs since typing NEW, the RESTORE option will recover the BASIC program in memory. But if the BASIC environment has been changed in any way, the program may not be restored correctly. If BASIC can tell something's wrong, it will report 'PROGRAM MANGLED'. NEW can be used in direct (edit) mode or in a program. When it's encountered in a program, the program terminates. NEXT -- See FOR/NEXT/STEP and RESUME NOT -- Get the complement of a number NOT (expression) The NOT function returns the complement of an integer in the range (-32768 to 32767). The function operates on the binary value of signed 16-bit integers. An expression outside of this range will cause an 'ILLEGAL QUAUTITY' error. X = NOT(5) Result is X=-6 X = NOT(-6) Result is X=5 NOT is often used in logical comparisons (such as an IF statement) to invert the result, since -1 (true) is the result of NOT(0) (false), and 0 (false) is the result of NOT(-1) (true). X = NOT("ABC"="ABC") AND ("DEF"="DEF") Result is X= 0 (false) X = NOT("ABC"="ABC") AND ("DEF"="XYZ") Result is X=-1 (true) OFF -- Subcommand used with various BASIC commands. ON -- Computed GOTO/GOSUB ON expression line_number_list This is a variation of the IF GOTO statement that branches to one of several line numbers based upon the value of an expression. The integer value of the evaluated expression determines which line number in the line_number_list gets control. If the expression evaluates to one, the first line number in the list gets control, if it's two the second line number gets control, and so on. Fractional parts of the value are truncated (for example, 2.9 becomes 2). If the value is zero or greater than the number of items in the list the computer takes none of the branches and continues on with the next statement. If the value is negative, an 'ILLEGAL QUANTITY ERROR' is reported. The ON/GOSUB statement must call the first line number of a subroutine and the subroutine must end with a RETURN statement. After executing the subroutine, control is returned to the statement following the ON/GOSUB statement. 10 INPUT"ENTER A NUMBER 1-3: ",X 20 ON X GOTO 100, 200, 300 30 PRINT"TOO LOW OR TOO HIGH": RUN 100 PRINT"ONE": RUN 200 PRINT"TWO": RUN 300 PRINT"THREE": RUN OPEN -- Open a channel to a device or disk file OPEN logical_chnl_num, device_number [,secondary_adr [,]] Before a program can access a device or a file, an I/O channel must be opened to it to communicate through. When something is opened, you associate a logical channel number with it, and it is with this number that all other I/O statements access the device or file. The OPEN command can be used in direct (edit) mode or in a program. The channel number, device number, and optional secondary address are integers from 0-255. Refer to the device's manual for more information about what (if any) secondary addresses it uses. channel: 0-127 return = output return character only 128-255 return = output return + linefeed device: 0 Keyboard 1 Default system drive whatever its number is (see SET DEF) 2 RS232 3 Screen 4-7 Serial bus (usually reserved for printers) 8-31 Serial bus (usually reserved for disk drives) The filespec is the file name in the case of disk files (refer to your DOS manual for details). Typically, the filename is a string having the the following form: [[@|S]drive:] filename [,type] [,mode] An example would be 0:MYFILE,SEQ,READ to open the sequential file MYFILE for reading on drive 0. Disk drives usually support some kind of filename pattern matching. Most disk drives support the following file types and modes (can be abbreviated to first character): types: 'S'equential 'P'rogram 'R'elative 'U'ser modes: 'R'ead 'W'rite 'L'ength (for relative type files) Some channels or devices accept a command string instead of a filename when they are opened. An example would be the disk command channel or the RS232 open/setup command. Refer to the device's documentation. OPEN 1,8,15,"I" Open CBM disk command channel & send it the 'I'nitialize command. OPEN 4,4,7 Open CBM printer channel in upper/lower case mode. OPEN 128,2,2,CHR$(14) Open a 9600 8N1 RS232 channel and translate CR into CRLF on output. See also DOPEN, DCLOSE, CLOSE, CMD, GET#, INPUT#, and PRINT# statements and I/O status variables ST, DS, and DS$. OR -- Boolean operator expression OR expression The OR operator returns a numeric value equal to the logical OR of two numeric expressions, operating on the binary value of signed 16-bit integers in the range (-32768 to 32767). Numbers outside this range result in an 'ILLEGAL QUANTITY' error. X = 4 OR 8 Result is X=12 In the case of logical comparisons, the numeric value of a true situation is -1 (equivalent to 65535 or $FFFF hex) and the numeric value of a false situation is zero. X = ("ABC"="ABC") OR ("DEF"="DEF") Result is X=-l (true) X = ("ABC"="ABC") OR ("DEF"="XYZ") Result is X=-1 (true) X = ("ABC"="XYZ") OR ("DEF"="XYZ") Result is X= 0 (false) PAINT -- Fill a graphics area with color PAINT x,y, mode [,color] x,y coordinate to begin fill at mode 0: fill area to edge = color 1: fill area to edge=same as color at x,y PAINT fills an enclosed graphic area starting at the given coordinate with the color of the currently defined PEN. The mode parameter identifies the region to be filled. [*** THIS COMMAND IS NOT YET IMPLEMENTED ***] PALETTE -- Define a color PALETTE [screen#|COLOR], color#, red, green, blue PALETTE RESTORE screen# 0-1 color# 0-255 red 0-15 green 0-15 blue 0-15 The PALETTE command can be used to define a color for a logical graphic screen, set an absolute color, or restore the C64DX VIC-III default colors. PALETTE can be used in direct mode or in a program. The VIC-III pre-defines the first 16 colors to the usual C64-type colors, but you can change them with the PALETTE COLOR command or restore them all with the PALETTE RESTORE command. See the sample program after the SCREEN command. PASTE -- Put a CUT graphic area on the screen PASTE x,y [*** NOT YET IMPLEMENTED ***] PEEK -- Function returning the contents of a memory location PEEK (address) This function returns the contents of a memory location. The address must be an integer in the range of 0-65535 ($0-$FFFF) and the value returned will be an integer in the range of 0-255 ($0-$FF). Use the BANK command to specify which 64K memory bank the address is in. Note that a BANK number greater than 127 (i.e., a bank number with the most significant bit set) must be used to address an I/O location, such as the VIC chip or color memory. Refer to the system memory map for details. PEEK uses the DMA device to access memory. Use the POKE command to change the contents of a memory location. BANK 0: X = PEEK (208) Reads the keyboard buffer index. If it's empty, X will be zero, otherwise X will be the number of characters in it. PEN -- Specify a pen color for drawing on graphic screen PEN pen, color pen 0-2 color 0-255 Before you can draw anything on a graphic screen, you have to tell BASIC what color your PENs are. You should first define what your colors are using the PALETTE command, then use PEN to associate those colors with a PEN. Whatever graphic commands you use after a PEN command will use the PEN you specified. PEN 0,1 Put color 1 "ink" into draw pen 0 See the sample program after the SCREEN command. PIC -- Graphic picture subcommand PLAY -- Play a musical string PLAY "[Vn,On,Tn,Un,Xn,elements]" [*** WILL CHANGE TO ADD 2ND SID SUPPORT ***] The PLAY command lets you select a voice, octave, instrument, volume, filter, and musical notes. All these parameters are packed into a string (spaces are allowed for readability). On = Octave (n=0-6) Tn = Tune envelope # (n=0-9) 0= piano (defaults) 1= accordion 2= calliope 3= drum 4= flute 5= guitar 6= harpsichord 7= organ 8= trumpet 9= xylophone Un = Volume (n=0-9) Vn = Voice (n=1-3) Xn = filter on (n=1), off (n=0) Elements: A,B,C,D,E,F,G ... Notes, may be preceded by: # ................. Sharp S ................. Flat . ................. Dotted W ................. Whole note H ................. Half note Q ................. Quarter note I ................. Eighth note S ................. Sixteenth note R ................. Rest M ................. Wait for all voices playing to end (a measure) Once the music string starts PLAYing, the computer will continue with the next statement. The music will continue to play automatically. Using the 'M'easure command will cause the computer to wait until the music has up to that point has been played out. Use the TEMPO command to alter the tempo (speed) of PLAY. Note that the VOLume command can change a PLAY string's volume setting. POINTER -- Get the address of a variable descriptor POINTER (variable_name) This function returns the address of an entry in the variable table. If the value returned is zero, the variable is currently undefined. The variable table is normally in the second RAM bank (BANK 1). See the section on variable storage for details. Note that, while the location of a string descriptor will not change, the location of the actual string in memory changes all the time. Also, when working with an array name you must specify a particular element, to which POINTER will return a pointer to that element's descriptor and not to the array descriptor. 10 A$="FRED" Define A$ 20 DESC=POINTER (A$) Lookup A$ in variable table 30 BANK1: PRINT PEEK(DESC) Displays the length of A$ PORE -- Write a byte to memory location POKE address, byte [,byte ...] POKE is used to write one or more bytes into one or more memory locations. The address must be an integer in the range of 0-65535 ($0-SFFFF) and the value to be written must be an integer in the range of 0-255 ($0-$FF). If more than one byte is given, it will be written into successive memory locations. Use the BANK command to specify which 64K memory bank the address is in. Note that a BANK number greater than 127 (i.e., a bank number with the most significant bit set) must be used to address an I/O location, such as the VIC chip or color memory. Refer to the system memory map for details. Also note that, unlike previous CBM computers, POKEs to a ROM location will not "bleed through" into a corresponding RAM location. POKE uses the DMA device to access memory. Use the PEEK function to read a byte from a memory location. Because this command directly accesses system memory, extreme care should be taken in its use. Altering the wrong memory location can crash the computer (press the reset button to reboot). BANK 0: POKE 208,0 Resets location 208 ($000D0), clearing the keyboard buffer. BANK 128: POKE DEC("D023"),1,2,3 Sets the VIC extended background colors to 1, 2, and 3 respectively POLYGON -- Draw a regular n-sided figure on a graphic screen POLYGON x,y, xradius,yradius, [solid], angle,drawsides,sides,subtend x,y = center of polygon x,yradius = radii of polygon solid = solid flag (0-1) angle = starting angle (0-360) drawsides = # of sides to draw (3-127) sides = # sides of polygon (drawsides<=sides) subtend = subtend flag (0-1) POS -- Get the column number of the cursor POS(0) This function returns the current text column the cursor is in, with respect to the currently defined window (see RWINDOW). It's usually used to format text printed to the screen. The argument (0) is not used for anything. POS will not work as expected if text output is redirected to a disk file or the printer. 10 MAXCOL = RWINDOW(l) 20 FOR ADR=DEC("600") TO DEC("7FF") 30 PRINT HEX$(PEEK(ADR));" "; 40 IF POS(0) > (MAXC0L-5) THEN PRINT 50 NEXT This example illustrates one way to format output to the screen, keeping the last item on a line from being split between two lines, regardless of the window size (as long as the window size is at least 4 characters wide). It dumps the data for the first sprite in hex. POT -- Paddle function POT (paddle) This function returns the state of a game paddle (POTentiometer) controller in one of the two game ports. paddle=1 ..... Position of paddle #1 (port 1, paddle "A") paddle=2 ..... Position of paddle #2 (port 1, paddle "B") paddle=3 ..... Position of paddle #3 (port 2, paddle "A") paddle=4 ..... Position of paddle #4 (port 2, paddle "B") The value returned by POT ranges from 0 to 255. Any value greater than 255 means that the fire button is also pressed. Paddles are read "backwards" from normal things like volume knobs or faucets. A value of 255 means the paddle has been turned counterclockwise as far as it will go ("off"), and a value of 0 means the paddle has been turned clockwise as far as it will go "on"). Note that some paddles are "noisy" and their output must be averaged or "damped" to prevent whatever they are controlling from jittering. 10 SPRITE 1,1 Turn on a sprite 20 DO Begin a loop 30 X=POT(3) Read paddle "A" in port 2 40 MOVSPR 1,300-(X AND 254),200 Move the sprite 50 LOOP UNTIL X>255 Loop until button pressed 60 SPRITE 1,0 Turn off sprite This sample program turns on a sprite and lets you move it horizontally with a paddle. If you press the paddle's fire button, it turns off the sprite and the program ends. The calculations in line 40 do several things all at once -- they mask the fire button and "damp" the output to reduce jitter by masking the least significant bit (the X AND 254 part) and invert the output so that turning the paddle to the right makes the sprite go right (subtracting result from 300). PRINT -- Display data on text screen PRINT [expression_list] [<,|;>] PRINT will evaluate each item in the expression_list and pass the results to the system screen editor to display on the screen. If a screen window is defined, the output will be confined to the window. PRINT can be used to send control codes and escape sequences to the screen editor to do such things as set windows, change TAB stops, change text colors or set reverse field, or choose cursor styles. See the section on Editor modes for details. PRINT can be followed by any of the following: Numeric or string expressions 12, "HELLO", 1+1, "S"+STR$(I) Variable names A, B, A$, X$ Functions ABS(33), HEX$(160) Punctuation marks ;, Nothing Numeric values are always followed by a space. Positive numbers are preceded by a space, and negative numbers are preceded by a minus sign ('-'). Scientific notation is used when a number is less than 0.01 or greater than or equal to 999999999.2 . A semicolon (';') or space between list items causes the next item to be printed immediately following the previous item. A comma (',') causes the next item to be printed at the next comma stop (similar to TAB stops, but every 10 spaces). These rules apply to the next print statement, if the expression_list ends with either a semicolon or a comma, otherwise a return is printed. Note that floating point variable names should not be separated from the next variable name with a space, and constants should not be preceeded or followed by a space. For formatted PRINT output, see the PRINT USING command. PRINT "HELLO" HELLO A$="THERE": PRINT "HELLO ";A$ HELLO THERE A=4:B=2: PRINT A+B 6 J=41: PRINT J;: PRINT J-1 41 40 C=A+B:D=B-A: PRINT A;B;C;D 4 2 6 -2 C=A+B:D=B-A: PRINT A,B,C,D 4 2 6 -2 A=1:B=2:AB=3: PRINT A B 3 PRINT 1 2 3, 1 2 3 +1 123 124 PRINT 0.009, 0.01 9E-03 .01 PRINT 999999999; 999999999.2 999999999 1E+09 The CMD command can be used to redirect PRINT output to a device or file. Also see the POS, SPC, TAB functions, CHAR and PRINT USING. PRINT# -- Send data to an I/O channel (file) PRINT#logical_channel_number [,expression_list] [<,|;>] This command is used to send (transmit) data to a device or file. The logical_channel number is the number assigned to the device (file) in an OPEN (or DOPEN) statement. The output is otherwise identical to that of a PRINT statement, including the comma and semicolon conventions. Note that certain screen-oriented functions, such as TAB and SPC do not have the same effect as they do with screen I/O. It's good practice to examine the I/O status byte (and the DS disk status for file I/O) after every I/O instruction to check for problems or errors. For formatted output, use the PRINT# USING command. 10 OPEN 1,8,15 Initialize disk drive 20 PRINT#1,"I" (same as DCLEAR) 30 CLOSE 1 10 DOPEN#1,"NEWFILE",W Create a SEQ file 20 FOR I=1 TO 10 30 PRINT#1, I, STR$(I) Write numbers 1-10 to it 40 NEXT 50 DCLOSE#1 10 OPEN 2,2,2,CHR$(12) Open 1200 baud RS232 channel 20 PRINT#2, "ATDT,5551212" Send modem a Hayes dial command PRINT USING -- Output formatted data to the screen, device, or file PRINT [#logical_channel_number,] USING format; expression_list [<,|:>] Read about the PRINT and PRINT# commands first for information regarding the syntax of the expression list and, for device output, establishing the logical_channel_number. The items in the expression list must be separated by commas (','). The format is defined in a string literal or string variable and is described below. See the PUDEF command for specifing special formatting characters. The various formatting characters are: CHARACTER SYMBOL NUMERIC STRING ---------------- ------ ------- ------ Pound 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 pound sign ('#') reserves room for a single character in the output field. If the data item contains more characters than the number of pound signs in the format field, the entire field will be filled with asterisks ('*'). 10 PRINT USING "####";X For these values of X, this format displays: A = 12.34 12 A = 567.89 568 A = 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 pound signs in the format item. Truncation occurs on the right. The plus ('+') and minus ('-') signs can be used in either the first or last position of a format field but not both. The plus sign is printed if the number is positive. The minus sign is printed if the number is negative. 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 sign nor a minus sign is used in the format field for a numeric data item, a minus sign is printed before the first digit or dollar symbol if the number is negative and no sign is printed if the number is positive. This means that one more character is printed if the number is positive. If there are too many digits to fit into the field specified by the pound sign and +/- signs, then an overflow occurs 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 number is rounded to the nearest integer and printed without any decimal places. When a decimal point is specified, the number of digits preceding the decimal point (including the minus sign, if the number is negative) must not exceed the number of pound 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 appears in a printed number. Only commas within a number are printed. Unused commas to the left of the first digit appear as the filler character. At least one pound sign must precede the first comma in a 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. FIELD EXPRESSION RESULT COMMENT ------ ----------- ------ ----------------------------- ##.# -.1 -0.1 Leading zero added ##.# 1 1.0 Trailing zero added #### -100.5 -101 Rounded to no decimal places ###. 10 10. Decimal point added #$## 1 $1 Leading dollar sign #### -1000 **** Overflow because 4 digits and minus sign don't fit in field 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 number), specify at least one pound sign before the dollar sign. If a dollar sign is specified without a leading pound sign, the dollar sign is printed in the position shown in the format field. If commas and/or a plus or minus sign is specified in a format field with a dollar sign, the program prints a comma or sign before the dollar sign. The four up arrows or carets symbol is used to specify that the the number is to be printed in E format (scientific notation). A pound sign must be used in addition to the four up arrows to specify the field width. The arrows can appear either before or after the pound sign in the format field. Four carats must be specified when a number is to be printed in E format. If more than one but fewer than four carats are specified, a syntax error results. If more than four carats are specified only the first four are used. The fifth carat is interpreted as a no text symbol. An equal sign ('=') is used to center a string in a field. The field width is specified by the number of characters (pound sign and =) in the format field. If the string contains fewer characters than the field width, the string is centered in the field. If the string contains more characters that can be fit 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. 5 X=32: Y=100.23: A$="TEST" 10 PRINT USING "$##.## ";13.25,X,Y 20 PRINT USING "###>#";"CBM",A$ When this is RUN, the following output appears on the screen: $13.25 $32.00 $***** CBM TEST $***** is printed instead of Y because Y has 5 digits, which exceeds the format specification. The second line asks for the strings to be right justified, which they are. PUDEF -- Redefine PRINT USING symbols PUDEF definition_string PUDEF allows redefinition of up to 4 symbols in the PRINT USING statement. Blanks, commas, decimal points, and dollar signs can be changed into some other character by placing the new character in the correct position in the PUDEF definition_string. Position 1 is the filler character. The default is a space character. Place another character here to be used instead of spaces. Similarly, Position 2 is the comma character. Default is a comma. Position 3 is the decimal point. Position 4 is the dollar sign. 10 PUDEF "*" PRINTs * in the place of blanks. 20 PUDEF " @" PRINTs @ in place of commas. QUIT -- [*** UNIMPLEMENTED ***] RCLR -- Get the current screen color RCLR(source) [*** CURRENTLY UNIMPLEMENTED ***] This function returns the color assigned to source as an number in the range of 0-15. The color sources are: 0 = background 1 = foreground 2 = multicolor 1 3 = multicolor 2 4 = border 5 = highlight color RDOT -- Get the current position or color of the pixel cursor RDOT(source) [*** CURRENTLY UNIMPLEMENTED ***] This function returns information about the current pixel location. 0 = current X position 1 = current Y position READ -- Read data from DATA statements READ variable_list READ statements are used along with DATA statements. READ statements read data from DATA statements into variables, just like an INPUT statement reads data typed by the user. READ statements can be used in direct or program mode, but DATA statements must be in a program. The variable types in the variable_list must match the type of DATA being read, or a 'TYPE MISMATCH' error is reported. If there are insufficient data in the program's DATA statements to satisfy all of the variables in the READ statement, an 'OUT OF DATA' error is reported. The computer maintains a pointer to the next DATA item to be read by a READ statement. Initially this pointer points to the beginning of the program. As each variable in a READ statement is filled, the computer moves the DATA pointer to the next DATA item. If all of a READ statement's variables are filled before all of the data has been read from a DATA statement, the next READ statement will begin reading data at the point where the previous READ stopped. The DATA pointer can be changed by the RESTORE command. It can be reset back to the beginning of the program, or pointed to a specific line number. See RESTORE. 10 DATA 100, 200, FRED, "HELLO, MOM", , 3.14, ABC123, -1.7E-9 20 READ X,Y 30 READ NAME$, MSG$, NULL$ 40 READ PI, JUNK$, S 50 RESTORE RECORD -- Specify a relative disk file record number RECORD #logical_channel_number, record [,byte] This command allows you to access any part of any record in a RELative type disk file. If the byte parameter is omitted, the access pointer is pointed at the first byte of the specified record number. Before you can use RECORD, you must OPEN a file. See OPEN and DOPEN for instructions. Also refer to your DOS manual for an explanation of RELative type files. 10 INPUT"ENTER RELATIVE FILENAME: ",F$ get name of existing file 20 DOPEN#1, (F$),L: PRINT DS$ open it & display disk status 30 R=1: INPUT"ENTER RECORD NUMBER: ",R get a record number 40 B=1: INPUT"ENTER BYTE (RETURN): ",B get byte number, if any 50 RECORD#1, R,B position file pointer 60 INPUT#1, REC$ read the record 70 PRINT REC$ display the record 80 PRINT "CONTINUE? (Y/N)" 90 GETKEY A$: IF A$="Y" THEN 30 100 DCLOSE#1 close the file REM -- Place an explanatory remark or comment in a program REM plain text message The REMark command is just a way to leave a note to whomever is reading a LISTing of the program. It might explain a section of the program, give information about the author, etc. REM statements in no way effect the operation of the program, except to add length to it (and therefore slow it down a little). No other executable statement can follow a REMark on the same line. 10 REM THIS PROGRAM WAS WRITTEN ON 2/14/91 BY F.BOWEN 20 REM SAMPLE PROGRAM 30 : 40 DIR :REM DISPLAY THE DISK DIRECTORY 50 LIST "SAMPLE PROGRAM" :REM DISPLAY THIS PROGRAM 60 END RENAME -- Rename a disk file RENAME "oldname" TO "newname" [,Ddrive] [Udevice] The RENAME command changes the name of a file in the disk directory. Pattern matching is not allowed, and "newname" must be a valid filename that does not already exist on the disk. The file being renamed does not need to be open. RENAME "TEST" TO "FINALTEST" RENAME (OLD$) TO (OLD$+".OLD") ON U(DEV) RENUMBER -- Renumber the lines of a BASIC program RENUMBER [new_starting_line [,[increment] [,old_starting_line]]] Renumber is used to resequence the line numbers of a BASIC program in memory. All or part of a program can be renumbered. The RENUMBER command first scans the program to make sure all the line numbers referenced in commands (such as GOTO, GOSUB, TRAP, etc.) exist, that new line numbers are in the legal range, and that changing the program would not overflow the available memory. An 'UNRESOLVED REFERENCE', 'LINE NUMBER TOO LARGE', or 'OUT OF MEMORY' error is reported if there's a problem, and RENUMBER is automatically canceled without having changed anything. If the program passes all the checks, RENUMBER changes the specified line numbers and updates all references to the old numbers throughout the program and relinks the program. The new_starting_line is the number of the first line in the program after renumbering. It defaults to 10. The increment is the spacing between line numbers (eg., 10, 20, 30 would mean an increment of 10). It also defaults to 10. The old_starting_line is the line number in the program where you want renumbering to begin. RENUMBER can be used in direct (edit) mode only. Note that line number zero (0) is a valid line number. RENUMBER Renumbers the entire program. After renumbering, the first line will be 10 the second 20, etc. through the end of the program. RENUMBER ,1 Renumbers the entire program as above, but in increments of one. The first line will be 10, the second 11, etc. RENUMBER 100, 5, 80 Starting at line 80, renumbers the program. Line 80 becomes line 100, and lines after that are numbered in increments of 5, through the end of the program. RENUMBER ,,65 Starting at line 65, renumbers lines in increments of 10, starting at line 10 through the rest of the program. RESTORE -- Position READ pointer at specific DATA statement RESTORE [line] The computer maintains a pointer to the next DATA item to be read by a READ statement. Initially this pointer points to the beginning of the program. The DATA pointer can be changed by the RESTORE command. Using RESTORE without specifying a line number will reset the DATA pointer back to the beginning of the program. If a line number is specified, the DATA pointer is pointed to that line. The line does not have to contain a DATA statement. When the computer executes the next READ statement, it will look for the next DATA item starting at the line the DATA pointer is at. See the READ command an example. RESUME - Resume program execution after error TRAP RESUME [line|NEXT] Used to return to execution after TRAPping an error. If a line number is given, the computer performs a 'GOTO line' and resumes execution at that line. RESUME NEXT resumes execution at the statement following the one that cause the error. RESUME without any parameters will resume execution at the statement that cause the error. If the computer encounters a RESUME statement outside of a TRAP routine or if a TRAP was not in effect a 'CAN'T RESUME' error is reported. RESUME can only be used in program mode. 10 TRAP 90 20 FOR I=-5 TO 5 30 PRINT 5/I 40 NEXT 50 END 60 : 90 PRINT ERR$(ER): RESUME NEXT RETURN -- Return from subroutine or event handler RETURN This statement is associated with the GOSUB (GO SUBroutine) statement. When a subroutine is called by a GOSUB statement, the computer remembers where it's at before it calls the subroutine. When the computer encounters a RETURN statement, it returns to the place it last encountered a GOSUB and continues with the next statement. If there wasn't a previous GOSUB, then a 'RETURN WITHOUT GOSUB' error is reported. RETURN is also used by event handlers, set up by the COLLISION command. See COLLISION. RGR -- Get the current graphic mode RGR(0) [*** CURRENTLY UNIMPLEMENTED ***] This function returns current graphic mode. A result of zero means the display is text, a non-zero result means it's graphic. RIGHT$ -- Get the rightmost characters of a string RIGHT$ (string,count) This function returns a string containing the rightmost 'count' number of characters of the string expression. Count is an numeric expression in the range (0-255). If count is greater than the length of the string, the entire string will be returned. If count is zero, a null (empty) string will be returned. A$ = RIGHT$("123ABC",3) Result is A$="ABC" RMOUSE -- Get the mouse position and button status RMOUSE [Xposition [,Yposition [,button]]] X,Yposition = current position of mouse pointer sprite Button = current status of mouse buttons 0 = no button 1 = right button 128 = left button 129 = both buttons RMOUSE is a command which retrieves a mouse's current position and the state of its buttons, and places this information into the specified numeric variables. If a mouse is not installed, "-1" is returned for all variables. If both ports are enabled, buttons from each port are merged. Use the MOUSE command to turn a mouse on or off. 10 MOUSE ON, 2, 1 Turn mouse on, port 2, sprite 1 20 DO Begin loop 30 RMOUSE X, Y, B Get mouse position & buttons 40 PRINTUSING"### ";X,Y,B Show " " " 50 LOOP UNTIL B=129 Loop until user presses both buttons 60 MOUSE OFF Turn mouse off RND -- Get a pseudo-random number RND (type) The RND function returns a pseudo RaNDom number between 0 and 1. The random sequence returned is determined by the type parameter: type = 0 Returns a random number based upon the system clock. type < 0 Negative numbers "seed" the random number generator, defining a new but reproducible random sequence. type > 0 Positive numbers draw the next random number from the sequence defined by the last "seed" value. This lets a programmer use a reproducible sequence while debugging (fixing) a program, so that random errors can be easily reproduced. Once the program has been fixed, it can be "seeded" such that a random sequence is used every time the program is run. 10 DO 20 INPUT "SEED"; S 30 IF S=0 THEN END 40 FOR I=1 TO S 50 PRINT INT(RND(1)*6)+1, INT(RND(1)*6)+1 60 NEXT 70 LOOP The above program will demonstrate the results of seeding the random number generator. It lets you specify a positive or negative seed value, and then prints the first S random pairs of that sequence. Enter a zero to end the program. The calculations in line 50 make the random numbers be integers from 1 to 6, like dice. Type in a negative dice from that sequence. Every time you enter "-1", for example, you will roll the same numbers: first roll 2 and 6 second 6 and 1 third 1 and 1 fourth 1 and 4 fifth 5 and 5 Games and statistical programs should use RND(0) for true randomness or seed the generator with a random number, such as RND(-TI). The general form for getting random integers using RND is: INT( RND(0) * MAX ) + 1 where MAX is the highest number you can get. This gives you numbers as low as 1 and as high as MAX. For dice, MAX is 6 (or 12 if you want to simulate rolling two dice at once). For cards, MAX is 52. INT( RND(0) * 16) This form will return integers from zero to 15, which is useful for generating random colour values, for example. RREG -- Get register data after a SYS call RREG [a_reg] [,[x_reg] [,[y_reg] [,[z_reg] [,status] ]]] Following a SYS call, the RREG command retrieves the contents of the microprocessor's registers and puts them into the specified numeric variables. See the sample program at SYS. RSPCOLOR -- Get multicolor sprite colors RSPCOLOR (multicolor#) Returns the current colors for multicolor sprites. Color values range from 0-15. Use RSPRITE function to get the foreground sprite color. multicolor# = 1 gets multicolor #1 multicolor# = 2 gets multicolor #2 See SPRITE and SPRCOLOR. RSPPOS -- Get the location and speed of a sprite RSPPOS (sprite,parameter) The RSPPOS function returns the current X or Y position of a sprite and its speed, set by the MOVSPR command. A sprite does not have to be on to use RSPPOS. The sprite number must be in the range of 0-7, and the parameter is: 0 to get current X position 1 to get current Y position 2 to get current speed (0-255) RSPRITE -- Get information about a sprite RSPRITE (sprite,parameter) The RSPRITE function returns the current state of a sprite, set by the SPRITE command. The sprite number must be in the range of 0-7, and the parameter is: 0 to see if it's turned on (1)=yes (0)=no 1 to get sprite foreground color (0-15) 2 to get priority over background (1)=yes (0)=no 3 to get X-expansion factor (1)=yes (0)=no 4 to get Y-expansion factor (1)=yes (0)=no 5 to get multicolor factor (1)=yes (0)=no RUN -- execute BASIC program RUN [line #] RUN "filename" [,Ddrive] [Udevice] RUN executes the BASIC program that is currently in memory. The program has to be LOADed (DLOAD) or manually typed in before it can be executed. If a line number is specified, execution begins at that line. If a filename is specified, the program is automatically loaded from disk into memory and executed. RUN can be used in a program. RUN clears all variables and open channels (but it does NOT properly close open disk write files -- used DCLOSE or DCLEAR beforehand). RUN also resets the runtime stack pointer (clears GOSUB & FOR/NEXT stacks) the DATA pointer, and the PRINT USING characters. To start a program without initializing everything, use GOTO. RUN Starts the program at the first line. RUN 100 Starts the program at line 100. RUN "TEST" Loads the program TEST from the, default system disk and starts the program at the first line. RWINDOW -- Get information about the current text window RWINDOW (parameter) This is a function that returns information about the current console text display. The parameter is specified as: 0 to get the maximum line # in the current window 1 to get the maximum column # in the current window 2 to get the screen size, either 40 or 80 columns SAVE -- Save a BASIC program in memory to disk SAVE "[[@]drive:]filename" [,device_number] This command copies a BASIC program in the computer's BASIC memory area into a PRoGram-type disk file. If the file already exists, the program is NOT stored and the error message 'FILE EXISTS' is reported. If the filename is preceded with an '@0:', then if the file exists it will be replaced by the program in memory. Because of some problems with the 'save-with-replace' option on older disk drives, using this option is not recommended if you do not know what disk drive is being used (DELETE the file before SAVEing). Pattern matching is not allowed. In the case of dual drive systems, the drive number must be part of the filename. Use the VERIFY or DVERIFY command to compare the program in memory with a program on disk. To save a binary program, use the BSAVE command. SAVE "myprogram" Creates the PRG-type file MYPROGRAM on the default system disk and copies the BASIC program in memory into it. SAVE "@0:myprogram" Replaces the PRG-type file MYPROGRAM with a new version of MYPROGRAM. If MYPROGRAM doesn't exist, it's created. SAVE F$,9 Saves a program whose name is in F$ on disk unit 9. SCALE -- Set the logical dimension of the graphic screen [*** NOT YET IMPLEMENTED ***] SCNCLR -- Clear a text or graphic screen SCNCLR [color] This command will clear the current text window if [color] omitted, otherwise it will clear the current graphic screen using the given color value. See also SCREEN CLR. SCNCLR Clears the text screen. If a window is defined it clears only the window area. SCNCLR 0 Clears the current graphic screen with color 0. SCRATCH -- Delete files from disk directory Recover accidentally deleted files SCRATCH "filespec" [,Ddrive] [Udevice] [,R] SCRATCH, ERASE, or DELETE are different names of the same command. They are used to delete a file from a disk directory, or optionally to recover if possible an accidentally deleted file. The diskette must not be 'write protected', or a 'WRITE PROTECT ON' error is reported. WARNING: Deleting a file will destroy all existing data in that file. Be extremely careful if you are using pattern matching, which can delete any or all files. In direct mode, you are asked to confirm what you are doing with 'ARE YOU SURE?'. Type 'Y' and press to proceed, or type any OTHER CHARACTER and press to cancel the command. In program mode there is no confirmation prompt. Upon completion, in direct mode only, the computer will display the number of files deleted. Refer to your disk manual for other details. Different disk drives implement slightly different pattern matching rules or support features such a specially protected files. If the 'R'ecover option is present and the DOS supports it, a deleted file can be recovered if nothing else has been written to the diskette since the file was accidentally deleted. You will still be asked to confirm the operation, and upon completion the computer will display the number of files restored. SCRATCH "oldfile" Deletes the file OLDFILE from the disk in the default system drive. SCRATCH "file.*" Deletes all files beginning with FILE. SCRATCH (F$), U(DD) Deletes the file whose name is in F$ from the disk in device DD. SCRATCH "SAVEME", R Attempt to recover the program SAVEME. SCREEN -- Graphic command The SCREEN command is used to initiate a graphic command. It always precedes another command word which identifies the graphic operation to be performed: SCREEN CLR - Set graphic screen color SCREEN CLR color# Clears (erases) the currently opened graphic screen using the given color value. Use SCNCLR to clear a text screen. See also SCNCLR. SCREEN DEF - Define a graphic screen SCREEN DEF screen#, width, height, depth screen# 0-1 width 0=320, 1=640, 2=1280 height 0=200, 1=400 depth 1-8 bitplanes (2-256 colors) Defines a logical screen (numbered 0 or 1), specifies its size and how many colors (bitplanes) it has. It does not allow access to the screen and it does not display the screen. The screen must be defined before it is opened for viewing and/or drawing to. SCREEN SET - Set draw and view screens SCREEN SET DrawScreen#, ViewScreen# draw screen # 0-1 view screen # 0-1 This command specifies which logical screen is to be viewed and which logical screen is to be accessed by the various draw commands. The screen must be defined and opened first. Both the draw and the view screen can be, and usually are, the same logical screen. For double buffering, they are different. SCREEN OPEN - Open a screen for access SCREEN OPEN screen# [,error_variable] screen# 0-1 error_variable [*** NOT YET IMPLEMENTED ***] This command actually sets up the screen and allocates the necessary memory for it. If it's the view screen it will be displayed. If it's the draw screen, it can now be drawn to. If there is not enough memory for the screen, 'NO GRAPHICS AREA' is reported and the screen is not opened. SCREEN CLOSE - Close a screen SCREEN CLOSE screen# screen# 0-1 This command closes a logical screen, ending access to it by the draw commands if it's the draw screen and restoring the text screen if it's the view screen. SCREEN CLOSE deallocates any memory reserved for the screen. SAMPLE GRAPHIC PROGRAM: 1 TRAP 170 in case of error want text screen 10 GRAPHIC CLR initialize graphics 20 SCREEN DEF 1,0,0,2 define a 320x200x2 graphic screen 30 SCREEN OPEN 1 open it 40 PALETTE 1,0, 0, 0, 0 define screen 1 color 0 = black 50 PALETTE 1,1, 15, 0, 0 define screen 1 color 1 = red 55 PALETTE 1,2, 0, 0,15 define screen 1 color 2 = blue 60 PALETTE 1,3, 0,15, 0 define screen 1 color 3 = green 70 SCREEN SET 1,1 make it the view screen 80 SCNCLR 0 clear screen with palette color 0 90 BORDER 0 set border color to color 0 100 PEN 0,1 make draw pen = color 1 (red) 110 LINE 100,100, 150,150 draw a diagonal red line 120 PEN 0,2 make draw pen = color 2 (blue) 130 BOX 50,50, 50,80, 80,50, 80,80 draw a blue box 140 PEN 0,3 make draw pen = color 3 (green) 150 CHAR 25,50, 1,1,2, "WORDS" draw green text 160 SLEEP 5 pause for 5 seconds 170 SCREEN CLOSE 1 close graphic, get text screen 180 PALETTE RESTORE restore normal system colors 190 BORDER 6 restore normal border color 200 END SET -- Set various system parameters The SET command is used to set a system parameter. It always precedes another command word which identifies the parameter to be changed: SET DEF - Set default system disk drive SET DEF device The BASIC DOS commands default to disk unit 8. Use SET DEF to change which device these commands default to. This command does not renumber a disk device, use SET DISK for that. Commands which specify a device will still access the device they specified. A program can be made more "user friendly" by either not specifying a drive (thus using the user's preferred drive) or by specifying device 1. Device number 1 means "use the system default drive, whatever its number is." 10 DIR gets directory of device 8 20 DIR U1 gets directory of device 8 30 DIR U10 gets directory of device 10 40 SET DEF 10 change the default drive to unit 10 50 DIR gets directory of device 10 60 DIR U1 gets directory of device 10 70 DIR U8 gets directory of device 8 SET DISK - Change a disk device number SET DISK oldnumber TO newnumber Use this command to renumber (change) a disk drive's unit number. Not all drives can be renumbered -- refer to your disk drive manual for details. This command sends to the disk's command channel the conventional CBM serial disk drive "M-W" command. See also the DISK command, which lets you send any command to a disk drive. SET DISK 8 TO 10 Change unit 8's number to 10 Because the built-in C64DX drives always take precedence over serial bus drives, this is one way to get the built-in drive "out of the way" so that you can access a serial bus drive #8. SGN -- Get the sign of a number SGN (expression) The SiGN function returns the sign of a numeric expression as follows: If the expression is < 0 (negative) .... returns -1 If the expression is = 0 (zero) ........ returns 0 If the expression is > 0 (positive) .... returns 1 SIN -- Sine function SIN (expression) This function returns the sine of X, where X is an angle measured in radians. The result is in the range -1 to 1. X = SIN (pi/4) Result is X=0.707106781 To get the sine of an angle measured in degrees, multiply the numeric expression by pi/180. SLEEP -- Pause program execution of a specified period of time SLEEP seconds Temporarily suspends execution of your program for 1 to 65535 seconds. SLOW -- Set system speed to 1.02MHz SLOW is used primarily to directly access "slow mode only" devices such as the SID sound chips. FAST is the default system speed. SOUND -- Produce sound effects SOUND v, f, d [,[dir] [,[m] [,[s] [,[w] [,p] ]]]] v = voice (1-6) f = frequency (0-65535) d = duration (0-32767) dir = step direction (0(up), 1(down), or 2(oscillate)) default=0 m = min frequency (0-65535) default=0 s = sweep (0-65535) default=0 w = waveform (0=triangle,1=saw,2=square,3=noise) default=2 p = pulse width (0-4095) 50% duty cycle=default=2048 The sound command is a fast and easy way to create sound effects and musical tones. The first three parameters are required to select the voice, frequency, and duration of the tone. The duration is specified in "jiffies" (60 jiffies = 1 second). Optionally, you can specify a waveform and, for square waves, the pulse width. The SOUND command can sweep a voice through a series of equally-spaced frequencies. The direction of the sweep, minimum and maximum frequencies can be programmed. If time expires before the sweep is done, the sound stops. If the minimum or maximum frequency is reached before time expires, the sound repeats. For programming details, refer to the SID hardware documentation. Use the VOLume command to change the volume of the sound. Note that the TEMPO command affects PLAY strings only, not SOUND effects. FREQout = ( f * 0.0596 ) Hz PWout = ( p / 40.95 ) % Each voice can be programmed separately and played simultaneously for a wide variety of sound effects. Once a sound effect is initiated, BASIC execution continues with the next statement while the sound plays out, allowing you to combine and control graphics, animation, and sound from a BASIC program. The examples below include information about how to generate precise tones for exact times, but for most casual users trial and error are perfectly acceptable! (Note that the values used are for 60Hz (NTSC) systems): Using voice 1, emit a square-wave, 440Hz tone for 1 second. Note that 440Hz = 7382 * 0.0596 using the above formula. SOUND 1, 7382, 60 Using voice 2, sweep from 100Hz (m=1638) to 440Hz (f=7382) in increments of 1Hz (s=17). The time required to do this can be calculated as t=(f-m)/s, so t=336 jiffies. SOUND 2, 7382, 336, 0, 1678, 17 Using voice 3, make a neat sound using an oscillating sweep (dir=2) and a sawtooth waveform (w=1) for 3 seconds (t=180). SOUND 3, 5000, 180, 2, 3000, 500, 1 SPC -- Space PRINT output SPC (number) The SPaCe function is used to format PRINTed data to the screen, a printer, or a file. It specifies the number of spaces to be skipped, from 0 to 255. A semicolon (';') is always assumed to follow SPC, even if it appears at the end of a print line. The SPC function works a little differently on screen, printer and disk output. On the screen, SPC skips over characters already on the screen, which is not the case with printer and disk output. On printers, if the last character on a line is skipped, the printer will automatically perform a carriage return and linefeed. PRINT "123";SPC(3);"456" Displays '123 456' PRINT "X";SPC(5) :PRINT"X" Displays 'X X' See also the TAB function. A better way to format PRINT output is with PRINT USING. SPRCOLOR -- Set multicolor sprite colors SPRCOLOR [sprite_mc1] [,sprite_mc2] Use the SPRITE command to set up a multicolor sprite, and use SPRCOLOR to set the additional colors. Note that these colors are common to all multicolor sprites. The color values must be in the range (0-15). Use the RSPCOL0R function to get the current multicolor sprite colors, and RSPRITE to get the current sprite foreground color. SPRDEF -- Define a sprite pattern [*** NOT EXPECTED TO BE IMPLEMENTED ***] SPRITE -- Turn a sprite on or off, and set its characteristics SPRITE number [,[on] [,[color] [,[priority] [,[x_exp] [,[y_exp] [,mode] ]]]]] The SPRITE command allows you set all of the characteristics of a sprite. Use the MOVSPR command to position it or set it in motion. Use the SPRCOLOR to set the multicolor sprite colors, if you are using multicolor sprites. All the parameters except the sprite number are optional. If you don't specify a parameter then it won't be changed. number = sprite number (0-7) on = enable (1) or disable(0) color = sprite foreground color (0-15) priority= sprite to display data priority: 0 means sprite goes over screen data 1 means sprite goes under screen data x,y_exp = sprite expansion on (1) or off (0) mode = sprite mode: 0 high resolution 1 multicolor The SPRITE command does not define a sprite. The sprite definitions must be loaded into the sprite area first ($600-$7FF). Use the BLOAD and BSAVE commands. [*** THIS MAY CHANGE ***] A sprite is 24 pixels wide and 21 pixels high. Each sprite definition requires 63 ($40 hex) bytes: $600 Sprite 0 definition $640 Sprite 1 definition $680 Sprite 2 definition $6C0 Sprite 3 definition $700 Sprite 4 definition $740 Sprite 5 definition $780 Sprite 6 definition $7C0 Sprite 7 definition Use the RSPRITE function to read a sprite's characteristics, or the RSPPOS function to read a sprite's position. The RSPCOLOR function is used to get the current multicolor sprite colors. 10 BLOAD"sprite 1 data", Load sprite 1's definition P(DEC("640")) 20 SPRITE 1, 1, 2 Turn it on, make it red 30 MOVSPR 1, 24, 50 Put it at top-leftmost corner 40 SPRSAV 1, 2 Copy sprite 1 definition to 2 50 SPRITE 2, 1, 7 Turn on sprite 2 make it yellow 60 MOVSPR 2, 320, 229 Put it at bottom-rightmost corner 70 BSAVE"sprite 2 data", Save sprite 2 P(DEC("680")) TO P(DEC("6C0")) 80 SPRITE 1, 0 Turn off sprite 1 90 SPRITE 2, 0 Turn off sprite 2 SPRSAV -- Copy a sprite definition SPRSAV source, destination Use this command to copy a sprite's data (shape) to another sprite or into a string variable, or copy a shape from a string variable into a sprite. You can have many different sprite shapes in memory at one time, all stored in strings. This makes it possible to animate sprites from BASIC by quickly "flipping through" shapes, using each shape like a frame from a movie film. SPRSAV 0, A$ copy the data (shape) of sprite 0 into A$ SPRSAV A$, 2 copy the data (shape) in A$ into sprite 2 SPRSAV 1, 2 copy the data (shape) in sprite 1 to sprite 2 STASH -- (see the DMA command) SQR -- Square root function SQR (number) This function returns the SQuare Root of the given numeric expression. The numeric expression must not be negative or an 'ILLEGAL QUANTITY' error is reported. A = SQR(10) Result is A = 3.16227766 STEP -- See FOR/NEXT/STEP STOP -- Halt program execution When STOP is executed, the computer immediately stops running the program and reports 'BREAK IN LINE xx'. No variables are cleared and files are not closed. This command is usually used while debugging (fixing) a BASIC program, since it lets you stop at a specific place, examine variables, change variables, and restart the program where it was halted (see CONTinue command) or some other line (see GOTO). In many cases, you can even change the program and use GOTO to resume execution with variables and open channels intact. SWAP -- (see the DMA command) STR$ -- Get the string representation of a number STR$ (number) The STRing function returns a string identical to PRINT's output of the given numeric expression. See PRINT for details regarding the format of numeric output. STR$ is the opposite of VAL. A$ = STR$(123) Result is A$ = " 123" A$ = STR$(-123) Result is A$ = "-123" A$ = STR$(.009) Result is A$ = " 9E-03" SYS -- Call a ROM routine or user machine language routine SYS address [,[a] [,[x] [,[y] [,[z] [,s] ]]]] This statement performs a call to a machine language routine at the specified address (range 0-65535, $3000-$FFFF) in a memory bank set up previously by the BANK command. The microprocessor's registers are loaded with the values specified in the parameters following the address (if given) and a JSR (Jump SubRoutine) instruction is performed. When the called routine ends with an RTS (ReTurn from Subroutine), the microprocessor's registers are saved and control is returned to the BASIC program. The microprocessor's registers can be examined with the RREG command. Because this command instructs the computer's microprocessor (CPU) to perform something, extreme care should be taken in its use. It can easily crash the computer if you do something wrong (press the reset button to reboot). Also see the BOOT SYS command. BANK 128: SYS DEC("FF5C") Call the Kernel's PHOENIX routine. BANK 128: SYS DEC("FF81") Reset the Screen Editor 10 BANK 128 20 BLOAD"user routine",P(DEC("1800")) Load a user routine 30 SYS DEC("1800"), areg, xreg Call it with args in A and X 40 RREG areg, xreg, , , sreg Get args back in A, X, and S 50 carry = (sreg AND 1) Get carry flag from S 60 PRINT "ACCUMULATOR = ";HEX$(areg) Display registers 70 PRINT "X REGISTER = ";HEX$(xreg) 80 PRINT "CARRY FLAG = ";carry See the USR function for another way to call machine language routines. TAB -- Space PRINT output TAB (number) The TAB function is used to format PRINTed data to the screen, a printer, or a file. It's primarily for screen text output, moving the cursor to the specified column (plus one) as long as the current print position is not already beyond that point (for example, if the current print position is the first column, TAB(1) would print subsequent text beginning in column 2). If the current print position is already beyond the column specified by the TAB function, nothing is done. For disk and printer output, TAB works exactly like the SPC function (see SPC). A semicolon (';') is always assumed to follow TAB, even if it appears at the end of a print line. PRINT "TEXT";TAB(10);"HERE" Result is 'TEXT HERE' PRINT "TEXT";SPC(10);"HERE" Result is 'TEXT HERE' The above examples illustrate the difference between TAB and SPC. See also the SPC function. A better way to format PRINT output is with PRIUT USING. Don't confuse the TAB function with the TAB character, CHR$(9), which is used to format data using the programmable TAB stops. TAN -- Tangent function TAN (expression) This function returns the tangent of the numeric expression, measured in radians. If the result overflows, TAN(pi/2) for example, an 'OVERFLOW' error is reported. X = TAN(1) Result is X=1.55740772 To get the tangent of an angle measured in degrees, multiply the numeric expression by pi/180. TEMPO -- Set the tempo (speed) of a PLAY string TEMPO rate Use this command to adjust the tempo (speed) of music playback by the PLAY command. The rate determines the duration of a whole note. The default is 12, making a whole in 4/4 time last 2 seconds. The formula is: duration = 24/rate The higher the rate, the faster the note. The range is (1-255). THEN -- See IF/THEN/ELSE TO -- See FOR/NEXT/STEP. Also used as a subcommand. TRAP -- Define an BASIC error handler TRAP [line_number] When turned on, TRAP intercepts all BASIC execution error conditions except 'UNDEF'D STATEMENT ERROR'. Even the STOP key can be TRAPped. When an error occurs, BASIC saves the error's location, line number, and error number. If TRAP is not set, BASIC returns to direct mode and displays the error message and line number. If TRAP is set, BASIC performs a GOTO to the line number specified in the TRAP statement and continues executing. Your BASIC error handling routine can examine the error number, message, and the line number where the error occurred and determine the proper course of action. The system error words are: ER Error Number EL Error Line (line where the error occurred) ERR$() Error Message If ER is -1, then a BASIC error did not occur. The error routine should check the disk status words, in case they were the cause of the error: DS Disk Error Number DS$ Disk Error Message Refer to the list of BASIC and Disk error messages in the appendix. Note that an error in your TRAP routine cannot be trapped. The RESUME statement can be used to resume execution -- see RESUME. TRAP with no line number specified turns off error TRAPping. 10 TRAP 90 enable trapping 20 FOR I=-5 TO 5 30 PRINT 5/I error when I=0 40 NEXT 50 TRAP turn trapping off 60 END 70 : 90 PRINT ERR$(ER): RESUME NEXT error routine TROFF -- Turn off trace mode TRON -- Turn on trace mode TROFF TRON Trace mode is used while debugging (fixing) a BASIC program. TRON enables tracing, and TROFF disables tracing. When the program is run and trace mode is on, the line number of the command that is being executed is displayed on the screen. If there are three commands on the line, the line number will be displayed three times, once each time one of the commands is executed. Trace mode lets you know what the computer is doing. Trace mode works even when a graphic screen is being displayed, but the line number is still displayed on the text screen so you won't be able to see it until the graphic screen is turned off. If your program is doing alot of PRINT statements, the display can seen a little confusing. Trace mode can be set in direct mode to trace the entire program, or it can be turned on and off from within your program to let you trace only selected portions of the program. Trace mode has no effect on commands entered in direct (edit) mode. The NEW command disables trace mode, but RUN and CLR do not. 10 FOR I=-5 TO 5 15 TRON 20 PRINT 5/I 25 TROFF 30 NEXT TYPE -- Display the contents of a sequential disk file TYPE "filename" [,Ddrive] [<,|ON>Udevice] Use this command to print the contents of a PETSCII data file on the screen. The file must contain lines no longer than 255 characters long and terminated by a return character (CHR$(13)). Lines too long result in a 'STRING TOO LONG' error. TYPE "readme" display the contents of the README file on the screen The command sequence below will print the contents of the README file on a CBM serial bus printer in upper/lower case mode. OPEN 4,4,7: CMD4: TYPE"readme": CLOSE4 UNTIL -- See DO/LOOP/WHILE/UNTIL/EXIT USR - Call a user defined machine language function USR (expression) When this function is used, the program jumps to a machine language subroutine whose starting address must be POKEd into system memory (BANK 128) at address 760 (low byte) and 761 (high byte), or $2F8 hex. The floating point value of the numeric expression is passed to the routine in the Floating point ACCumulator (FACC), and the value to be returned is taken from the FACC when the routine ends. If the USR vector is not set up prior to making the USR call, an 'UNDEF'D FUNCTION' error is reported. The routine must be located in the system bank. The BANK command does not affect USR. Using this method of calling a machine language routine requires a fair amount of set up and a good knowledge of the lower level math routines built into BASIC. See the SYS command, which is more commonly used to call a machine language routine. The following program illustrates the basic steps required for installing a USR routine and calling it: 10 BANK 128 System bank for poke & load 20 UV = DEC("1800") Where my routine is 30 BLOAD "my user routines",P(UV) Load my routine 40 POKE DEC("2F8"), UV AND 255, UV / 256 Set up USR address 50 x = USR(123): PRINT X Call my routine with the the value 123, get back and print whatever my routine leaves in FACC The following program actually works. It points the USR vector to the BASIC math jump table entry for the routine which inverts the sign of the number in the FACC. Type in positive & negative numbers: 10 BANK 128 System bank for poke 20 POKE DEC("2F8"), DEC("33"), DEC("7F") Set up USR address 30 DO: INPUT"SIGNED NUMBER"; N Get number input 40 : PRINT USR(N) Display USR output 50 : LOOP UNTIL N=0 End if user types zero USING -- See PRINT USING VAL -- Get the numerical value of a string VAL (string) The VALue function converts a string into a number. The conversion starts with the first character and ends at the end of the string or the first character that is not allowed in normal number input. Spaces are ignored. If the first character of the string is not a legal character, a zero is returned. The VAL function works the same way the INPUT and READ commands do. VAL is the opposite of STR$. X = VAL(" 123") Result is X = 123 X = VAL("-123") Result is X = -123 X = VAL(" 9E-02") Result is X = .09 VERIFY -- Compare a program or data in memory with a disk file VERIFY "filename" [,device_number [,relocate_flag]] This command is just like a LOAD command, except instead of putting the data read from a file into memory, the computer compares it to what is already in memory. If there's any difference at all a 'VERIFY ERROR' is reported. The filename must be given, and pattern matching may be used. In the case of dual drive systems, the drive number must be part of the filename. If a device number is given, the file is sought on that unit, which must be a disk drive. If a device number is not given, the default system drive is used. See also DVERIFY. Note: If the BASIC program in memory is not located at the same address as the version on disk was SAVEd from, the files will not match even if the program is otherwise identical. The relocate_flag is used to VERIFY binary files. If the relocate_flag is present and non-zero, the file will be compared to memory starting at the address stored on disk when the file was SAVEd. The memory bank used is the bank given in the last BANK statement. The ending address is determined by the length of the disk file. The comparison halts on the first mismatch or at the end of the file. The area to be compared must be confined to the indicated memory bank. Do not use the relocate_flag to verify BASIC programs. See also BVERIFY. VERIFY "myprogram" Good: SEARCHING FOR 0:myprogram Bad: SEARCHING FOR 0:myprogram VERIFYING VERIFYING OK ?VERIFY ERROR VERIFY "PROG" Compares BASIC program in memory to file PROG on the default system disk. VERIFY FILE$,DRV Compares program in memory to a program whose name is in the variable FILE$ on the unit whose number is in DRV. VERIFY "0:PROG",8 Compares memory to BASIC program PROG on unit 8, drive 0. BANK 128 Compares a binary file into memory. The VERIFY "BIN",8,1 address used comes from the disk file, but you must specify the memory bank. VIEWPORT -- [*** CURRENTLY UNIMPLEMENTED ***] VOL -- Set audio volume level VOL volume [*** THIS COMMAND WILL CHANGE ***] This statement sets the volume level for SOUND and PLAY statements. VOLUME can be set from 0 to 15, where 15 is the maximum volume. A volume of 0 turns sound output off. VOLume affects all 3 voices. Note that PLAY strings can change the volume, too. WAIT -- Pause BASIC program until a memory state satisfied WAIT address, and_mask [,xor_mask] The WAIT statement causes program execution to be suspended until data at a specified memory location matches a given bit pattern. It's used to pause your program until an event occurs. The event could be an I/O state (such as a fire button or peripheral port change), a hardware state (such as the raster position or RS232 status), or memory change caused by an interrupt event (such as a keyboard scan). The WAIT statement tells the computer to read (PEEK) a memory location (0-65535) and AND the value it got with the number in and_mask (0-255). If the result is zero, repeat the operation until the result is not zero. This is like the following BASIC instructions, but much faster: DO: result = PEEK(address): LOOP UNTIL (result AND and_mask) <> 0 This works if the state you are WAITing for is non-zero (a one or "high" state). If you want to wait for a zero state (a "low" state), you need to use the xor_mask option to "flip" the bits of the result. Note that it's possible to "hang" your program indefinitely if the state you are waiting for never happens or you specify the wrong data. Press the STOP and RESTORE keys at the same time to get control back. Be sure to use the BANK command before you tell the computer to WAIT to specify which 64K memory bank the address is in. Note that a BANK number greater than 127 (i.e., a bank number with the most significant bit set) must be used to address an I/O location, such as the VIC chip. Refer to the system memory map for details. 10 BANK 128 Wait for the VIC raster to be 20 WAIT DEC("D011"), 128 offscreen (want RC8 = 1) 10 BANK 128 Wait for the VIC raster to be 20 WAIT DEC("D011"), 128, 128 onscreen (want RC8 = 0) 10 BANK 128 20 WAIT DEC("D3"), 1 Wait for user to press key 30 WAIT DEC("D3"), 2 Wait for user to press key 40 WAIT DEC("D3"), 4 Wait for user to press key 50 WAIT DEC("D3"), 8 Wait for user to press key WHILE -- See DO/LOOP/WHILE/UNTIL/EXIT WIDTH -- [*** CURRENTLY UNIMPLEMENTED ***] WINDOW -- Set a text window WINDOW left_column, top_row, right_column, bottom_row [,clear] This command defines a logical text screen window. All text I/O will be confined to this window. The row parameters must be in the range (0-24), and the column parameters must be in the range (0-79) for 80-column screens or (0-39) for 40-column screens. The parameters are always referenced to the physical screen (i.e., you cannot define a window within a window). If the clear flag is given, the new window area will be cleared after it's set up. Use the RWINDOW function to get the current window size. You are responsible for saving and restoring screen data in all windows because the WINDOW command simply sets the window margins. The WINDOW command does not draw a border around a window. All color commands and screen modes (such as scroll disable, TAB stops, etc.) are global. Two consecutive "home" characters will reset the window definition back to the physical screen. WINDOW 0,0,39,24 Define a window in 80-column mode that is the left half of the screen. WINDOW 40,0,79,24 Define a window in 80-column mode that is the right half of the screen. WINDOW 0,0,79,12 Define a window in 80-column mode that is the top half of the screen. WINDOW 0,13,79,24 Define a window in 80-column mode that is the bottom half of the screen. WINDOW 20,6,59,12,1 Define a window in 80-column mode in the center of the screen and clear it. The window is 12 characters high and 40 characters wide. PRINT CHR$(19)CHR$(19); Reset the window back to full screen in either 40 or 80-column mode and put the cursor in top left corner. XOR -- Exclusive-Or function XOR (number,number) The XOR function returns a numeric value equal to the logical XOR of two numeric expressions, operating on the binary value of the unsigned 16-bit integers in the range (0 to 65535). Numbers outside this range result in an 'ILLEGAL QUANTITY' error. X = XOR(4,12) Result is X= 8 X = XOR(2,12) Result is X=14 3.1.4. VARIABLES The C64DX uses three types of variables in BASIC: floating point X integer X% string X$ Normal NUMERIC VARIABLES, also called floating point variables, can have any from up to nine digits of accuracy. When a number becomes larger than nine digits can show, as in +10 or -10, the computer displays it in scientific notation form, with the number normalized to 1 digit and eight decimal places, followed by the letter E and the power of ten by which the number is multiplied. For example, the number 12345678901 is displayed as 1.23456789E+10. INTEGER VARIABLES can be used when the number is a signed whole number from +32767 to -32768. Integer data is a number like 5, 10, or -100. Integers take up less space than floating point variables, particularly when used in an array. STRING VARIABLES are those used for character data, which may contain numbers, letters, and any other character that the computer can make. An example of string data is "Commodore C64DX". VARIABLE NAMES may consist of a single letter, a letter followed by a number, or two letters. Variable names may be longer than 2 characters, but only the first two are significant. An integer is specified by using the percent (%) sign after the variable name. String variables have a dollar sign ($) after their names. EXAMPLES: Numeric Variable Names: A, A5 , BZ Integer Variable Names: A%, A5%, BZ% String Variable Names : A$, A5$, BZ$ ARRAYS are lists of variables with the same name, using an extra number (or numbers) to specify an element of the array. Arrays are defined using the DIM statement, and may be floating point, integer, or string variable arrays. The array variable name is followed by a set of parentheses () enclosing the number of the variable in the list. EXAMPLE: A(7), BZ%(11), A$(87) Arrays can have more than one dimension. A two dimensional array may be viewed as having rows and columns, with the first number identifying the row and the second number identifying the column (as if specifying a certain grid on the map). EXAMPLE: A(7,2), BZ%(2,3,4), Z$(3,2) RESERVED VARIABLE NAMES are names that are reserved for use by the computer, and may not be used for another purpose. These are the variables DS, DS$, ER, ERR$, EL, ST, TI, and TI$. KEYWORDS such as TO and IF or any other names that contain KEYWORDS, such as RUN, NEW, or LOAD cannot be used. ST is a status variable for input and output (except normal screen/keyboard operations). The value of ST depends on the results of the last I/O operation. In general, if the value of ST is 0 then the operation was successful. TI and TI$ are variables that relate to the real-time clock built into the C64DX. The system clock is reset to zero when the system is powered up or reset, and can be changed by the user or a program. TI$="hh:mm:ss.t" Allows optional colons to delimit parameters and allows input to be abbrieviated (eg., TI$="h:mm" or even TI$=""), defaulting to "00" for unspecified parameters. 24-hour clock (00:00:00.0 to 23:59:59.9). TI 24-hour TOD converted into tenths of seconds. The value of the clock is lost when the computer is turned off. It starts at zero when the computer is turned on, and is reset to zero when the value of the clock exceeds 23:59:59.9. The variable DS reads the disk drive command channel, and returns the current status of the drive. To get this information in words, PRINT DS$. These status variables are used after a disk operation, like DLOAD or DSAVE, to find out why the error light on the disk drive is blinking. ER, EL, and ERR$ are variables used in error trapping routines. They are usually only useful within a program. ER returns the last error encountered since the program was RUN. EL is the line where the error occurred. ERR$ is a function that allows the program to print one of the BASIC error messages. PRINT ERR$(ER) prints out the proper error message. 3.1.5. OPERATORS The BASIC OPERATORS include ARITHMETIC, RELATIONAL, and LOGICAL OPERATORS. The ARITHMETIC operators include the following signs: + addition - subtraction * multiplication / division ^ raising to a power (exponentiation) On a line containing more than one operator, there is a set order in which operations always occur. If several operators are used together, the computer assigns priorities as follows. First exponentiation, then multiplication and division, and last, addition and subtraction. If two operators have the same priority, then calculations are performed in order from left to right. If these operations are to occur in a different order, BASIC 10.0 allows giving a calculation a higher priority by placing parentheses around it. Operations enclosed in parentheses will be calculated before any other operation. Make sure that the equations have the same number of left and right parentheses, or a SYNTAX ERROR message is posted when the program is run. There are also operators for equalities and inequalities, called RELATIONAL operators. Arithmetic operators always take priority over relational operators. = is equal to < is less than > is greater than <= or =< is less than or equal to >= or => is greater than or equal to <> or >< is not equal to Finally, there are three LOGICAL operators, with lower priority than both arithmetic and relational operators: AND OR NOT These are most often used to join multiple formulas in IF...THEN statements. When they are used with arithmetic operators, they are evaluated last (i.e., after + and -). If the relationship stated in the expression is the true the result is assigned an integer of -1 and if false an integer of 0 is assigned. There is also an XOR function. EXAMPLES: IF A=B AND C=D THEN 100 requires both A=B & C=D to be true IF A=B OR C=D THEN 100 allows either A=B or C=D to be true A=5:B=4:PRINT A=B displays 0 A=5:B=4:PRINT A>3 displays -1 PRINT 123 AND 15:PRINT 5 OR 7 displays 11 and 7