Transmit the BASIC program in memory to a "file" on a device.
 

For a deviceNumber of 4 or greater, the fileName must be 1 or more characters or a MISSING FILE NAME ERROR occurs.  Generally only mass-storage devices like disk-drives will work correctly (for example, SAVE to a printer usually doesn't work).  Most storage devices generally limit the filename to 16 characters, although the fileName parameter might be longer to allow for additional parameters (such as drive or partition number).

 

For a cassette, fileName is optional.  If the fileName is longer than 187 characters, only (!) the first 187 characters will be saved.

 

Most CBM machines allow only 1 cassette in which case specifiying a deviceNumber of 2 will generate ILLEGAL DEVICE NUMBER.  Some modified CBMs (in particular those with JiffyDOS) will give the same error with a deviceNumber of 1 as well.  The same error is generated if a deviceNumber of 0 (keyboard) or 3 (screen) is requested.

 

Otherwise, an ILLEGAL QUANTITY ERROR is generated if either the deviceNumber or flags is less than 0 or greater than 255.

 

If the device is a cassette, and no buttons are detected as pressed, the KERNAL will print PRESS PLAY & RECORD ON TAPE.  The user may do that (typically desired) or accidentaly (usually) press only PLAY on the cassette device.  Either action will cause the SAVE to proceed (but no data will be saved if the user pressed only PLAY).  As an alternative, the user may press the STOP key which generates a BREAK ERROR.

 

If an error has not happened yet, and BASIC is not running a program, the KERNAL will print SAVING fileName.

 

Now, if the deviceNumber mod 32 is 31 the KERNAL will hang the system; otherwise if the deviceNumber is greater or equal to 4 and deviceNumber mod 32 does not respond (in approximately 1 millisecond) a DEVICE NOT PRESENT ERROR is generated.

 

The cassette is not capable of generating an error while saving (although errors may occur).  An IEEE or slow-serial IEC device also has no "official way" to report an error; it generally just stops accepting data and the system will be "stuck" trying to transmit the remainder of the program; the user needs to press the STOP key to regain control.  A fast-serial device may signal an error to the C128, which aborts the SAVE operation, but no error is reported by BASIC (further investigation needed!).

 

Pressing the STOP key while the program is being transmitted to the device will generate a BREAK ERROR.

 

After the program has been completely transmitted (presumably saved on some storage medium), and if the device is a cassette, and if flags is an odd number, then an end-of-tape marker will be written to the cassette.

 

Unless the version of BASIC supports BSAVE, there is no "official" way to SAVE an arbitrary range of memory (such as BASIC variables or ML program that was POKE'd into memory).  Generally the user will need to call the KERNAL with an SYS command.

 

Examples:

SAVE         : REM store the BASIC program in memory to an un-named cassette file
SAVE "",1,1  : REM the same thing, but also write an end-of-tape marker
SAVE "MFILE",8  : REM store the BASIC program as "MYFILE" on the default drive/partion of device 8
SAVE "1:MYFILE",8 : REM the same thing, but use drive/partition 1 instead
SAVE "MYFILE,S",8 : REM store the BASIC program onto disk as a SEQ file (instead of a PRG file)

 

BSAVE, DSAVE, LIST, STASH

 

BLOAD, DLOAD, FETCH, LOAD, NEW, SCRATCH
 

DVERIFY, SWAP, VERIFY