SECTION 17

17. Basic Commands and Statements

17.1 APPEND

Append new data to the end of a sequential file.

APPEND #logical file number, "filename" [,Ddrive number]
[<ON | ,> Udevice]

This command opens the file having the specified filename, and positions the pointer at the end of the file. Subsequent PRINT# (write) statements will cause data to be appended to the end of this file. Default values for drive number and device number are 0 and 8 respectively.

Variables or Expressions used as filenames must be enclosed within parentheses.

EXAMPLES:

APPEND#8,"MYFILE"

APPEND#7,(A$),D0,U9

17.2 AUTO

Enable/disable automatic line numbering.

AUTO [line#]

This command turns on the automatic line-numbering feature. This eases the job of entering programs, by automatically typing the line numbers for the user. As each program line is entered by pressing {return}, the next line number is printed on the screen, and the cursor is positioned on the second space to the right of the line number. The line number argument refers to the desired increment between line numbers. AUTO without an argument turns off the auto line numbering, as does RUN. This statement can be used only in direct mode (outside of a program).

EXAMPLES:

AUTO 10

AUTO 50

AUTO

17.3 BACKUP

Copy the entire contents from one disk to another on a dual disk drive.

BACKUP source Ddrive number TO destination Ddrive number
[<ON | ,>Udevice]

This command copies all the data from the source diskette onto the destination diskette using a dual diskdrive. With the BACKUP command, a new diskette can be used without first formatting it. This is because the BACKUP command copies all the information on the diskette, including the format. Because of this, the BACKUP command destroys any information already on the destination disk. Therefore, when backing up onto a previously used diskette, make sure it contains no programs you mean to keep. As a precaution the computer asks "ARE YOU SURE?" before it starts the operation. Press the {y} key to perform the BACKUP, or any other key to stop it. You should always create a backup of all your disks, in case the original diskette is lost or damaged. Also see the COPY command, in paragraph 17.21. The default device number is unit 8.

NOTE: This command can be used only with a dual-disk drive. It will not allow you to make copies of protected disks (most prepackaged software).

EXAMPLES:

BACKUP D0 TO D1

BACKUP DO TO D1 ON U9

17.4 BANK

Select one of the 16 banks, numbered 0-15.

BANK bank number

This statement specifies the bank number and corresponding memory configuration for the Commodore 128 memory. The default bank is 15. Here is a table of available BANK configurations in the Commodore 128 memory:

BANK   CONFIGURATION

0      RAM(0) only
1      RAM(1) only
2      RAM(2) only*
3      RAM(3) only*
4      Internal ROM, RAM(0), I/O
5      Internal ROM, RAM(1), I/O
6      Internal ROM, RAM(2), I/O*
7      Internal ROM, RAM(3), I/O*
8      External ROM, RAM(0), I/O
9      External ROM, RAM(1), I/O
10     External ROM, RAM(2), I/O*
11     External ROM, RAM(3), I/O*
12     Kernal and Internal ROM(LOW), RAM(0), I/O
13     Kernal and External ROM(LOW), RAM(0), I/O
14     Kernal and BASIC ROM, RAM(0), Character ROM
15     Kernal and BASIC ROM, RAM(0), I/O

To access a particular bank, type BANK n (n=0-15) and then use PEEK/POKE or SYS. From within the monitor, precede the four-digit hexadecimal number of the address range you are viewing with a hexadecimal digit (0-F).

17.5 BEGIN/BEND

A structure used with IF... THEN ELSE so that you can include several program lines between the start (BEGIN) and end (BEND) of the structure. Here is the format:

IF Condition THEN BEGIN : statement
statement
statement BEND : ELSE BEGIN
statement
statement BEND

EXAMPLE:

10 IF X=1 THEN BEGIN: PRINT "X=1 is True"
20 PRINT "So this part of the statement is performed"
30 PRINT "When X equals 1"
40 BEND: PRINT "End of BEGIN/BEND structure":GOTO 60
50 PRINT "X does not equal 1":PRINT "The statements between
   BEGIN/BEND are skipped"
60 PRINT "Rest of Program"

The same rules are true if the ELSE:BEGIN clause is specified. If the condition is true all statements between ELSE:BEGIN and BEND are performed, including all statements on the same line as BEND. If False, the program resumes with the line immediately following the line containing BEND.

17.6 BLOAD

Load a binary file starting at the specified memory location.

BLOAD "filename" [,Ddrive number] [<ON | ,>Udevice number]
[,Bbank number] [,Pstart address]

filename

the name of your file

bank number

lets you select one of the 16 banks

start address

the memory location where loading begins

A binary file is a file, whether a program or data, that has been SAVEd either within the machine language monitor or by the BSAVE command. The BLOAD command loads the binary file into the location specified by the start address.

EXAMPLES:

BLOAD "SPRITES", B0, P3584

BLOAD "DATA1", D0, U8, B1, P4096

If start address is not specified the file will load at the same address it was saved from.

17.7 BOOT

Load and execute a program which has been saved as a binary file.

BOOT ["filename"] [,Ddrive number] [<ON | ,>Udevice]

The command loads an executable binary file and begins execution at the predefined starting address. The default device number is 8 drive 0.

EXAMPLES:

BOOT

BOOT"GRAPHICS 1", D0, U9

17.8 BOX

Draw a box at specific position on screen.

BOX [color source], x1, y1 [, x2, y2] [,angle] [,paint]

This statement allows the user to draw a rectangle of any size on the screen. Rotation is based on the centre of the rectangle. The pixel cursor (PC) is located at x2, y2 after the BOX statement is executed. The color source number must be zero (0) or one (1) if in standard bit map or a 2 or 3 if in multicolor bit map mode.

Also see the GRAPHIC command, in paragraph 17.47, for selecting the appropriate graphic mode to be used with the BOX color source number.

Also see the LOCATE command, in paragraph 17.28, for information on the pixel cursor.

EXAMPLES:

BOX 1, 10, 10, 60, 60

BOX 1, 10, 10, 60, 45, 1

DRAW , 30, 90, , 45, 1

BOX 1, 20, 20, , ,1

Any parameter can be omitted but you must include a comma in its place, as in the last two examples.

NOTE: x2, y2 count as one parameter so only one extra comma is required. Wrapping occurs if the degree is greater than 360, i.e. 360=0 (450=90).

17.9 BSAVE

Save a binary file from the specified memory locations.

BSAVE "filename" [,Ddrive number] [<ON | ,>Udevice number] [,Bbank number],
Pstart address TO Pend address+1

filename

the name you give the file

drive number

either 0 or 1 on a dual drive (0 is the default)

device number

the number of disk drive unit (default is 8)

bank number

the number of the bank you specify (0-15)

start address

the starting address where the program is SAVEd from

end address+1

the end address of the program plus one, i.e. the end address you specify in BSAVE is one byte higher than the end address of the memory range

This is the same as the SAVE command in the machine language monitor.

EXAMPLES:

BSAVE "SPRITE DATA",B0,P3584 TO P4096

BSAVE "PROGRAM.SCR",D0,U9,B0,P3182 TO P8000

17.10 CATALOG

Displays the disk directory.

CATALOG [Ddrive number] [<ON | , >Udevice number] [,wildcard string]

The CATALOG command displays the directory on the specified drive just as the directory command. See this command, in paragraph 17.28, for more examples (DIRECTORY and CATALOG are completely interchangeable).

EXAMPLE:

CATALOG

17.11 CHAR

Displays characters at the specific position on the screen.

CHAR [color source], x, y [,string] [,rvs]

This is primarily designed to display characters on a bit mapped screen, but it can also be used on a text screen. Here is what the parameters mean:

color source:	0 =	Background color
	1 =	Foreground color
	2 =	Multicolor 1	} Only in Graphics
	3 =	Multicolor 2	} modes 3 and 4
x	Character column (0-79) (wraps around to the next line in 40-column mode).
y	Character row (0-24).
string	String to print.
RVS	Reverse field flag
	0 =	Off
	1 =	On
	(default 0)

Text (alphanumeric strings) can be displayed on any screen at a given location by the CHAR statement. Character data is read from Commodore 128 character ROM area. The user supplies the x and y coordinates of the starting position and the text string to be displayed. Color source and reverse imaging are optional.

The string is continued on the next line if it attempts to print past the right hand edge of the screen. When used in text mode, the string printed by the CHAR command works just like a PRINT string, including cursor and color control. These control functions inside the string do not work when the CHAR command is used to display text in bit map mode. Upper/Lower case controls (CHR$(142) or CHR$(14)) also operate in bit map mode.

Multicolor characters are handled differently from standard characters. The following table shows how to generate the possible combinations.

Note for Lynx Users: Follow [this link] to view a better representation of the next table.

		Reverse Flag
		0(OFF)	1(ON)
Color source 0	Text	1	1
	Background	2	3
Color source 1	Text	1	0
	Background	0	1
Color source 2	Text	2	0
	Background	0	2
Color source 3	Text	3	0
	Background	0	3

EXAMPLE:

10 COLOR 2,3: REM multicolor 1=Red
20 COLOR 3,7: REM multicolor 2=Blue
30 GRAPHIC 3,1
40 CHAR 0,10,10,"TEXT",0
50 CHAR 0,10,11,"TEXT",1

17.12 CIRCLE

Draws circles, ellipses, arcs, etc. at specific positions on the screen.

CIRCLE [color source],x,y,xr [,yr] [,sa] [,ea] [,angle] [,inc]

With the CIRCLE statement, the user can draw a circle, ellipse, arc, triangle, octagon, or other polygon. The final pixel cursor (PC) is left at the circumference of the circle at the ending arc angle. Any rotation is relative to the centre. Arcs are drawn from the starting angle clockwise to the ending angle. The increment controls the smoothness of the shape; using lower values results in more nearly circular shapes. Specifying the inc greater than 2 creates a rough-edged boxed-in shape.

Also see the LOCATE command, in paragraph 17.28, for information on the pixel cursor.

EXAMPLES:

CIRCLE 1,160,100,65,10

CIRCLE 1,160,100,65

CIRCLE 1,60,40,20,18,,,,45

CIRCLE 1,260,40,20,30,,,,90

CIRCLE 1,60,140,20,18,,,,120

You may omit a parameter, but you must still place a comma in the appropriate position. Omitting parameters take on the default values.

17.13 CLOSE

Close logical file.

CLOSE file number

This statement closes any files used by DOPEN or OPEN statements. The number following the word CLOSE is the file number to be closed.

EXAMPLE:

CLOSE 2

17.14 CLR

Clear program variables.

CLR

This statement erases any variables in memory, but leaves the program intact. This statement is automatically executed when a RUN or NEW command is given.

17.15 CMD

Redirect screen output.

CMD logical file number [,write list]

This command sends the output, which normally goes to the screen (i.e. PRINT statements, LIST, but not POKES into the screen) to another device, such as a disk data file or printer. This device or file must be OPENed first. The CMD command must be followed by a number or numeric variable referring to the file or device. The write list can be any alphanumeric string or variable. This command is useful for printing at the top of program listings.

EXAMPLES:

OPEN 1,4

CMD 1

LIST

PRINT#1

CLOSE 1

17.16 COLLECT

Free inaccessible disk space.

COLLECT [Ddrive number] [<ON | ,>Udevice]

Use this command to make available any disk space that has been allocated to improperly closed (splat) files, and to delete references to these files from the directory. Splat files are files that appear on the directory with an asterisk next to them. Defaults to device number 8.

EXAMPLE:

COLLECT D0

NOTE: It will also free space allocated for direct access and any boot sector. See your disk drive manual for more information.

17.17 COLLISION

Define handling for sprite collision interrupt.

COLLISION type [, statement]

When the specified situation occurs, BASIC will finish processing the current executing instruction and perform a GOSUB to the line number given. When the subroutine terminates (it must end with a RETURN), BASIC will resume processing where it left off. Interrupt action continues until a COLLISION of the same type without a line number is specified. More than one type of interrupt may be enabled at the same time, but only one interrupt can be handled at a time (i.e. there can be no recursion and no nesting of interrupts). The cause of an interrupt may continue causing interrupts for some time unless the situation is altered or the interrupt is disabled.

To determine which sprites have collided since the last check, use the BUMP function.

EXAMPLES:

COLLISION 1, 5000

COLLISION 1

COLLISION 2,1000

NOTE: Sprites can still collide even if they are set off the screen, but not if they are switched off.

17.18 COLOR

Define colors for each screen area.

COLOR source number, color number

This statement assigns a color to one of the seven color areas:

Source Numbers
Area	Source
0	40-column (VIC) background
1	40-column (VIC) foreground
2	multicolor 1
3	multicolor 2
4	40-column (VIC) border
5	character color (40- or 80-column screen)
6	80-column (VDC) background color

Colors that are usable are in the range 1-16:

Color Code   Color             Color Code   Color

1            Black             9            Orange
2            White             10           Brown
3            Red               11           Light Red
4            Cyan              12           Dark Gray
5            Purple            13           Medium Gray
6            Green             14           Light Green
7            Blue              15           Light Blue
8            Yellow            16           Light Gray

             Color Numbers in 40-Column Format

1            Black             9            Dark Purple
2            White             10           Brown
3            Dark Red          11           Light Red
4            Light Cyan        12           Light Purple
5            Dark Cyan         13           Medium Gray
6            Dark Green        14           Light Green
7            Dark Blue         15           Light Blue
8            Light Yellow      16           Light Gray

              Color Numbers in 80-Column Format

EXAMPLES:

COLOR 0,1

COLOR 5,8

17.19 CONCAT

Concatenates two data files.

CONCAT "file 2" [,Ddrive number] TO "file 1" [,Ddrive number]
[<ON | ,>Udevice]

The CONCAT command attaches file 2 to the end of file 1 and retains the name of file 1. The device number defaults to 8 and the drive number defaults to 0.

EXAMPLES:

CONCAT "FILE B" TO "FILE A"

CONCAT (A$) TO (B$), D1, U9

Whenever a variable is used as a filename as in the last example, the filename variable must be surrounded by parentheses.

NOTE: Keep the filenames short (10 characters) because the command buffer is limited in some disk drives.

17.20 CONT

Continue program execution.

CONT

This command is used to restart a program that has been stopped by either using the {stop} key, a STOP statement, or an END statement. The program resumes execution where it left off. CONT will not resume with the program if lines have been changed or added to the program or if any editing of the program is performed on the screen. If the program stopped due to an error, or if you have caused an error before trying to restart the program, CONT will not work. The error message in this case is CAN'T CONTINUE ERROR.

17.21 COPY

Copy files from one drive to another in a dual disk drive or within a single drive.

COPY <["source filename"] [,Ddrive number]> TO <["destination filename"]
[,Ddrive number]> [<ON | ,>Udevice]

This command copies files from one disk (the source file) to another (the destination file) on a dual-disk drive. It can also create a copy of a file on the same disk within a single drive, but the filename must be different. When copying from one drive to another, the filename may be the same.

The COPY command can also COPY all files from one drive to another on a dual disk drive. In this case the drive numbers are specified and the source and destination filenames are omitted.

The default parameters for the COPY command are device number 8, drive 0.

NOTE: Copying between two single or double drive units cannot be done. See BACKUP, in paragraph 17.3.

EXAMPLES:

COPY "TEST",D0 TO "TEST PROG",D1

COPY "STUFF",D0 TO "STUFF",D1

COPY D0 TO D1

COPY "WORK.PROG" TO "BACKUP"