Basic Commands and Statements - continued

17.63 PAINT

Fill area with color.

PAINT [color source], x, y [,mode]

The PAINT command fills an area with color, the area is defined by a fully enclosed shape around, but not including the x,y coordinates specified. Points where the color source is the same as the source of the pixel are not PAINTed. (See example 3.)

If mode=0 the area filled must be bounded by the color source, any other color sources which lie within this boundery are overPAINTed. (See example 1.)

If mode=1 the boundery of the area is any color source (except 0). No color sources will be overPAINTed; i.e. only non-PAINTed areas can be filled when mode=1. (See example 2.)

17.63.1 EXAMPLE 1:

10 COLOR 0,1:COLOR 1,2:COLOR 2,5:COLOR 3,7
20 GRAPHIC 3,1	multicolor graphics
30 CIRCLE 1,80,100,30	draw circle in color source 1
40 CIRCLE 3,80,100,35	draw circle in color source 3
50 BOX 2,80,100,90,110,45,1	draw filled box in color source 2
60 PAINT 3,70,100,0	paint inner circle in color source 3 bounded only by color source 3

17.63.2 EXAMPLE 2:

As example 1, but change line 60 to:

60 PAINT 3,70,100,1

paint inner circle bounded by non-background color source

17.63.3 EXAMPLE 3:

As example 2, but add lines 70 and 80:

70 COLOR 2,8	change color source to yellow
80 PAINT 2,90,110,1	attempt to repaint the box fails, because color source in PAINT and at (90,100) are the same (2).

17.64 PLAY

Define and play musical notes and elements.

PLAY "[Vn] [On] [Tn] [Un] [Xn] [elements] [...]"

The PLAY statement gives you the power to select voice, octave and tune envelope (including ten predefined musical instrument envelopes), the volume and the notes you want to PLAY. All these controls are enclosed in quotes.

All elements except R and M precede the musical notes in a PLAY string.

NOTE: * These must precede each musical note.

EXAMPLES:

PLAY "V1O4T0U5X0CDEFGAB"

PLAY "V3O5T6U7X1#B$AW.CHDQEIF"

NOTE: You will need to set up a filter before you can hear anything with this example - try FILTER 1024,1.

17.65 POKE

Change the contents of a RAM memory location.

POKE address, value

The POKE statement allows changing of any value in the Commodore 128 RAM, and allows modification of many of the Commodore 128 Input/Output registers. The keyword POKE is always followed by two parameters. The first is a location inside the Commodore 128 memory, this can be a value from 0 to 65535. The second parameter is a value from 0 to 255, which is placed in the location, replacing any value that was there previously. The value of the memory location determines the bit pattern of the memory location. In C128 mode the POKE occurs into the current selected RAM bank. The POKE address depends on the BANK number. See BANK, in paragraph 17.4 of this Encyclopaedia for the appropriate BANK configurations.

EXAMPLE:

10 POKE 53280,1

NOTE: PEEK, a function related to POKE, which returns the contents of the specified memory location is listed under BASIC Functions.

17.66 PRINT

Output to text screen

PRINT print list

The PRINT statement is the major output statement in BASIC. While the PRINT statement is the first BASIC statement most people learn to use, there are many variations of this statement. The word PRINT can be followed by any of the following:

Characters inside of quotes	("text" lines)
Variable names	(A, B, A$, X$)
Functions	(SIN(23), ABS(33))
Punctuation marks	(; ,)

The characters inside quotes are often called literals because they are printed literally, exactly as they appear. Variable names have the value they contain (either a number or a string) printed. Functions also have their number values printed.

Punctuation marks are used to help format the data neatly on the screen. The comma tabs to the nearest tenth column, while the semicolon prints items next to each other. Either punctuation mark can be used as the last symbol in the statement. This results in the next PRINT statement acting as if it is continuing the previous PRINT statement. PRINT on its own moves to the start of the next line - leaving a blank line.

EXAMPLES:                           RESULTS

10 PRINT "HELLO"                    HELLO

20 A$=" THERE":PRINT "HELLO";A$     HELLO THERE

30 A=4:B=2:PRINT A+B                 6

40 J=41:PRINT J;:PRINT J-1           41  40

50 PRINT A;B;:D=A+B:PRINTD;A-B       4  2  6  2

See also POS, SPC and TAB Functions, in Section 18, paragraphs 18.24, 18.37, and 18.40, respectively.

17.67 PRINT#

Output data to files.

PRINT# file number, print list

There are a few differences between this statement and the PRINT. Most importantly, the word PRINT# is followed by a number, which refers to the data file previously OPENed. The number is followed by a comma and a list of items to be output to the file. The semicolon acts in the same manner for spacing in printers as it does in the PRINT statement, commas output 10 spaces. Some devices may not work with TAB and SPC.

EXAMPLES:

10 OPEN 4,4
20 PRINT#4,"HELLO THERE!",A$,B$

10 OPEN 2,8,2,"DATAFILES,S,W"
20 PRINT#2,A,B$,C,D

NOTE: The PRINT# command is used by itself to clear the channel to a device after outputting via CMD and before closing the file as follows:

OPEN 4,4
CMD 4
LIST
PRINT#4
CLOSE 4

See also the CMD command, in paragraph 17.15.

17.68 PRINT USING

Output using format

PRINT[#filenumber,] USING "format list"; print list

This statement defines the format of string and numeric items for printing to the text screen, printer or other device. The format is put in quotes. This is the format list. Then add a semicolon and a list of what is to be printed in the format for the print list. The list can be variables or the actual values to be printed, separated by commas.

FORMAT STRING USED WITH
CHARACTER               NUMERIC  STRING
Hash sign (#)           X        X
Plus sign (+)           X
Minus sign (-)          X
Decimal point (.)       X
Comma (,)               X
Dollar sign ($)         X
Four Carets (^^^^)      X
Equal sign (=)                   X
Greater than sign (>)            X

The hash sign {#} reserves room for a single character in the output field. With Numeric Data if the data item contains more characters than there are # signs in the format field, the entire field is filled with asterisks {*}; no characters are printed.

EXAMPLE:

10 PRINT USING "####";X

X = 12.34                  12

X = 567.89                 568

X = 123456                 ****

For a STRING item, the string data is truncated at the bounds of the field. Only as many characters are printed as there are hash signs in the format item. Truncation occurs on the right.

The plus (+) and minus (-) signs can be used in either the first or the last position of the format field, but not both. The plus sign is printed if the number is positive. The minus sign is printed if the number is 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 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. No sign is printed if the number is positive. This means that one additional character, the minus sign, is printed if the number is negative. If there are too many characters to fit into the field specified by the hash signs and plus/minus sign, then an overflow 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 value is rounded to the nearest integer and printed without decimal places.

When a decimal point is specified, the number of digits preceding the decimal point (including the minus sign, if the value is negative) must not exceed the number of hash signs before the decimal point. If there are too many digits, an overflow occurs and the field is filled with asterisks {*}.

A comma {,} allows placing of commas in numeric fields. The position of the comma in the format list indicates where the commas appear in a printed number. Only commas within a number are printed. Unused commas to the left of the first digit appear as filler character. At least one hash sign must precede the first comma in the field.

If commas are specified in a field and the number is negative, then a minus sign is printed as the first character, even if the character position is specified as a comma.

A dollar sign ($) symbol shows that a dollar sign will be printed in the number. If the dollar sign is to float (always be placed before the number), at least one hash sign must be specified before the dollar sign. If a dollar sign is specified without a leading hash sign, the dollar sign is printed in the position shown in the format field. If a plus or minus sign are specified in a format field with a dollar sign, the program prints the sign before the dollar sign.

EXAMPLES:

Field  Expression  Result Comment

##.#   -.1         -0.1   Leading zero added.

##.#   1           1.0    Trailing zero added.

####   -100.5      -101   Rounded to no decimal places.

####   -1000       ****   Overflow because four digits and a minus
                          sign cannot fit in field.

###.   10          10.    Decimal point added.

#$##   1           $1     Leading dollar sign.

The up arrows or caret symbols {^^^^} are used to specify that the number is to be printed in the E format (scientific notation). A hash sign must be used in addition to the four carets to specify the field width. The carets must appear after the hash sign in the format field. Four carets must be specified when a number is to be printed in E format. If fewer than four carets are specified, a syntax error results. If more than four carets are specified, only the first four are used. The fifth and subsequent carets are interpreted as text symbols. You can specify a {+} or {-} sign after the carets if you require a trailing sign. An equal {=} sign is used to centre a string in a field. The field width is specified by the number of characters (the hash signs and an equal sign) in the format field. If the string contains fewer characters than the field width, the string is centered in the field. If the string contains more characters than can be fitted into the field, then the rightmost characters are truncated and the string fills the entire field. A greater than {>} sign is used to right justify a string in a field. Other characters can be included in a format string, these are treated as literals. This allows you to build up tables and charts. See line 30 in the program below for a specific example of this.

EXAMPLE:

5 X=32: Y=100.23: A$="CAT": B$="COMPUTER"
6 F$=* #=########## * #$##.## *+CHR$(13)
10 PRINT USING "$##.##";13.25,X,Y
20 PRINT USING "###>#";"CBM",A$
30 PRINT USING F$;A$,X,B$,Y

When this program is RUN, line 10 prints:

 $13.25 $32.00 $*****

Line 20 prints this:

  CBM  CAT

Line 30 prints this:

*      CAT     *  $23.00 *
*   COMPUTER   * $100.23 *

17.69 PUDEF

Redefine symbols in PRINT USING statements.

PUDEF "nnnn"

Where "nnnn" is any combination of characters, up to four in all, PUDEF allows you to redefine any of the following four symbols in the PRINT USING statement: blanks, commas, decimal points and dollar signs. These four symbols can be changed into some other character by placing the new character in the correct position in the PUDEF control string.

Position 1 is the filler character. The default is a blank. Place a new character here for another character to appear in place of blanks.

Position 2 is the comma character. Default is a comma.

Position 3 is the decimal point. Default is a decimal point.

Position 4 is the dollar sign. Default is a dollar sign.

EXAMPLE:

10 PUDEF"*"

20 PUDEF" <"

NOTE: All positions up to the one(s) to be changed must be specified.

For example PUDEF " $" would print the $ in place of the dollar sign, but the decimal point, comma and filler character would all be set to space.

PUDEF only affects numeric formats i.e. PUDEF "0" will change filler spaces in numbers to leading 0s, but will not affect filler spaces in strings.

The character to replace the $ has no effect unless the $ in the format string of PRINT USING is preceded by a # (i.e. is floating).

17.70 READ

Read data from DATA statements and input it into the computer's memory (while the program is RUNning)

READ variable list

This statement takes information from DATA statements and stores them in variables, where the data can be used by the RUNning program. The READ statement variable list may contain both strings and numbers. Be careful to avoid reading strings where the READ statement expects a number, this produces a TYPE MISMATCH ERROR message.

The data in the DATA statements are READ in sequential order. Each READ statement can read one or more data items. Every variable in the READ statement requires a DATA item. If one is not supplied, an OUT OF DATA ERROR occurs.

In a program, you can READ the data and the reREAD by issuing the RESTORE statement. The RESTORE statement sets the sequential data pointer back to the beginning, where the data can be READ again. See the RESTORE statement, in paragraph 17.75.

EXAMPLES:

10 READ A, B, C
20 DATA 3, 4, 5

10 READ A$, B$, C$
20 DATA JOHN, PAUL, GEORGE

10 READ A, B$, C
20 DATA 1200, NANCY, 345

17.71 RECORD

Position relative file pointers.

RECORD#logical file number, record number [,byte]

This statement positions a relative file pointer to select any byte (character) of any record in the relative file. The logical file number can be in the range between 1 and 255. The record number can be in the range 1 through 65535. Byte number is in the range 1 through 254. See your disk drive manual for details about relative files.

When the record number value is set higher than the last record number in the file, the following occurs:

• For a write (PRINT#) operation, additional records are created to expand the file to the desired record number.
• For a read (INPUT# or GET#) operation, a null record is returned and a RECORD NOT PRESENT error occurs.

EXAMPLE:

10 DOPEN #2,"CUSTOMER"
20 RECORD#2,10,1
30 PRINT#2,A$
40 DCLOSE #2

The RECORD command accepts variables for its parameters. It is often convenient to place the RECORD command within a FOR... NEXT or DO loop. Also see DOPEN, in paragraph 17.31.

17.72 REM

Comment or remark about the operation of a program line.

REM [message]

The REMark statement is a note to whoever is reading a listing of the program. REM may explain a section of the program, give information about the author, etc. REM statements do not affect the operation of the program, except to add length to it (and therefore use more memory). Nothing to the right of the keyword REM is interpreted by the computer as an executable instruction. Therefore, no other executable statement can follow a REM on the same line.

EXAMPLE:

1010 NEXT X: REM END OF MAIN PROGRAM LOOP

17.73 RENAME

Change the name of a file on disk.

RENAME [Ddrive number,] "old filename" TO "new filename"
[<ON | ,>Udevice number]

This command is used to rename a file on disk, from the old filename to the new filename. The diskdrive does not RENAME a file if it is OPEN.

EXAMPLES:

RENAME D0, "TEST" TO "FINAL TEST"

RENAME D0,(A$) TO (B$),U9

17.74 RENUMBER

Renumber lines of a BASIC program.

RENUMBER [new starting line number] [,increment]
[,old starting line number]

The new starting line is the number of the first line in the program after renumbering; the default is 10. The increment is the interval between line numbers (i.e. 10, 20, 30, etc.); the increment default value is also 10. The old starting line number is the first line number before you renumber the program. The default in this case is the first line of the program. This command can only be executed from direct mode.

An UNRESOLVED REFERENCE error occurs if any reference to number that does not exist is encountered. An OUT OF MEMORY occurs if RENUMBERing expands the program beyond its limits. A LINE NUMBER TOO LARGE error occurs if RENUMBER generates a line number of 64000 or higher. These errors leave the program unharmed.

EXAMPLES:

RENUMBER

RENUMBER 20,20,15

RENUMBER,,65

ALWAYS SAVE YOUR PROGRAM BEFORE RENUMBERING, because very long programs can cause a SYSTEM crash when RENUMBERed with larger line numbers.

Also note that long programs should be RENUMBERed in FAST mode as they will take a long time to renumber (up to 30 minutes for a 55K program in FAST).

If you only have a 40 column display use FAST:RENUMBER... {return}. Then type SLOW {return}. While RENUMBERing is taking place you will not see anything happening. When RENUMBERing has finished, you display will return.

If you have an 80 column display or 40/80 column display select the 80 column screen before typing FAST.

17.75 RESTORE/RESTORE

Reset READ pointer to DATA statement so the DATA can be reREAD.

RESTORE	(C64 mode)
RESTORE [line #]	(C128 mode)

When executed in a program, the pointer to the item in a DATA statement that is to be READ next is reset to the first item in the DATA statement. This provides the capability to reREAD the data. If a line number follows the RESTORE statement the READ pointer is set to the first data item after the specified program line. Otherwise the pointer is reset to the beginning of the BASIC program. In C64 mode there is no option to specify the line number, i.e. you can only RESTORE to the beginning of the program.

EXAMPLES:

10 FOR I=1 TO 3
20 READ X
30 T = X + T
40 NEXT
45 PRINT T
50 RESTORE
69 GOTO 10
70 DATA 10,20,30

10 READ A,B,C
20 DATA 100,500,750
30 READ X,Y,Z
40 DATA 36,24,38
50 RESTORE 40
60 READ S,P,Q
70 PRINT A,B,C
80 PRINT X,Y,Z
90 PRINT S,P,Q

NOTE: If a line number is specified the line must exist! A variable can be used e.g. RESTORE LR.

17.76 RESUME

Define where the program will continue (RESUME) after an error has been trapped.

RESUME [line # | NEXT]

This statement is used to restart program execution after TRAPping an error. With no parameters, RESUME attempts to re-execute the line in which the error occurred. RESUME NEXT resumes execution at the statement immediately following the one containing the error; RESUME followed by a line number will GOTO the specific line and resumes execution from that line number. RESUME can only be used in program mode.

EXAMPLE:

10 TRAP 100
20 INPUT "ENTER A NUMBER";A
30 B=100/A
40 PRINT"THE RESULT=",B:PRINT"THE END"
50 PRINT"DO YOU WANT TO RUN IT AGAIN(Y/N)":GETKEYZ$:IF Z$="Y"THEN 20
60 STOP
100 INPUT"ENTER ANOTHER NUMBER (NOT ZERO)";A
110 RESUME

17.77 RETURN

Return from subroutine.

RETURN

This statement is always paired with the GOSUB statement. When a program encounters a RETURN statement, it goes to the statement immediately following the last GOSUB command executed. If no GOSUB was previously issued, the a RETURN WITHOUT GOSUB error message is displayed and the program stops. All subroutines end with a RETURN statement.

EXAMPLE:

10 PRINT "ENTER SUBROUTINE"
20 GOSUB 100
30 PRINT "END OF SUBROUTINE"
.
.
.
90 STOP
100 PRINT "SUBROUTINE 1"
110 RETURN

17.78 RREG

Read the contents of the accumulator AC, X register XR, Y register YR and Status register SR.

RREG [var1] [, [var2] [, [var3] [, [var4] ] ] ]

After a SYS command is issued, the contents of the CPU registers AC, XR, YR and SR are stored in memory before the C128 returns to BASIC. The memory locations of these stores are:

• AC -> 6
• XR -> 7
• YR -> 8
• SR -> 5

With the RREG command the values in these memory stores are loaded into the specified variables. The values range between zero and 255 (inclusive).

Not all variables have to be specified. For instance, it is possible to only read the contents of YR:

RREG , ,YR : PRINT YR

EXAMPLE:

100 FOR I=4864 TO 4870
110 READ D : POKE I,D
120 NEXT I
130 DATA 169,6,162,7,160,8,96
131 REM ML PRG
132 REM
133 REM 01300 LDA #6 ; LOAD AC WITH VALUE 6
134 REM 01302 LDX #7 ; LOAD XR WITH VALUE 7
135 REM 01304 LDY #8 ; LOAD YR WITH VALUE 8
136 REM 01306 RTS ; END ML SUBROUTINE
140 SYS 4864
150 RREG AC, XR, YR
160 PRINT "AC=";AC, "XR=";XR, "YR=";YR
170 M6 = PEEK(6) : REM MEMORY LOCATION 6
180 M7 = PEEK(7) : REM MEMORY LOCATION 7
190 M8 = PEEK(8) : REM MEMORY LOCATION 8
200 PRINT "MEMORY LOCATIONS 6, 7 AND 8:"; M6;","M7;","M8

Line 160 prints this:

AC= 6    XR= 7    YR= 8

Line 200 prints this:

MEMORY LOCATIONS 6, 7 AND 8: 6 , 7 , 8

17.79 RUN/RUN

Execute BASIC program.

RUN [line #]
RUN "filename" [,Ddrive number] [<ON | ,>Udevice number]	(BASIC 7.0 only)

Once a program has been typed into memory or LOADed, the RUN command executes it. RUN clears all variables in the program before starting program execution. If there is a number following the RUN command, execution starts at that line number. If there is a filename following the RUN command, the named file is loaded from the disk drive and RUN, with no further action required by the user. RUN may be used within a program. The default drive number is 0 and default device number is 8.

EXAMPLES:

RUN

RUN 100

RUN"PRG1"

RUN(A$)