C128 System Guide - Section 17 (cont)

Basic Commands and Statements - continued

TABLE OF CONTENTS save, scale, scnclr, scratch, sleep, slow, sound, sprcolor, sprdef, sprite, sprsav, sshape/gshape, stash, stop, swap, sys/sys, tempo, trap, troff, tron, verify, vol, wait, width, window

17.80 SAVE

Store the program in memory to disk or tape.

SAVE ["filename"] [,device number] [,EOT flag]

This command stores the program currently in memory onto cassette tape or disk for later retrieval. If SAVE is typed alone an unnamed file will be saved to tape. Tape is a sequential system and, therefore, it is up to the user to ensure that there is nothing important on the tape before SAVEing (see VERIFY, in paragraph 17.100). To give your program a name simply enclose the chosen name in quotes (or use a string variable) immediately after typing SAVE. A filename can be up to 16 characters.

NOTE: When SAVEing to disk you must specify a filename or you will get a MISSING FILE NAME ERROR.

To specify the device number (e.g. 1 for tape) place a comma followed by the device number after the closing quote following the filename.

The final parameter (EOT) follows the device number and is again seperated by a comma. It has no significance when used with disk and can have one of four values when used with tape. These options are:

0: Default - no action.
1: SAVE so that the relocate function of LOAD does not work, i.e. the file will always load back at the address from which it was SAVEd.
2: Write an END OF TAPE marker at the end of the file - attempts to LOAD beyond the end of a file saved this way will generate a FILE NOT FOUND ERROR.
3: SAVEs in non-relocatable format (1) and writes the EOT (2).

NOTE: If you specify the device number or EOT parameter the filename (and device number) must be included. For tape this may be a null (""). See the following examples.

EXAMPLES:

SAVE "HELLO"

Stores a program on tape, under the name HELLO

SAVE A$,8

Stores on disk, with the name stored in variable A$.

SAVE "HELLO",8

Stores on disk, with the name HELLO (equivalent to DSAVE "HELLO").

SAVE "HELLO", 1, 2

Stores on tape, with the name HELLO, and places an END-OF-TAPE marker after the program.

SAVE "",1,3

Stores on tape, with no name, places an EOT marker after the program, does not allow the program to be relocated on loading.

17.81 SCALE

Alter scaling in graphics mode.

SCALE n [,xmax,ymax]

where:

n: 1 (on) or 0 (off)
xmax: in the range 320-32767,
default 1023 (hi-res)
default 2047 (multicolor)
ymax: in the range 200-32767,
default 1023

Changes the scaling of the bit map display coordinates in both multicolor and high resolution modes. Coordinates for the MOVSPR command are also scaled. Maps many logical points to one physical point.

This is helpful when you need to plot data over a wide range of values - it will not help if you have a large cluster of data with only high values.

Because multicolor uses 2 physical pixels on the x-axis per dot, its normal display is:

X=0 to 159 ; Y=0 to 199

as opposed to

X=0 to 319 ; y=0 to 199

If you wish to use the same coordinates for multicolor and hi-res use SCALE 1,640,200 after setting up a multicolor screen and use the default SCALE values for both types of screen.

NOTE: The GRAPHIC command turns scaling off, i.e. using GRAPHIC (something) is equivalent to GRAPHIC...: SCALE 0.

EXAMPLE:

10 GRAPHIC 1: GOSUB 100
20 SCALE 1: GOSUB 100
30 SCALE 1,5000,5000: GOSUB 100
40 END
100 CIRCLE 1,160,100,60: RETURN

17.82 SCNCLR

Clear screen.

SCNCLR [mode number]

Mode Number   Mode
     0        40 column (VIC) text.
     1        bit map*.
     2        split screen bit map*.
     3        multicolor bit map*.
     4        split screen multicolor bit map*.
     5        80 column (VDC 8563) text.

This statement with no arguments clears the graphics screen, if it is present, otherwise the current text screen is cleared**.

EXAMPLES:

SCNCLR 5

Clears 80 column text screen.

SCNCLR 1

Clears the (VIC) bit map screen.

SCNCLR 4

Clears the (VIC) multicolor bit map split screen.

NOTE *: The bit map area is the same for both hi-res and multicolor, the different mode numbers select other parameters to clear e.g. 40 column text (2 and 4) and color RAM (3 and 4).

NOTE **: If a graphics screen has been created but is not selected (GRAPHIC=0) it will not be cleared. If you are using 2 screens (80 column for text and 40 column for graphics) SCNCLR will clear both text and graphics screens if called from the 80 column screen.

17.83 SCRATCH

Delete a file from the disk directory.

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

This command deletes a file form the disk directory. As a precaution, the system asks "Are you sure?" (in direct mode only) before the Commodore 128 starts the operation. Type a {y} to perform the SCRATCH or press any other key to cancel the operation.

Use this command to erase unwanted files, and to create more space on the disk. The filename may contain template, or wildcards (?,*). The default drive number is 0 and default device number is 8.

EXAMPLE:

SCRATCH "MY BACK",D0

This erases the file "MY BACK" from the disk in drive 0 of unit 8.

17.84 SLEEP

Delay program for a specific period of time.

SLEEP n

where n is seconds (0 < n < 65536)

If you select a delay which is too long for your program and you want to halt it, the {stop} key can be used to break into a delay.

17.85 SLOW

Return the Commodore 128 to 1 Mhz operation.

SLOW

The Commodore 128 is capable of running the 8502 microprocessor at a speed of 1 or 2 Megahertz (Mhz).

The SLOW command slows down the microprocessor to 1 Megahertz from 2 Megahertz. The FAST command sets the Commodore 128 at 2 Mhz. The Commodore 128 can process commands substantially faster at 2 Mhz than at 1 Mhz. Note, however, that the 40 column screen cannot be used at 2 Mhz.

17.86 SOUND

Outputs sound effects and musical notes.

SOUND v, f, d [, dir] [, m] [, s] [, w] [, p]

where:

v: voice 1, 2 or 3
f: frequency value (0-65535)
d: duration (0-32767)
dir: step direction (0 = up, 1 = down, 2 = oscillate), default=0
m: minimum frequency (0-65535) if the sweep is used, default=0
s: step value for sweep (0-65535), default=0
w: waveform (0 = triangle, 1 = sawtooth, 2 = pulse, 3 = noise), default=2
p: pulse width (0-4095), default=2048

The SOUND command is a fast and easy way to create sound effects and musical tones. The three required parameters v, f and d select the voice, frequency and duration of the sound. The duration is in units called jiffies. Sixty jiffies equals 1 second.

The SOUND command can sweep through a series of frequencies which allows sound effects to pass through a range of notes. Specify the direction of the sweep with the dir parameter. Set the minimum frequency of the sweep with m and the step value of the sweep with s. Select the appropriate waveform with w and specify p as the width of the variable pulse waveform if selected in w.

EXAMPLES:

SOUND 1,40960,60

Play a SOUND at frequency 40960 in voice 1 for 1 second.

SOUND 2,2000,5,0,2000,100

Output a sound by sweeping through the frequencies starting at 2000 and incrementing upward in units of 100.

SOUND 3,5000,1,2,3000,500,1

This example outputs a range of sounds starting at a minimum frequency of 3000, through 5000, in increments of 500. The direction of the sweep is back and forth (oscillating). The selected waveform is sawtooth and the voice selected is 3.

17.87 SPRCOLOR

Set multicolor 1 and/or multicolor 2 colors for all sprites.

SPRCOLOR [smcr1] [, smcr2]

where:

smcr1: multicolor 1 for all sprites.
smcr2: multicolor 2 for all sprites.

These parameters may be any color from 1 through 16.

EXAMPLES:

SPRCOLOR 3,7

Sets sprite multicolor 1 to red and multicolor 2 to blue.

SPRCOLOR 1,2

Sets sprite multicolor 1 to black and multicolor 2 to white.

17.88 SPRDEF

Enter the SPRite DEFinition mode to create and edit sprite images (40 column display only).

SPRDEF

The SPRDEF command defines sprites interactively.

Entering the SPRDEF command, displays a sprite work area on the screen which is 24 characters wide by 21 characters tall. Each character position in the grid corresponds to a sprite pixel in the sprite displayed to the right of the work area. Here is a summary of the SPRite DEFinition mode operations and the keys that perform them:

At the SPRITE NUMBER? prompt

user
input description

{return}
Exits SPRite DEFinition mode at the SPRITE NUMBER? prompt only.

{1} - {8}
Selects a sprite number and enters sprite edit mode.

In the sprite edit mode

user
input description

{a}
Turns on and off Automatic cursor movement.

{crsr} keys
Moves cursor.

{return}
Moves cursor to start of next line.

{home}
Moves cursor to top left corner of sprite work area.

{clr}
Erases entire grid.

{1}-{4}
Selects color source:

1 = clear

2 = foreground

3 = multicolor 1

4 = multicolor 2

{ctrl 1} - {ctrl 8}
Selects sprite foreground color (1-8).

{C= 1} - {C= 8}
Selects sprite foreground color (9-16).

{stop}
Cancels changes and returns to the READY prompt.

{shift return}
Saves sprite in memory and returns to the SPRITE NUMBER? prompt.

{x}
Expands sprite in X (horizontal) direction - Toggle.

{y}
Expands sprite in Y (vertical) direction - Toggle.

{m}
Standard sprite / Multicolor sprite - Toggle.

{c}
Copies sprite data from one sprite to another.

NOTE: Using SPRDEF will clear the bit map screen.

17.89 SPRITE

Turn on or off, color, expand and set screen priorities for a sprite.

SPRITE <number> [,on/off] [,fgnd] [,priority] [,x-exp] [,y-exp] [,mode]

The SPRITE statement controls most of the characteristics of a sprite.

Parameter Description

number

Sprite number (1-8).

on/off

Turns sprite on (1) or off (0).

fgnd

Sprite foreground color (1-16).

priority

Priority is 0 if sprites appear in front of object on the screen;
priority is 1 if sprites appear behind objects on the screen.

x-exp

Horizontal EXPansion on (1) or off (0).

y-exp

Vertical EXPansion on (1) or off (0).

mode

Select standard sprite (0) or multicolor sprite (1). (See SPRCOLOR, in paragraph 17.87)

Unspecified parameters in subsequent sprite statements take on the characteristics of the previous SPRITE statement. You can check the characteristics of a SPRITE with the RSPRITE function.

EXAMPLES:

SPRITE 1,1,3

Turn on SPRITE number 1 and color it red.

SPRITE 2,1,7,1,1,1

Turn on SPRITE number 2, color it blue, make it pass behind objects on the screen and expand it in horizontal and vertical directions.

SPRITE 6,1,1,0,0,1,1

Turn on SPRITE number 6, color it black. The first appearing 0 tells the computer display the sprites are in front of objects on the screen. The second 0 and the following 1 tell the C128 to expand the sprite vertically only. The last 1specifies the sprite to be displayed in multicolor mode. Use the SPRCOLOR command to select the sprite's multicolor.

SPRITE 7,,,,1

Set the horizontal expansion of SPRITE number 7 - all other options retain their previous settings.

17.90 SPRSAV

Store a sprite data from a text string variable into a sprite storage area or vice versa.

SPRSAV origin,destination

This command transfers a sprite image from a string variable to a sprite storage area. It can also tranfer data from the sprite storage area into a string variable. Either the origin or the destination can be a sprite number or a string variable but they both cannot be string variables (they both CAN be sprite numbers, however). If you are moving a string into a sprite, only the first 63 bytes of data are used. The rest are ignored, since a sprite can only hold 63 data bytes.

NOTE: SPRSAV sprite, string produces a string in the same format as SSHAPE so that it can be used with GSHAPE to 'fix' a sprite onto hi-res screen. The string will be 67 characters long.

EXAMPLES:

SPRSAV 1,A$

Transfers the image pattern from sprite 1 to the string named A$.

SPRSAV B$,2

Transfers the data from the string variable B$ into sprite 2.

SPRSAV 2,3

Transfers the data from sprite 2 to sprite 3.

17.91 SSHAPE/GSHAPE

Save/retrieve shapes to/from string variables.

SSHAPE and GSHAPE are used to save and load rectangular areas of multicolor or standard bit mapped screen to/from BASIC string variables. The command to save an area of the screen into a string variable is:

SSHAPE string variable, x1, y1 [, x2, y2]

where:

string variable: String name to save data in
x1, y1: Corner coordinates (0,0 through 319,199) (scaled).
x2, y2: Corner coordinates opposite (x1,y1) (default is the PC)

Because BASIC limits strings to 255 characters, the size of the area that can be saved is limited. The string size required can be calculated using one of the following (unscaled) formulas:

L(hi-res) = INT( (ABS(x1-x2) + 1) / 8 + .99) * (ABS(y1-y2) + 1) + 4
L(multicolor) = INT( (ABS(x1-x2) + 1) / 4 + .99) * (ABS(y1-y2) + 1) + 4

NOTE: The upper limits of the coordinates (319,199 for standard and 159,199 for multicolor bit mapped graphics) apply to the unSCALEd coordinate system. When SCALE is turned on, the limit are set by the SCALE command.

The command to retrieve (load) the data from a string variable and display it on specified screen coordinates is:

GSHAPE string variable, [x,y] [,mode]

where:

string

Contains shape to be drawn.

x,y

Top left coordinates (0,0 through 319,199) telling where to draw the shape (scaled), default is the pixel cursor.

mode

Replacement mode:

0: place shape as is (default).
1: invert (reverse) shape.
2: OR shape with area.
3: AND shape with area.
4: XOR shape with area.

The replacement mode allows you to change the data in the string variable so that you can invert it, perform a logical OR, exclusive OR or AND operation on the image.

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

EXAMPLES:

SSHAPE A$,10,10

Saves a rectangular area from the coordinates (10,10) to the location of the pixel cursor, into string variable A$.

SSHAPE B$,20,30,47,51

Saves a rectangular area from top left coordinates (20,30) throught bottom coordinates (47,51) into string variable B$.

GSHAPE A$,120,20

Retrieves shaped contained in string variable A$ and displays it at top left corner at coordinates (120,20).

GSHAPE B$,30,30,1

Retrieves shape contained in string B$ and displays it at top left coordinates (30,30). The shape is inverted due to the replacement mode being selected by the 1.

NOTE: Beware using modes 1-4 with multicolor shapes. You may obtain unpredictable results.

17.92 STASH

Move contents of host memory to expansion RAM.

STASH #bytes, intsa, expsa, expb

Refer to FETCH command for description of parameters.

17.93 STOP

Halt program execution.

STOP

This statement halts the program. A message, BREAK IN LINE xxx occurs (in program mode), where xxx is the line number containing the STOP command. The program can be restarted at the statement following STOP if the CONT command is used immediately, without any editing occuring in the listing. The STOP statement is often used while debugging a program.

17.94 SWAP

Swap contents of host RAM with contents of expansion RAM.

SWAP #bytes, intsa, expsa, expb

Refer to FETCH command for description of parameters.

17.95 SYS/SYS

Call and execute a machine language subroutine at the specified address.

SYS address
(C64 mode)

SYS address [, [a] [, [x] [, [y] [, [s] ] ] ] ]
(C128 mode)

This statement performs a call to a machine code subroutine at the given address in a memory configuration set up according to the BANK command. Optionally, arguments a, x, y and s are loaded into the accumulator, x, y and status registers respectively, before the subroutine is called.

The address range is 0 to 65535 (both inclusive). The program begins executing the machine language program starting at that memory location. Also see the BANK command, in paragraph 17.4.

EXAMPLES:

SYS 40960

Calls and executes the machine language routine at location 40960.

SYS 8192,0

Calls and executes the machine language routine at location 8192 and loads zero into the accumulator.

17.96 TEMPO

Define the speed of the song being played.

TEMPO n

where n is a relative duration between 1 and 255 (inclusive).

The actual duration for a whole note is determined by using the formula given below:

whole note duration = 23.06/n seconds

The default value of n is 8, and note duration decreases with n.

EXAMPLES:

TEMPO 16

Defines the TEMPO at 16.

TEMPO 1

Defines the TEMPO at the slowest speed.

TEMPO 250

Defines the TEMPO at 250.

17.97 TRAP

Detect and handle program errors while a BASIC program is RUNning.

TRAP [line#]

When turned on, TRAP intercepts all error conditions (excluding DOS error messages, but including the {stop} key). In the event of any execution error, the error flag is set and execution is transferred to the line number specified in the TRAP statement.

The line number in which the error occurred can be found by using the system variable EL. The specific error condition is contained in system variable ER. The string function ERR$(ER) gives the error message corresponding to the error condition.

The RESUME statement can be used to resume program execution. TRAP with no line number turns off error trapping. An error in a TRAP routine cannot be trapped, unless it contains a TRAP statement of its own.

EXAMPLE:

100 TRAP 1000
If an error occurs, go to line 1000.

1000 ?ERR$(ER);EL
Print the error message, and the error line number.

1010 RESUME
Resume program execution.

17.98 TROFF

Turn OFF error TRacing mode.

TROFF

This statement turns off trace mode.

17.99 TRON

Turn ON error TRacing mode.

TRON

TRON is used in program debugging. This statement begins trace mode. When you RUN the program, the line numbers of the program appear in brackets before any action for that line occurs.

If you have multistatement lines, the line number will be printed before each statement is processed.

17.100 VERIFY

Verify program in memory against one saved to disk or to tape.

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

This command causes the Commodore 128 to check the program on tape or disk against the one in memory, to determine if the program is really SAVEd. This command is also very useful for positioning a tape so that the Commodore 128 writes after the last program on tape.

VERIFY, with no arguments after the command, causes the Commodore 128 to check the next program on tape, regardless of its name, against the program now in memory. VERIFY, followed by a program name in quotes or a string variable, searches the tape for that program and when found checks it against the program in memory. VERIFY, followed by a name, a comma and a number, checks the program on the device with that number (1 for tape, 8 for disk). The relocate flag is the same as in the LOAD command. It verifies the program from the memory location from which it was SAVEd. (See also DVERIFY, in paragraph 17.34.)

EXAMPLES:

VERIFY "HELLO"

Searches for HELLO on tape, checks it against memory.

VERIFY "HELLO",8,1

Searches for HELLO on disk, then checks it against memory.

VERIFY "LASTFILE"

Searches tape for LASTFILE, checks it, reports an error if there is no match. You can then save you new program after it, without erasing previous programs.

NOTE: If graphic area is allocated or deallocated after a SAVE, VERIFY and DVERIFY will report an error. Technically this is correct. BASIC text in this case has moved from its original (SAVEd) location to another address range. Hence, VERIFY, which performs byte-to-byte comparisons, will fail, even though the program is valid.

17.101 VOL

Define output level of sound.

VOL volume level

This statement sets the volume for SOUND and PLAY statements. VOLUME level can be set from 0 to 15, where 15 is the maximum volume, and 0 is off. VOL affects all voices.

EXAMPLES:

VOL 0

Turns volume off.

VOL 1

Sets volume to its lowest audible level.

VOL 15

Sets volume for SOUND and PLAY statements to its highest level.

17.102 WAIT

Pause program execution until a data condition is satisfied.

WAIT location, mask1 [, mask2]

The WAIT statement causes program execution to be suspended until a given memory address recognizes a specific bit pattern or value. In other words, WAIT can be used to halt the program until some external event has occurred. This is done by monitoring the status of bits in the Input/Output registers. The data items used with the WAIT can be any values. For most programmers, this statement should never be used. It causes the program to be halt until a specific memory location's bits change in a specific way. This is used for certain I/O operations and almost nothing else. The WAIT statement takes the value in the memory location and performs a logical AND operation with the value in mask1. If mask2 is specified, the result of the first operation is exclusively ORed with mask2. In other words, mask1 "filters out" any bits not to be tested. Where the bit is 0 in mask1, the corresponding bit in the result will always be 0 . The mask2 value flips any bits, so that an off condition can be tested as well as an on condition. Any bits being tested for a 0 should have a 1 in the corresponding bit position in mask2. If corresponding bits of the mask1 and mask2 operands differ, the exclusive-OR operation gives a bit result of 1. If the corresponding bits get the same the bit is 0. It is possible to enter an infinite pause with the WAIT statement, in which case the {run/stop} and {restore} keys can be used to recover. WAIT may require a bank command if the memory you wish to access is not in the currently selected BANK.

The following examples are for the C128 mode only. The first example WAITs until a key is pressed on the tape unit to continue with the program. The second example will WAIT until the {shift} key is pressed and then released. The third example will WAIT until either bit 7 (128) is on or bit 4 (16) if off.

EXAMPLES:

WAIT 1,32,32
WAIT 211,1:WAIT 211,1,1
WAIT 36868, 144, 16

(144 and 16 are binary masks. 144=%10010000 in binary and 16 = %10000 in binary.)

17.103 WIDTH

Set the width of drawn lines.

WIDTH n

This command sets the width of lines drawn using BASIC's graphic commands to either single or double width. Giving n a value of 1 defines a single width line; a value of 2 defines a double width line.

EXAMPLES:

WIDTH 1

Set width for graphic commands.

WIDTH 2

Set double width for drawn lines.

17.104 WINDOW

Defines a screen window.

WINDOW top left col, top left row, bot right col, bot right row
[, clear]

This command defines a logical window within the 40 or 80 column text screen. The coordinates must be in the range 0-39/79 for column values and 0-24 for row values. The clear flag, if provided (1), causes a screen-clear to be performed (but only within the limits of the newly described window).

EXAMPLES:

WINDOW 5,5,35,20

Defines a window with top left corner coordinates (5,5) and bottom right corner coordinates (35,20).

WINDOW 10,2,33,34,1

Defines a window with upper left corner coordinates (10,2) and lower right coordinates (33,24). Also clears the portion of the screen within the window as specified by the 1.

NOTE: If you specify a column greater than 39 on a 40-column display you will get an "ILLEGAL QUANTITY ERROR".

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.