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

Basic Commands and Statements - continued


TABLE OF CONTENTS
data, dclear, dclose, def fn, delete, dim, directory, dload, do/loop/while/until/exit, dopen, draw, dsave, dverify, end, envelope, fast, fetch, filter, for/to/step/next, get, getkey, get#, go64, gosub, goto/go to, graphic

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
Clears all open channels on drive 0, device number 8.

DCLEAR D1,U9
Clears all open channels on drive 1, device number 9.

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
Closes all files currently open on unit 8.

DCLOSE #2
Closes the file associated with the logical file number 2.

DCLOSE ON U9
Closes all files curently open on unit 9.

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
Deletes line 75.

DELETE 10-50
Deletes lines 10 through 50, inclusive.

DELETE-50
Deletes all lines from the beginning of the program up to and including line 50.

DELETE 75-
Deletes all lines from 75 to the end of the program, inclusive.

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)
41 elements, 16 elements, 125 elements.

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
Lists all files on the disks in unit 8.

DIRECTORY D1, U9, "WORK"
Lists the file named "WORK" on drive 1 of unit 9.

DIRECTORY "AB*"
Lists all files starting with the letters "AB" like ABOVE, ABOARD, etc. on all drives of unit 8. The asterisk specifies a wild card, where all files starting with "AB" are displayed.

DIRECTORY D0, "FILE ?.BAK"
The ? is a wild card that matches a single character in that position. For example: FILE 1.BAK, FILE 2.BAK, FILE 3.BAK all matching the string.

DIRECTORY D1,U9,(A$)
Lists the filename stored in the variable A$, on device number 9, drive 1. Remember whenever a variable is used as a filename, surround the variable in parentheses.

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"
Searches the disk for the program "BANKRECS" and LOADs it.

DLOAD (A$)
LOADs a program from disk whose name is stored in the variable A$. An error message is given if A$ is empty. Remember, when a variable is used as a filename, it must be enclosed in parentheses.

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"
This example performs the statement X=X-1 and PRINTs "X=";X until X=0. When X=0 the program resumes with the statement following LOOP, PRINT "END OF LOOP"

10 DO WHILE A$="":GET A$:LOOP
20 PRINT "THE ";A$;" KEY HAS BEEN PRESSED"
A$ remains null as long as no key is pressed. As soon as a key is pressed program control passes to the statement immediately following LOOP, PRINT "THE ";A$;" KEY HAS BEEN PRESSED". The example performs a GET A$ as long as A$ is a null character. This loop constantly checks to see if a key on the keyboard is being pressed. Note that the statement GETKEY A$ has the same effect as line 10.

10 OPEN #8,"SEQFILE"
20 DO
30 GET #8,A$
40 PRINT A$;
50 LOOP UNTIL ST
60 DCLOSE #8
This program opens the file "SEQFILE" and gets data until the ST system variable indicates all data is input. A value of 0 indicates a FALSE condition, nonzero is true. ST is normally 0.

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]
where:
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
Open the sequential file number 1 (ADDRESS) for a write operation.

DOPEN#2,"RECIPES",D1,U9
Open the sequential file number 2 (RECIPES) for a read operation on device number 9, drive 1.

DOPEN#3,"BOOKS",L128
Open the relative file number 3 (BOOKS) for read and write on unit 8 drive 0. Record length is 128 characters.

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 a dot

DRAW ,10,10 TO 100,60
Draw a line

DRAW ,10,10 TO 10,60 TO 100,60 TO 10,10
Draw a triangle

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"
SAVEs the program "BANKRECS" to disk.

DSAVE (A$)
SAVEs the disk program named in the variable A$.

DSAVE "PROG 3",D1,U9
SAVEs the program "PROG 3" to disk on unit 9, drive 1 (on a dual drive unit).

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"
Verifies program "C128" on drive 0, unit 8.

DVERIFY "SPRITES",D0,U9
Verifies program "SPRITES" on drive 0, device 9.

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]
where:

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
where:
#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]
where:
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
Set the cutoff frequency at 1024, select the band pass filter and a resonance level of 2.

FILTER 2000,1,0,1,10
Set the cutoff frequency at 2000, select both the low pass and high pass filters (to form a notch-reject) and set the resonance level at 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
The FOR... NEXT loop in lines 20 and 30 are nested inside the one in line 10 and 40. The STEP increment of .5 is used to illustrate the fact that floating point indices are valid.

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"
This line waits for the A key to be pressed to continue.

20 GET B, C, D
Get numeric variables B, C and D from the keyboard without waiting for a key to be pressed.

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$
This line waits for a key to be pressed. Typing any key continues the program.

10 GETKEY A$,B$,C$
This line waits for three alphanumeric characters to be entered from the keyboard. GETKEY can also be used to READ numeric keys.

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
This example calls the subroutine beginning at line 800 and executes it. All subroutines terminate with a RETURN statement.

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
The GOTO in line 20 makes line 10 repeat continuously until {run/stop} is pressed.

GOTO 100
Starts (RUNs) the program starting at line 100, without clearing the variable storage area.

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
Select standard bit map mode and clear the bit map.

GRAPHIC 4,0,10
Select split screen multicolor bit map mode, do not clear the bit map and start the split screen at line 10.

GRAPHIC 0
Select 40 column text.

GRAPHIC 5
Select 80 column text.

GRAPHIC CLR
Clear and deallocate the bit map screen.

[continue with next part]

[top of document]

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