Transfer "file" data into computer "memory".
 

For deviceNumber of 4 or greater, the fileName must be at least one or more characters or a MISSING FILE NAME ERROR occurs.  Generally only mass-storage devices like disk-drives will work correctly (for example, LOADing from a printer usually doesn't work).  Most devices that do support LOAD 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, the KERNAL will print PRESS PLAY ON TAPE if no buttons are detected as pressed.  For a cassette, fileName is optional.  If not specified, the KERNAL will pause for each program file it finds and report FOUND fileName, at which point the user may press the C= key to load that file or press the spacebar (or wait a few seconds) to continue searching for a file.  If the fileName is longer than 187 characters, only (!) the first 187 characters will be tested.

 

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 an error has not happened yet, and BASIC is not running a program, the KERNAL will print SEARCHING FOR fileName or simply SEARCHING, depending wether or not the length of the  fileName parameter is greater than zero.

 

Now, if the deviceNumber mod 32 is 31 or greater, the KERNAL will hang the system.  Otherwise, if the deviceNumber is greater or equal to 4 and deviceNumber mod 32 does not respond on the IEEE/IEC bus (within about 1 millisecond) then a DEVICE NOT PRESENT ERROR occurs.  Otherwise, if the device is a storage device (like a floppy disk), then usually a fileName that begins with $ will load a listing of the device's current directory (formatted as a BASIC program).

 

If the an end-of-tape marker is found (cassette) or the IEEE/IEC device does not return a two-byte start address, then a FILE NOT FOUND ERROR is generated.

 

Next, if a program is not running, the message LOADING is displayed.  If the flags is an even number, the file will be loaded at BASIC's secret start-of-text address (and after loading the "program" it will be re-linked for the correct address, except in v1.0).  If the flags is an odd number, the file will be loaded starting at the address stored at the beginning of the file (generally, the address it was saved from) but no re-linking will be done after loading the file.

 

While loading the file, device-specific errors may occur.  For cassette this is generally an unrecoverable parity error, and a LOAD ERROR will be generated.  For most IEEE/IEC devices there is no error reported, the system just appears to hange until the user presses the STOP key.  In v7.0, a fast-serial device may generate a LOAD ERROR without the user needing to press STOP.  If the user presses the STOP key while the file is loading, a LOAD ERROR is generated (wether or not the device actually had an error).

 

On the C128, the KERNAL will abort loading if the next address to be loaded after reading a byte from the device would be 65280 (FF00 hexadecimal), and BASIC will report LOAD ERROR.  No other checks on the load address are performed on any CBM machine (that I know about).  Thus loading beyond the "top-of-memory" or past the 64K limit or into the CPU stack or into the I/O registers is possible (and often fatal).

 

Once all the file data has been (successfully) loaded, BASIC will update its secret variable "end-of-program" which on systems with 64K or less RAM is actually the secret "start-of-variables".  Note the "start-of-variables" is only updated if LOAD was executed as a command in direct mode (in RUN mode, this secret pointer is unchanged to allow "program chaining").  In this case, BASIC performs CLR after updating the "start-of-variables" which resets the other secret variables "start-of-arrays" and "end-of-strings".  Strangely, on systems with more than 64K of RAM, CLR is also performed when LOAD is used in direct mode, although it is not needed (and in fact is EXTREMELY annoying, I call it a serious bug).

 

If the flags was an even number (and BASIC is v2+) then BASIC will attempt to re-link the (presumably) BASIC program that was loaded.  If the file was not a BASIC program, or the data was corrupted, the computer may crash at this point.

 

If BASIC is in Run Mode, execution resumes at the first statement in the program (regardless of the flags).

 

Unless the version of BASIC supports BLOAD, the only "official" way to load a machine-language program or raw data into memory (we'll call this a non-BASIC file) is by using LOAD and specifiying a flags value with an odd number.  Unfortunately BASIC doesn't give much thought to the flags value.  For example, after loading a non-BASIC file, a running program will restart from the beginning (this should only happen if a new BASIC program was loaded).  And if a BASIC program is not running, loading a non-BASIC file will update the start-of-variables and perform CLR.  For these reasons, a machine lacking BLOAD may need to resort to some tricks, like calling the KERNAL with an SYS command.

 

* Similarly (oppositely?) when loading a BASIC program (i.e., using an even flags value) other tricks may be needed.  In particular, if one program wants to load another program, but doesn't want the side-effects of "program chaining" to occur (i.e., failure to update the start-of-variables), then tricks will be needed.  A common technique in this case is to print a RUN command on the screen, above that print a LOAD command on the screen, position the text cursor above all that, stuff two carriage returns into the keyboard buffer, and END the program.  At which point BASIC will return to direct mode and execute the commands printed on screen.  Can you say K-L-U-D-G-E ?  Good, I knew you could!

 

Examples:

LOAD         : REM any 'BASIC' program file on cassette
LOAD "",1    : REM any 'BASIC' program file on cassette
LOAD "*",8   : REM (typically) the first 'BASIC' program on a disk
LOAD "*",8,1 : REM (typically) the first 'ML' program on a disk

 

For an IEEE/IEC device, the fileName may include device-specific parameters in addition to the "real filename".  Examples:

LOAD "1:MYFILE",8 : REM read "MYFILE" from drive/partition 1 on device 8
LOAD "/MYDIR/:MYFILE",8 : REM read "MYFILE" from "MYDIR" on device 8 (default drive/partition)
LOAD "MYFILE,S",8,1   : REM load a SEQ-type file as a non-BASIC file

Note the last example will fail on the C128 when used with most fast-serial devices (at least the 1571 [in 1571 mode] and 1581), assuming the program is stored on disk as SEQ-type file.  If there happens to be a normal PRG-type file on the disk (in which case it is probably the wrong file), the last example would "succeed" on the C128.  This is due to a bug in the 1571 ROM which was duplicated in the 1581.  My fast-serial upgrade for uIEC does not suffer this problem.  Behavior of CMD devices is not yet tested by me.

 

BOOT, BLOAD, CATALOG, DIRECTORY, DLOAD, FETCH, NEW, RUN

 

END, BSAVE, DSAVE, STASH
 

SAVE, VERIFY