SECTION 17

ABCDEFGHIKLMNOPRSTVW
[continue/next section][MAIN/Introduction][table of contents]

17. Basic Commands and Statements


TABLE OF CONTENTS
append, auto, backup, bank, begin/bend, bload, boot, box, bsave, catalog, char, circle, close, clr, cmd, collect, collision, color, concat, cont, copy

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"
OPEN logical file 8 called "MYFILE" for appending with subsequent PRINT# statements.

APPEND#7,(A$),D0,U9
OPEN logical file named by the variable A$ on drive 0, device number 9 and prepare to APPEND.

17.2 *AUTO*

Enable/disable automatic line numbering.

AUTO [line#]

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

EXAMPLES:

AUTO 10
Automatically numbers program lines in increments of 10.

AUTO 50
Automatically numbers lines in increments of 50.

AUTO
Turns off automatic line numbering.

17.3 *BACKUP*

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

BACKUP source Ddrive number TO destination Ddrive number
[<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
Copies all data from the disk in drive 0 to the disk in drive 1, in dual disk drive unit 8.

BACKUP DO TO D1 ON U9
Copies all data from drive 0 to drive 1, in disk drive unit 9.

17.4 *BANK*

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

BANK bank number

This statement specifies the bank number and corresponding memory 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
* For use on extended C128s with a larger internal memory eg: 256K. In unxpanded machines there is no RAM in these BANKs and 2 echoes 0 and 3 echoes 1.

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

17.5 *BEGIN/BEND*

A structure used with IF... THEN ELSE so that you can include several 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"
If the Conditional (IF... THEN) statement in line 10 is true, the statements between the keywords BEGIN and BEND are performed, including all the statements on the same line as BEND. If the (IF... THEN) conditional statement in line 10 is False, all statements between the BEGIN and BEND, including the ones on the same program line as BEND are skipped, and the program resumes with the first program line immediately following the line containing BEND. The BEGIN/BEND essentially treats line 10 through 40 as one long line.

The same rules are true if the ELSE:BEGIN clause is specified. If the 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]
where:
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
LOADs the binary file "SPRITES" starting in location 3584 in BANK 0.

BLOAD "DATA1", D0, U8, B1, P4096
LOADs the binary file "DATA1" into location 4096 (BANK 1) from Drive 0, unit 8.

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

17.7 *BOOT*

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

BOOT ["filename"] [,Ddrive number] [<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 an executable program, (CP/M Plus for example). This is a special case and requires setting up a specific sector on the disk.

BOOT"GRAPHICS 1", D0, U9
BOOTs the program "GRAPHICS 1" from unit 9, drive 0 and executes it. Execution begins at the start address of the program (i.e. where it starts loading).

17.8 *BOX*

Draw a box at specific position on screen.

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

color source:

0 = Background color
1 = Foreground color
2 = Multicolor 1 } Only in Graphics
3 = Multicolor 2 } modes 3 and 4

x1, y1

Top left corner coordinate (scaled).

x2, y2

Bottom right corner opposite x1, y1 (scaled); default is the PC location.

angle

Rotation in clockwise degrees; default is zero degrees.

paint

Paint shape with color
0 = Do not paint
1 = Paint
(default 0)

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

Also see the GRAPHIC command, in paragraph 17.47, for selecting the 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
Draws the outline of a rectangle.

BOX 1, 10, 10, 60, 45, 1
Draws a painted, rotated box (a diamond).

DRAW , 30, 90, , 45, 1
Draws a filled, rotated polygon (see note).

BOX 1, 20, 20, , ,1
Draws a filled rectangle from 20, 20 to the current pixel cursor.

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

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

17.9 *BSAVE*

Save a binary file from the specified memory locations.

BSAVE "filename" [,Ddrive number] [<ON | ,>Udevice number] [,Bbank number],
Pstart address TO Pend address+1
where:
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
Saves the binary file named "SPRITE DATA" starting at location 3584 through 4095 (BANK 0).

BSAVE "PROGRAM.SCR",D0,U9,B0,P3182 TO P8000
Saves the binary file named "PROGRAM.SCR" in the memory address range 3182 through 7999 (BANK 0) on drive 0, unit 9.

17.10 *CATALOG*

Displays the disk directory.

CATALOG [Ddrive number] [<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
Displays the disk directory on drive 0 of unit 8.

17.11 *CHAR*

Displays characters at the specific position on the screen.

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

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

color source:

0 = Background color
1 = Foreground color
2 = Multicolor 1 } 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]
where:

color source:

0 = Background color
1 = Foreground color
2 = Multicolor 1 } Only in Graphics
3 = Multicolor 2 } modes 3 and 4

x,y

Centre coordinates of the CIRCLE.

xr

X radius (scaled).

yr

Y radius (scaled).

sa

Starting arc angle (default 0 degrees).

ea

Ending arc angle (default 360 degrees).

angle

Rotation in clockwise degrees (default is 0 degrees).

inc

Degrees between segments (default is 2 degrees).

[ASCII IMAGE]

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
Draws an ellipse

CIRCLE 1,160,100,65
Draws a circle

CIRCLE 1,60,40,20,18,,,,45
Draws an octagon

CIRCLE 1,260,40,20,30,,,,90
Draws a diamond

CIRCLE 1,60,140,20,18,,,,120
Draws a triangle

You may omit a parameter, but you must still place a comma in the 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
Logical file 2 is closed.

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
OPENs device #4, which is the printer.

CMD 1
All normal output now goes to the printer.

LIST
The LISTing goes to the printer, not the screen - even the word READY.

PRINT#1
Sends output back to the screen.

CLOSE 1
Close the file.

17.16 *COLLECT*

Free inaccessible disk space.

COLLECT [Ddrive number] [<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
Free all available space which has been incorrectly allocated to improperly closed files.

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

17.17 *COLLISION*

Define handling for sprite collision interrupt.

COLLISION type [, statement]

type

Type of interrupt as follows:
1 = Sprite-to-sprite collision
2 = Sprite-to-display collision
3 = Light pen

statement

BASIC line number of a subroutine

When the specified situation occurs, BASIC will finish processing the 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
Detects a sprite-to-sprite collision and program control sent to subroutine at line 5000.

COLLISION 1
Stops interrupt action which was initiated in above example.

COLLISION 2,1000
Detect sprite-to-display collision and program control directed to subroutine in line 1000.

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

17.18 *COLOR*

Define colors for each screen area.

COLOR source number, color number

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

Source Numbers

Area

Source

0

40-column (VIC) background

1

40-column (VIC) foreground

2

multicolor 1

3

multicolor 2

4

40-column (VIC) border

5

character color (40- or 80-column screen)

6

80-column (VDC) background color

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

Color Code   Color             Color Code   Color

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

             Color Numbers in 40-Column Format

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

              Color Numbers in 80-Column Format

EXAMPLES:

COLOR 0,1
Change background color of 40-column screen to black.

COLOR 5,8
Change character color to yellow.

17.19 *CONCAT*

Concatenates two data files.

CONCAT "file 2" [,Ddrive number] TO "file 1" [,Ddrive number]
[<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"
FILE B is attached to FILE A and the combined file is designated FILE A.

CONCAT (A$) TO (B$), D1, U9
The file named by B$ becomes a new file of the same name, with the file named by A$ attached to the end of B$ - this is performed on Unit 9, Drive 1 (a dual disk drive).

Whenever a variable is used as a filename as in the last example, the 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
Copies "TEST" from drive 0 to drive 1, renaming it "TEST PROG" on drive 1.

COPY "STUFF",D0 TO "STUFF",D1
Copies "STUFF" from drive 0 to drive 1.

COPY D0 TO D1
Copies all files from drive 0 to drive 1.

COPY "WORK.PROG" TO "BACKUP"
Copies "WORK.PRG" as a file called "BACKUP" on the same disk (drive 0).

[continue with next part]

[top of document]

page URL: www.bigfoot.com/~c128page/c128sg/sect-17a.htm
contact: c128page@bigfoot.com