Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎

BLOAD

Keyword Abbreviation Token (hex) Version(s) Classification
BLOAD B{Shift+L} DD 4.7 Command and Statement
PUDEF P{Shift+U} DD 3.5, 7.0 Command and Statement
BLOAD B{Shift+L} FE 11 7.0 Command and Statement

  Syntax   
BLOAD fileName [ , D driveNumber ] [ { , | ON } U unitNumber ] ... [ , loadAddress ] [ { , | ON loadBank ] [ , ItwoChar ] [ , R ] ...
 
Parameters Type Legal Value(s) Default Value Note(s)
fileName String  1~16 characters    Non-literal must be enclosed in parentheses () 
driveNumber Integer  0 or 1  Non-literal must be enclosed in parentheses ()
unitNumber Integer  8 ~ 11  Non-literal must be enclosed in parentheses () 
loadAddress Unsigned Integer  0 ~ 65535  from first 2 bytes of file  Non-literal must be enclosed in parentheses ()
loadBank Unsigned Byte 0 to max*  most recent BANK  Non-literal must be enclosed in parentheses ()
*max is 15 on C128, or 255 on CBM-II series
twoChar Char[2]  any    Must be two literal characters. 
 
 
  Purpose  
Memory initialization.  Load a non-BASIC file into memory.

 
  Remarks  
BLOAD is typically used to load a machine-language program or other non-BASIC data into RAM.  Rarely used to load data into I/O registers.
 
The nice thing about BLOAD is you can set a specific loadAddress.  The version 1.0 LOAD can also load a "machine language program" but it always loads to the address stored in the file header (first two bytes of file).  Unfortunately, BLOAD doesn't work with cassette!  In fact it only works with devices (unitNumber) 8 to 11. A minor bug is that you may specify the unitNumber an unlimited number of times; the last value will actually be used.  BLOAD will always specify driveNumber in the command sent to the device (defaults to 0 if you omit it) and so only that drive will be searched for the fileName, but with the original LOAD omitting the driveNumber will cause the device to search both drives (assuming the device has 2 drives).
 
If the fileName has more than 16 characters then STRING TO LONG ERROR will be generated instead.  If the fileName has zero characters then MISSING FILE NAME ERROR occurs.  The fileName may include wild-card characters like ? and *.  If the fileName begins with an @ character, SYNTAX ERROR occurs.
 
Most disk devices will only search for PRG files unless fileName ends with ",type" where type is one of the characters "D", "P", "S", or "U" corresponding to DEL, PRG, SEQ, and USR file types respectively.  However there are two problems with this.  The first is the entire fileName string is limited to 16 characters so adding these 2 characters will cause an error if the "real" filename is 15 or 16 characters in length.  Another problem is a bug in the 1571 and 1581 (maybe some CMD devices) which will ignore the ",type".
 
In direct mode, the messages SEARCHING FOR driveNumber:fileName will be printed.  No message is printed when a program is running.
 
If the fileName does not exist, BASIC will generate FILE NOT FOUND ERROR (a similar message reported by the device will be read into DS$).  Otherwise, in direct mode, the message LOADING will be printed.  Again, no message is printed when a program is running.
 
On most systems, other errors generated by the device while trying to load the file will cause BASIC to "freeze" until the user manually presses STOP at which point BREAK ERROR (or STOP KEY DETECTED) would be generated.  On the C128, however, fast-serial devices can report an error to the computer without this kludgy "freeze".  In this case BASIC will report FILE DATA ERROR.  In either case, you can then get the specific error from the device with DS or DS$.
 
Internally, the loadAddress is incremented after every byte is read from the file.  On the C128, if the new value ever reaches the MMU register at 65280 ($ff00 hexadecimal) then OUT OF MEMORY ERROR is generated and the operation aborts (leaving special internal drive channel open; use DCLEAR or read DS$ to clear this condition).  There are many other addresses that could be reached (on all the various CBM machines) that could cause the system to "crash" in one way or another (this is due to the lack of memory protection in the hardware; it would be very "expensive" to attempt this in software); it is not all bad, for one thing it rarely happens, and for another this has been turned into a "feature" to implement "auto-start programs" in older versions of BASIC.  If everything goes okay, the ending loadAddress + 1 may be PEEK'ed from a secret variable.
 
Unlike LOAD, the use of BLOAD in a program will not cause the program to re-start from the first line number after the load completes.  Unlike LOAD or DLOAD, internal BASIC pointers (i.e., secret variables) are not updated either.
 
If a required parameter is omitted, or an expression (enclosed in parentheses) is not valid, or an expression is used without parentheses, SYNTAX ERROR occurs.  If any parameter is not the correct type (string or numeric) a TYPE MISMATCH ERROR will be generated.  Otherwise if a parameter is not a legal value (see table above), an ILLEGAL QUANTITY ERROR is usually generated (except the previosuly described fileName).
 
Any omitted parameter will take the default value shown above; in particular, unitNumber 8, driveNumber 0.  The default bankValue will be the value used in the last BANK command/statement... not the last bankValue used in a prior disk-command.
 
Like all disk commands and statements, the Syntax is more flexible than shown above.  In particular, the parameters may be given in any order.  The general restrictions are: a comma (,) must not precede the first parameter (the ON presposition may), any non-literal value (a variable name or expression) must be enclosed in parentheses (), and do not supply the same parameter more than once.  Exceptions include the U and R parameters, which may used an unlimited number of times (the R is ignored), and the twoChar parameter which must always be two literal characters (it is ignored too, but it may not be repeated).
 
Like all disk-based commands, BLOAD restricts the driveNumber to 0 or 1 which often makes it unusable on a "disk" with multiple partitions.  Like all disk-based commands, BLOAD restricts the fileName to no more than 16 characters which makes it nearly useless if you want to include a path.
 
Like all disk-based commands, BLOAD will reset DS$ and set the secret variable "DosFA" to the unitNumber.  It also indirectly updates ST.
 
Examples:
BLOAD "BITMAP" : REM disk unit 8, drive 0, current BANK, address in file header
BLOAD "BITMAP", B1, P(AD) : REM unit 8, drive 0, bank 1, address in variable AD
BLOAD (N$),U(U)           : REM use variables for fileName and unitNumber
 
 
  Compare With  
 
  Contrast With  
  See Also  
BANKDS, DS$, GET#, INPUT#ONST, SYS, VERIFY 
© H2Obsession, 2014
Comments