C128 System Guide - Section 17 (cont)

Basic Commands and Statements - continued

TABLE OF CONTENTS header, help, if/then/else, input, input#, key, let, list, load, locate, monitor, movspr, new, on, open

17.48 HEADER

Formats a diskette.

HEADER diskname [,I i.d.] [,Ddrive number] [<ON | ,>Udevice number]

where:

diskname: Any name up to 16 characters.
i.d.: Any two alphanumeric characters. You must use two - you may not leave a space.

Before a new disk can be used for the first time, it must be formatted with the HEADER command. The HEADER command can also be used to erase a previously formatted disk, which can then be reused.

When you enter a HEADER command in direct mode, the prompt ARE YOU SURE? appears. In program mode, the prompt does not appear.

The command divides the disk into sections called blocks. It creates a table of contents of files, called a directory. Give each disk a unique i.d. number. Be careful when using the HEADER command because it erases all stored data.

You can HEADER a diskette more quickly if it was already formatted (by a HEADER command), by omitting the new disk i.d. The old i.d. is used instead. The quick HEADER can be used only if the disk was previously formatted, since it clears out the directory rather than formatting the disk. The default device number is 8 and the default drive is 0.

As a precaution, the system asks ARE YOU SURE? before the Commodore 128 completes the operation. Press the {y} key to perform the HEADER, or press any other key to cancel it.

The HEADER command reads the disk command error channel, and if any error is encountered, the error message ?BAD DISK is displayed.

The HEADER command is analogous to the BASIC 2.0 command:

OPEN 1,8,15,"N0:diskname,i.d." : CLOSE 1

EXAMPLES:

HEADER "MYDISK",I51,D0

This HEADERs "MYDISK" using i.d. 51 on drive 0, (default) device number 8.

HEADER "RECS",I45,D1 ON U9

This HEADERs "RECS" using i.d. 45, on Drive 1, device number 9.

HEADER "C128 PROGRAMS",D0

This is a quick HEADER on drive 0, device number 8, assuming the disk in the drive was already formatted. The old i.d. is used.

17.49 HELP

Highlight the line where the error occurred.

HELP

The HELP command is used after an error has been reported in a program. When HELP is typed in 40-column format, the line where the error occurs is listed, with the portion containing the error displayed in reverse field. In 80-column format, the portion of the line where the error occurs is underlined. Pressing the {help} key types HELP{return} automatically.

17.50 IF/THEN/ELSE

Evaluate a conditional expression and execute portions of a program depending on the outcome of the expression.

IF expression THEN statements
(BASIC 2.0)

IF expression THEN statements [:ELSE else-clause]
(BASIC 7.0)

The IF... THEN statement evaluates a BASIC expression and takes one or two possible courses of action depending upon the outcome of the expression. If the expression is true, the statement(s) following THEN is executed. This may be any BASIC statement. If the expression if false, the program resumes with the program line immediately following the program line containing the IF statement, unless an ELSE clause is present. The entire IF... THEN statement must be contained within 160 characters (80 in C64 mode). Also see BEGIN/BEND, in paragraph 17.5.

The ELSE clause, if present, must be on the same line as the IF... THEN portion of the statement, and separated from the THEN clause by a colon {:}. When an ELSE clause is present, it is executed only when the expression if false. The expression being evaluated may be a variable or a formula, in which case it is considered true if nonzero, and false if zero. In most cases, there is an expression involving relational operators (=, <, >, >=, <>).

The IF... THEN statement can take two alternate forms:

IF expression THEN line number

IF expression THEN GOTO line number

These forms transfer program execution to the specific line number if the expression is true. Otherwise, the program resumes with the program line number immediately following the line containing the IF statement.

EXAMPLES:

50 IF X>0 THEN PRINT "OK": ELSE END

This line checks the value of X. If X is greater than 0, the statement immediately following the keyword THEN (PRINT"OK") is executed and the ELSE clause is ignored. If X is less than or equal to 0, the ELSE clause is executed and the statement immediately following THEN is ignored.

10 IF X=10 THEN 100
20 PRINT"X does not equal 10"
.
.
99 STOP
100 PRINT "X equals 10"

This example evaluates the value of X. If X equals 10, the program control is transferred to line 100 and the message "X EQUALS 10" is printed. If X does not equal 10, the program resumes with line 20, the C128 prints the prompt "X DOES NOT EQUAL 10" and the program stops.

NOTE: The ELSE extension cannot be used in C64 mode.

17.51 INPUT

Receive a data string or a number from the keyboard and wait for the user to press {return}.

INPUT ["prompt string";] variable list

The INPUT statement asks for data from the user while the program is RUNning and places the data into a variable or variables. The program stops, prints a question mark (?) on the screen, and waits for the user to type the answer and hit the {return} key. The word INPUT is followed by a prompt string and a variable name or list of variable names separated by commas. The message in the prompt string inside quotes suggests (prompts) the information the user should enter. If this message is present, there must be a semicolon (;) after the closing quote of the prompt.

When more than one variable is INPUT, seperate them by commas. The computer asks for the remaining values by typing two question marks (??). If the {return} key is pressed without INPUTting a value, the INPUT variable retains its previous value. The INPUT statement can be executed only within a program.

EXAMPLE:

10 INPUT "PLEASE TYPE TWO NUMBER";A,B
20 INPUT "AND YOUR NAME";A$
30 PRINT A$;", YOU TYPED THE NUMBER"A;"AND";B

17.52 INPUT#

Inputs data from a file into the computer's memory.

INPUT#file number, variable list

This statement works like input, but takes the data from a previously OPENed file usually on a disk or tape instead of the keyboard. No prompt string is used. This statement can be used only within a program.

EXAMPLE:

10 OPEN 2,8,2,"DATAFILE,S,R"
20 INPUT#2,A$, C, D$
30 CLOSE 2

In line 20 data is INPUT from the file "DATAFILE" and stores it in variables A$, C and D$.

17.53 KEY

Define or list function key assignments.

KEY [key number, string]

There are eight function keys (F1 - F8) available to the user on the Commodore 128: four unshifted and four shifted. The Commodore 128 allows you to perform a function or operation for each time the specified function key is pressed. The definition assigned to a key can consist of data, or a command or series of commands. KEY with no parameters specified returns a listing displaying all current KEY assignments. If data is assigned to a function key, that data is displayed on the screen when that function key is pressed. The maximum length of all the definitions together is 246 characters.

EXAMPLES:

KEY 7,"GRAPHIC0" + CHR$(13) + "LIST" + CHR$(13)

This tells the computer to select the (VIC) 40-column text screen and list the program whenever the {f7} key is pressed (in direct mode). CHR$(13) is the ASCII character for {return} and performs the same action as pressing the {return} key. Use CHR$(27) for the {esc} key. Use CHR$(34) to incorporate the double quote character into a KEY string. The keys may be redefined in a program. For example:

10 KEY 2,"PRINT DS$" + CHR$(13)

This tells the computer to check and display the disk drive error channel variable (PRINT DS$) each time the {f2} key is pressed.

To restore all function keys to their BASIC default values, reset the Commodore 128 by pressing the {reset} button (or switch off and then on).

17.54 LET

Assigns a value to a variable.

[LET] variable = expression

The word LET is rarely used in programs, since it is not necessary. Whenever a variable is defined or given a value, LET is always implied. The variable name that receives the result of a calculation is on the left side of the equal sign. The number, string or formula is on the right side. You can only assign one value with each (implied) LET statement. For example, LET A=B=2 is not (normally) legal.

EXAMPLES:

LET A = 5

Assign the value 5 to numeric variable A.

B = 6

Assign the value 6 to numeric variable B.

C = A * B + 3

Assign the numeric variable C, the value resulting from 5 times 6 plus 3.

D$ = "HELLO"

Assign the string "HELLO" to string variable D$.

17.55 LIST

List the BASIC program currently in memory.

LIST [line | first- | first-last | -last]

The LIST command displays a BASIC program listing that has been typed or LOADed into the Commodore 128's memory so you can read and edit it. When LIST is used alone (without numbers following it), the Commodore 128 gives a complete LISTing of the program on the screen. The listing process may be slowed down by holding the {C=} key, paused by {ctrl s} or {noscroll} key (and resumed by pressing any key), or stopped by hitting the {run/stop} key. If the word LIST is followed by a line number, the Commodore 128 shows only that line number. If LIST is typed with two line numbers seperated by a dash all lines from the first to the second number are displayed. If LIST is typed followed by a number and just a dash, the Commodore 128 shows all line from that number to the end of the program. And if LIST is typed with a dash, then a number, all lines from the beginning of the program to that line number are LISTed. By using these variations, any portion of a program can be examined or brought to the screen for modification. In Commodore 128 mode, LIST can be used in a program.

EXAMPLES:

LIST

Shows entire program.

LIST 100-

Shows from line 100 until the end of the program.

LIST 10

Shows only line 10.

LIST -100

Shows all lines from the beginning to line 100 inclusive.

LIST 10-200

Shows lines from 10 to 200, inclusive.

17.56 LOAD

Load a program from a peripheral device such as the disk drive or Datassette.

LOAD ["filename"] [,device number] [,relocate flag]

This is the command used to recall a program stored on disk or cassette tape. Here, the filename is a program name up to 16 characters long, in quotes. The name must be followed by a comma (outside the quotes) and a number which acts as a device number to determine where the program is stored (disk or tape). If no number is supplied, the Commodore 128 assumes device number 1 (the Datassette tape recorder).

The relocate flag is a number (0 or 1) that determines where a program is loaded in memory. A relocate flag of 0 tells the Commodore 128 to load the program at the start of the BASIC program area. A flag of 1 tells the computer to LOAD from the point where it was SAVEd. The default value of the relocate flag is 0. The relocate parameter of 1 is generally used when loading machine language programs.

The device most commonly used with the LOAD command is the disk drive. This is device number 8, though the DLOAD command is more convenient to use when working with disk.

If LOAD is typed with no arguments, followed by {return}, the C128 assumes you are loading from tape and you are prompted to "PRESS PLAY ON TAPE". When you press PLAY, the Commodore 128 starts looking for a program on tape. When the program is found, the Commodore 128 prints FOUND "filename", where the filename is the name of the first file which the datassette finds on the tape. Press the {C=} key to LOAD the found filename, or press the {spacebar} to keep searching on the tape. Once the program is LOADed, it can be RUN, LISTed or modified.

NOTE: Pressing the {spacebar} does not cause the next file to be searched for in C64 mode.

EXAMPLES:

LOAD

Reads in the next program from tape.

LOAD "HELLO"

Searches tape for a program called "HELLO", and LOADs it if found.

LOAD A$,8

LOADs the program from disk whose name is stored in the variable A$. (This is the equivalent to DLOAD(A$).)

LOAD"HELLO",8

Looks for the program called "HELLO" on disk drive number 8, drive 0. (This is equivalent to DLOAD "HELLO".)

LOAD"MACHLANG",8,1

LOADs the machine language program called "MACHLANG" into the location from which it was saved.

The LOAD command can be used within a BASIC program to find and RUN the next program on a tape or disk. This is called chaining.

17.57 LOCATE

Position the bit map pixel cursor on the screen.

LOCATE x,y

The LOCATE statement places the pixel cursor (PC) at any specified pixel coordinate on the screen.

The pixel cursor (PC) is the coordinate on the bit map screen where drawing of circles, boxes, lines and points and where PAINTing begins. The PC ranges from x,y coordinates 0,0 throught 319,199 (scaled) in hi-res and 159,199 (scaled) in multicolor bit map. The PC is not visible like the text cursor, but it can be controlled through the graphics statements (BOX, CIRCLE, DRAW, etc.). The default location of the pixel cursor is the coordinate specified by the x and y portions in each particular graphics command. So the LOCATE command does not have to be specified.

EXAMPLE:

LOCATE 160,100

Position the PC in the centre of the standard bit map screen. Nothing will be seen until something is drawn.

The PC can be found by using RDOT(0) function to get the x-coordinate and RDOT(1) to get the y-coordinate. The color source of the dot at the PC can be found by PRINTing RDOT(2).

17.58 MONITOR

Enter the Commodore 128 machine language monitor.

MONITOR

See Appendix J for details on the Commodore 128 Machine Language Monitor.

17.59 MOVSPR

Position or move sprite on the screen.

MOVSPR number,x1,y1
Place the specified sprite at absolute coordinate x,y (scaled).

MOVSPR number,+/- x, +/- y
Move sprite relative to its current position.

MOVSPR number,X;Y
Move sprite distance X at angle Y relative to its current position.

MOVSPR number,x angle #y speed
Move sprite at an angle relative to its original coordinates, in the specified clockwise direction and speed.

where:

number: sprite's number (1 through 8)
<,x,y>: the coordinate of the sprite location (scaled)
angle: the angle (0-360) of motion in the clockwise direction relative to the sprite's original coordinates
speed: a speed (0-15) at which the sprite moves

This statement locates a sprite at a specific location on the screen according to the SPRITE coordinate plane (not the bit map plane) or initiates sprite motion at a specific rate. See MOVSPR in paragraph 6.3.7 of Section 6 for a diagram of the sprite coordinate system.

EXAMPLES:

MOVSPR 1,150,150

Position sprite 1 near the centre ot the screen, x,y coordinate 150, 150.

MOVSPR 1,+20,-30

Move sprite 1 to the right 20 coordinates and up 30 coordinates.

MOVSPR 4,-50,+100 Move sprite 4 to the left 50 coordinates and down 100.

MOVSPR 5,45 #15 Move sprite 5 at an 45 degree angle in the clockwise direction, relative to its original x and y coordinate. The sprite moves at the fastest rate (15).

NOTE: Once you specify an angle and a speed in the fourth form of the MOVSPR statement, you must set a speed of zero to stop the sprite moving.

17.60 NEW

Clear (erase) program and variable storage.

NEW

This command erases the entire program in memory and clears any variables that may have been used. Unless the program was stored on disk or tape, it is lost. Be careful with the use of this command. The NEW command also can be used as a statement in a BASIC program. However, when the Commodore 128 gets to this line, the program is erased and everything stops.

17.61 ON

Conditional branch to a specified program line number according to the results of the specified expression.

ON expression <GOTO | GOSUB> line #1 [,line #2, ...]

This statement can make the GOTO and GOSUB statements operate like special versions of the (conditional) IF statement. The word ON is followed by an expression, then either of the keywords GOTO or GOSUB and a list of line numbers separated by commas. If the result of the expression is 1, the first line number in the list is executed. If the result is 2, the second line number is executed on so on. If the result is 0, or larger than the number of line numbers in the list, the program resumes with the statement immediately following the ON statement. If the number is negative, an ILLEGAL QUANTITY error results.

EXAMPLE:

10 INPUT X:IF X<0 THEN 10
20 ON X GOSUB 30, 40, 50, 60
25 GOTO 10
30 PRINT "X=1":RETURN
40 PRINT "X=2":RETURN
50 PRINT "X=3":RETURN
60 PRINT "X=4":RETURN

When X=1, ON sends control to the first line number in the list (30). When X=2, ON sends control to the second line (40), etc.

17.62 OPEN

Open files for input or output.

OPEN logical file number, device number [,secundary address]
[<,"filename, filetype, mode" | cmd string>]

The OPEN statement allows the Commodore 128 to access files within devices such as a disk drive, a Datassette cassette recorder, a printer or even the screen of the Commodore 128.

The word OPEN is followed by a logical file number, which is the number to which all other BASIC input/output statements will refer, such as PRINT# (write), INPUT# (read), etc. This number is from 1 to 255.

The second number, called the device number follows the logical file number. Device number 0 is the Commodore 128 keyboard; 1 is the cassette recorder; 3 is the Commodore 128 screen; 4-7 are normally the printer(s); 8-11 are reserved for disk drives. It is often a good idea to use the same file number as the device number, because it makes it easy to remember which is which.

Following the device number may be a third parameter called the secundary address. In the case of the cassette, this can be 0 for read, 1 for write and 2 for write with END-OF-TAPE marker at the end. In case of the disk, the number refers to the channel number. See you disk drive manual for more information on channels and channel numbers. For the printer, the secundary addresses are used to select certain programming functions.

There may also be a filename specified for disk or tape OR a string following the secundary address, which could be a command to the disk/tape drive or the name of the file on tape or disk. If the filename is specified, the type and mode refer to disk files only. File types are PROGRAM, SEQUENTIAL, RELATIVE and USER; modes are READ and WRITE.

EXAMPLES:

10 OPEN 3,3

OPENs the screen as file number 3.

20 OPEN 1,0

OPENs the keyboard as file number 1.

30 OPEN 1,1,0,"DOT"

OPENs the cassette for reading, as file number 1, using "DOT" as the filename.

OPEN 4,4

OPENs the printer as file number 4.

OPEN 15,8,15

OPENs the command channel on the disk as file 15, with secundary address 15. (Secundary address 15 is reserved for the disk drive error command channel.)

5 OPEN 8,8,12,"TESTFILE,SEQ,WRITE"

OPENs a sequential disk file for writing called "TESTFILE" as file number 8, with secundary address 12.

See also: CLOSE (17.13), CMD (17.15), GET# (17.43), INPUT# (17.52), and PRINT# (17.67) statements and system variables ST, DS and DS$ (19.1).

Portions of this page are (C) by Commodore.ca and this site is hosted by www.URTech.ca
If you want to use any images or text from this site you must get written approval first. Click HERE to send an email request explaining your intended usage.