Basic Commands and Statements - continued

17.22 DATA

Define data to be used by a program.

DATA list of constants

This statement is followed by a list of data items to be input into the computer's memory by READ statements. The items may be numeric or string and are seperated by commas. String data need not be inside quote marks, unless they contain any of the following characters: {space}, {colon}, or {comma}. If two commas have nothing between them, the value is READ as a zero if numeric or as an empty string. Also see the RESTORE statement, in paragraph 17.75, which allows the Commodore 128 to reREAD data.

EXAMPLE:

DATA 100,200, FRED, "HELLO MUM", , 3, 14, ABC123

17.23 DCLEAR

Clear all open channels on disk drive.

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

This statement closes and clears all open channels on the specified device number. Default is U8. This command is analogous to OPEN 0,8,15,"I0": CLOSE 0.

EXAMPLES:

DCLEAR D0

DCLEAR D1,U9

NOTE: Files will be aborted, data may not be recoverable from files which were being written to. See CLOSE/DCLOSE, in paragraphs 17.13 / 17.24.

17.24 DCLOSE

Close disk file.

DCLOSE [#logical file number] [<ON | ,>Udevice]

This statement closes a single file or all the files currently open on a disk unit. If no logical file number is specified, all currently open files are closed. The default device number is 8. Note the following examples:

EXAMPLES:

DCLOSE

DCLOSE #2

DCLOSE ON U9

17.25 DEF FN

Define a user-defined function.

DEF FN name(variable) = expression

This statement allows definition of a complex calculation as a function. In the case of a long formula that is used several times within a program, this keyword can save valuable program space. The name given to the function begins with the letters FN, followed by any legal numeric variable name (not integer or array). First, define the function by using the statement DEF, followed by the name given to the function. Following the name is a set of parentheses ( ) with a local variable name enclosed. This variable only has a value if it appears in the expression on the right of the equal sign. The same variable name can be used elsewhere in a program but it will be completely seperate from its use in the function. Other variables and/or functions can be used in the expression and these are evaluated as their value at the time the function is called. Next is an equal sign, followed by the formula to be defined. The function can be performed by sustituting any number for variable, using the format shown in lines 40 and 50 of the example below.

EXAMPLE:

10 DEF FNEG(LO)=INT((V1*LO^2)*100)/100
   LO is local to this line
20 LO=15
   A normal program variable
30 V1=3.14159
   Approximation of {pi}
40 PRINT FNEG(5)
   Assign 5 to the local value LO in the function.
50 PRINT FNEG(1)
   Use 1 in the function instead of LO.
60 PRINT INT(V1*LO^2)*100)/100
   Variable LO used
70 PRINT LO
   Remains unchanged

17.26 DELETE

Delete lines of a BASIC program in the specified range.

DELETE <start line | start line -  | start line - end line | - end line>

This command can be executed only in direct mode.

EXAMPLES:

DELETE 75

DELETE 10-50

DELETE-50

DELETE 75-

17.27 DIM

Declare number of elements in an array.

DIM variable(subscripts) [, variable(subscripts)] [...]

Before arrays of variables can be used, the program must first execute a DIM statement to establish DIMensions of the array (unless there are 11 or fewer elements in each DIMension of the array). The DIM statement is followed by the name of the array, which may be any legal variable name. Then, enclosed in parantheses, 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 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. Here's how to calculate the amount of memory used by an array:

• 5 bytes for the array name
• 2 bytes for each dimension
• 2 bytes/element for integer variables
• 5 bytes/element for normal numeric variables
• 3 bytes/element for string variables
• 1 byte for each character in each string element

Integer arrays take up two-fifths the space of floating point arrays (e.g. DIM A%(100) requires 209 bytes; DIM A(100) requires 512 bytes).

NOTE: Elements are numbered from 0, e.g. DIM A(100) gives 101 elements.

More than one array can be dimensioned in a DIM statement by seperating the array variable names by commas. If the program executes a DIM statement for any array more than once, the message RE'DIM ARRAY ERROR is posted. It is good programming practice to place DIM statements near the beginning of the program.

EXAMPLE:

10 DIM A$(40),B7(15),CC%(4,4,4)

17.28 DIRECTORY

Displays the contents of the disk directory on the screen.

DIRECTORY [Ddrive number] [<ON | ,>Udevice] [, wildcard]

The {f3} function key in C128 mode displays the DIRECTORY for device number 8, drive 0. Use CONTROL S or NOSCROLL to pause the display.

The DIRECTORY command should not be used to print a hard copy, because some printers interfere with the data coming from the disk drive. The disk directory should be loaded (LOAD "$",8) destroying the current program in memory in order to print a hard copy.

The default device number is 8, and the default drive number is 0.

EXAMPLES:

DIRECTORY

DIRECTORY D1, U9, "WORK"

DIRECTORY "AB*"

DIRECTORY D0, "FILE ?.BAK"

DIRECTORY D1,U9,(A$)

NOTE: To print the DIRECTORY of the disk in drive 0, unit 8, use the following example:

LOAD"$0",8
OPEN4,4:CMD4:LIST
PRINT#4:CLOSE4

17.29 DLOAD

Load a BASIC program from disk.

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

This command loads a BASIC program from disk into current memory. (Use LOAD to load programs from tape.) The program must be specified by a filename of up to 16 characters. DLOAD assumes device number 8, drive 0.

EXAMPLES:

DLOAD "BANKRECS"

DLOAD (A$)

The DLOAD command can be used within a BASIC program to find another program on disk. This is called chaining.

17.30 DO/LOOP/WHILE/UNTIL/EXIT

Define and control progam loop.

DO [UNTIL condition | WHILE condition] statement [EXIT]
LOOP [UNTIL condition | WHILE condition]

This loop structure performs the statements between the DO statement and the LOOP statement. If no UNTIL or WHILE statements modifies either the DO or the LOOP statement, execution of the statements in between continues indefinitely. If an EXIT statement is encountered in the body of a DO loop, execution is transferred to the first statement following the LOOP statement. DO loops may be nested, following the rules defined by the FOR... NEXT structure. If the UNTIL parameter is specified, the program continues looping until the condition is satisfied (becomes true). The WHILE parameter is basically the oposite of the UNTIL parameter: the program continues looping as long as the condition is true. As soon as the condition is no longer true, program control resumes with the statement immediately following the LOOP statement. An example of a condition (boolean operation) is A=1, or G>65.

EXAMPLES:

10 X=25
20 DO UNTIL X=0
30 X=X-1
40 PRINT "X=";X
50 LOOP
60 PRINT "END OF LOOP"

10 DO WHILE A$="":GET A$:LOOP
20 PRINT "THE ";A$;" KEY HAS BEEN PRESSED"

10 OPEN #8,"SEQFILE"
20 DO
30 GET #8,A$
40 PRINT A$;
50 LOOP UNTIL ST
60 DCLOSE #8

17.31 DOPEN

Open a disk file for a read and/or write operation.

DOPEN #logical file number,"filename[,<S | P>]" [,Lrecord length]
[,Ddrive number] [<ON | ,>Udevice number] [,w]

S

Sequential file type.

P

Program file type.

L

Record length = the length of records in a relative file only.

w

Write operation (if not specified a read operation occurs).

This statement opens a sequential, program or relative file for a read or write operation. The record length (L) pertains to a relative file, which can be as long as 254. The w parameter is specified only during a write (PRINT#) operation in a sequential file. If not specified, the disk drive assumes the disk operation to be a read operation. Relative file are open for both read and write operations at the same time.

The logical file number associates a number to a file for future disk operations such as a read (INPUT# or GET#) or write (PRINT#) operation. The logical file number can range from 1 to 255. Logical file numbers greater than 128 automatically send a carriage return and linefeed with each PRINT# command. Logical file number less than 128 send only a carriage return, which can be suppressed with a semicolon at the end of the PRINT# command. The default device number is 8, and the default drive is 0.

EXAMPLES:

DOPEN#1,"ADDRESS",W

DOPEN#2,"RECIPES",D1,U9

DOPEN#3,"BOOKS",L128

17.32 DRAW

Draw dots, lines and shapes at specified positions on screen.

DRAW [color source], x1,y1 [TO x2,y2] ...

This statement draws individual dots, lines, and shapes. Here are the parameter values:

color source:	0 =	Background color
	1 =	Foreground color
	2 =	Multicolor 1	} Only in Graphics
	3 =	Multicolor 2	} modes 3 and 4
x1, y1	Starting coordinate, scaled.
x2, y2	Ending coordinate, scaled.

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

EXAMPLES:

DRAW 1,100,50

DRAW ,10,10 TO 100,60

DRAW ,10,10 TO 10,60 TO 100,60 TO 10,10

You may omit a parameter but you still must include the comma that would have followed the unspecified parameter.

17.33 DSAVE

Save a BASIC program file to disk.

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

This command stores (SAVEs) a BASIC program on disk. (See SAVE, in paragraph 17.80, to store programs on tape.) A filename up to 16 characters long must be supplied. The default device number is 8, while the default drive number is 0.

EXAMPLES:

DSAVE "BANKRECS"

DSAVE (A$)

DSAVE "PROG 3",D1,U9

17.34 DVERIFY

Verify the program in memory against the one on disk.

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

This command causes the Commodore 128 to check the program on the specified drive against the program in memory. The default drive number is 0 and the default device number is 8.

NOTE: If graphic area is allocated or deallocated after a SAVE, an error occurs. Technically this is correct. Because BASIC text is moved from its original (SAVEd) location when a bit mapped graphics area is allocated or deallocated, the original location where the C128 verified the SAVEd program changes. Hence, VERIFY, which performs byte-to-byte comparisons, fails, even though the program is valid.

To verify binary data, see VERIFY "filename",8,1 format, under VERIFY command description, in paragraph 17.100.

EXAMPLES:

DVERIFY "C128"

DVERIFY "SPRITES",D0,U9

17.35 END

Define the end of program execution.

END

When the program encounters the END statement, it stops RUNning immediately. The CONT command can be used to restart the program at the next statement (if any) following the END statement.

17.36 ENVELOPE

Define a musical instrument envelope.

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 level (0-15)
rel	Release rate (0-15)
wf	Waveform:	0 =	triangle
		1 =	sawtooth
		2 =	variable pulse (square)
		3 =	noise
		4 =	ring modulation
pw	Pulse width (0-4095)

A parameter that is not specified will retain its predefined or currently redefined value. Pulse width applies to the width of the variable pulse waveform (wf=2) only and is determined by the formula: pwout = pw/40.95, so that pw=2048 produces a square wave and values 0 and 4095 produce constant DC output. The Commodore 128 has initialized the following 10 envelopes:

         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     harpsicord
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

To play predefined musical instrument envelopes, you simply specify the envelope number in the PLAY command (see PLAY, in paragraph 17.64). You do not need to use the ENVELOPE command. The ENVELOPE command is used only when you need to change the envelope.

17.37 FAST

Put machine in 2 Mhz mode of operation.

FAST

This command initiates 2 Mhz mode, causing VIC's 40 column screen to be turned off. All operartions (except I/O) are speeded up considerably. Graphics may be used, but will not be visible until a SLOW command is issued.

17.38 FETCH

Get data from expansion (RAM module) memory.

FETCH #bytes, intsa, expsa, expb

#bytes

number of bytes to get from expansion memory (0-65535)

intsa

starting address of host RAM (0-65535)

expsa

starting address of expansion RAM (0-65535)

expb

64K expansion RAM bank number (0-15)

17.39 FILTER

Define sound (SID chip) 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).

Unspecified parameters result in no change to the current value.

You can use more than one type of filter at a time. For example, both low-pass and high-pass filters can be used together to produce a notch (or band-reject) filter response. For the filter to have an audible effect, at least one type of filter must be selected and at least one voice must be routed through the filter.

EXAMPLES:

FILTER 1024,0,1,0,2

FILTER 2000,1,0,1,10

17.40 FOR/TO/STEP/NEXT

Define a repetitive program loop structure.

FOR variable = start value TO end value [STEP increment]

NEXT [variable]

The FOR statement works with the NEXT statement to set up a section of the program that repeats for a set number of times (i.e. a loop). This is useful when something needs to be counted or something must be done a certain number of times (such as printing).

This statement executes all the commands enclosed between the FOR and NEXT statements repetitively, according to the start and end values. The start value and end value are the beginning and ending counts for the loop variable. The loop variable is added to or subtracted from during the FOR... NEXT loop.

The logic of the FOR... NEXT statement is as follows. First, the loop variable is set to the start value. When the program reaches a program line containing the NEXT statement, it adds the STEP increment (default = 1) to the value of the loop variable and checks to see if it is higher than the end value of the loop. If the loop variable is less than or equal to the end value, the loop is executed again, starting with the statement immediately following the FOR statement. If the loop variable is greater than the end value, the loop terminates and the program resumes immediately following the NEXT statement. The opposite is true if the step size is negative.

EXAMPLE A 10 FOR L=1 TO 10 20 PRINT L 30 NEXT L 40 PRINT "I'M DONE! L =";L

EXAMPLE B 10 FOR L=10 TO 1 STEP-1 20 PRINT L 30 NEXT L 40 PRINT "I'M DONE! L =";L

Program A prints the number from one to 10, followed by the message I'M DONE! L = 11. Program B prints the numbers down to one and them I'M DONE! L = 0.

The end value of the loop may be followed by the word STEP and another number or variable. In this case, the value following the word STEP is added each time, instead of the default value one. This allows counting backwards, by fractions, or increments other than one.

The user can set up loops inside one another. These are known as nested loops. Care must be taken when nesting loops so, that the last loop to start is the first one to end.

EXAMPLE:

10 FOR L = 1 TO 100
20 FOR A = 5 TO 11 STEP .5
30 NEXT A
40 NEXT L

17.41 GET

Receive input data from the keyboard, one character at a time without waiting for a key to be pressed.

GET variable list

The GET statement reads each key typed by the user. As the user types, the characters are stored in the computer's memory (in an area called the keyboard buffer). Up to 10 characters can be stored here1, any characters typed after the 10th character are lost. The GET statement reads the first character from the buffer and moves the rest up, allowing room for more. If there are no characters in the buffer a null (empty) character is returned. The word GET is followed by a variable name, either numeric or string. GET will not pause the program if no characters are in the buffer (see GETKEY, in paragraph 17.42).

If the C128 intends to GET a numeric key and a key other than a number is pressed, the program stops and a TYPE MISMATCH error message is displayed. The GET statement may also be put into a loop, checking for an empty result. The GETKEY statement could also be used in this case. See GETKEY, in paragraph 17.42, for more information. The GET and GETKEY statements can be executed only within a program.

EXAMPLES:

10 DO:GET A$:LOOP UNTIL A$="A"

20 GET B, C, D

17.42 GETKEY

Receive input data from the keyboard, one character at a time and wait for a key to be pressed.

GETKEY variable list

The GETKEY statement is very similar to the GET statement. Unlike the GET statement, GETKEY, if there is no character in the keyboard buffer, will wait for the user to type a character on the keyboard. This lets the computer wait for a single character to be typed. This statement can be executed only within a program.

EXAMPLES:

10 GETKEY A$

10 GETKEY A$,B$,C$

NOTE: GETKEY cannot return a null (empty) character.

17.43 GET#

Receive input data from a tape, disk or RS232.

GET#file number, variable list

This statement inputs one character at a time from a previously opened file. Otherwise, it works like the GET statement. This statement can be executed only within a program.

EXAMPLE:

GET#1,A$ This example receives one character, which is stored in the variable A$, from file number 1. This example assumes that file 1 was previously opened. See the OPEN and DOPEN statements, in paragraphs 17.62 and 17.3, respectively.

17.44 GO64

Switch to C64 mode.

GO64

This statement switches from C128 mode to C64 mode. The question "Are You Sure?" is displayed in response to the GO64 statement. If {y} is typed, then the currently loaded program is lost and control is given to the C64 mode; otherwise, if any other key is pressed, the computer remains in C128 mode. This statement can be used in direct mode or within a program. The prompt is not displayed in program mode.

17.45 GOSUB

Call a subroutine from the specified line number.

GOSUB line number

This statement is similar to the GOTO statement, except the Commodore 128 returns from where it came when the subroutine is finished. When a line with a RETURN statement is encountered, the program jumps back to the statement immediately following the GOSUB statement.

The target of a GOSUB statement is called a subroutine. A subroutine is useful if a task is repeated several times within a program. Instead of duplicating the section of program over and over, set up a subroutine, and GOSUB to it at the appropriate time in the program. See also the RETURN statement, in paragraph 17.77.

EXAMPLE:

20 GOSUB 800
:
:
799 END
800 PRINT "HI THERE": RETURN

Line 799 stops the program accidentally falling into the subroutine.

17.46 GOTO/GO TO

Transfer program execution to the specified line number.

GOTO line number

After a GOTO statement is encountered in a program, the computer executes the statement specified by the line number in the GOTO statement. When used in direct mode, GOTO executes (RUNs) the program starting at the specified line number, without clearing the variables. This is the same as the RUN command except it does not clear variable values.

EXAMPLES:

10 PRINT"COMMODORE"
20 GOTO 10

GOTO 100

17.47 GRAPHIC

Select a graphic mode.

GRAPHIC mode [,clear] [,s]

GRAPHIC CLR

This statement puts the Commodore 128 in one of the six graphic modes:

Mode	Description
0	40-column (VIC) standard text
1	Standard bit map
2	Standard bit map (split screen)
3	Multicolor bit map
4	Multicolor bit map (split screen)
5	80-column text

The clear parameter specifies whether the bit mapped screen is cleared (equal to 1) upon running the program, or left intact (equal to 0). The s parameter indicates the starting line number of the split screen when in graphic mode 2 or 4 (standard or multicolor bit map split screen modes). The default starting line number of the split screen is 19.

When executed, GRAPHIC 1-4 allocated a 9K bit mapped area. The start of BASIC text area is moved above the bit map area, and any BASIC program is automatically relocated. This area remains allocated even if the user returns to TEXT mode (GRAPHIC 0). If the clear option is specified as 1, the screen is cleared. The GRAPHIC CLR command deallocates the 9K bit mapped area, making it available again for BASIC text. Any BASIC program is relocated.

EXAMPLES:

GRAPHIC 1,1

GRAPHIC 4,0,10

GRAPHIC 0

GRAPHIC 5

GRAPHIC CLR