| Home CBM ASCII-X BASIC Disk Commands Enter RUN mode Program Format Secret Variables Variable Format Expressions Keywords (divide) (equal) (less) (minus) (more) (multiply) (plus) (power) Abs And Append Asc Atn Auto Backup Bank Begin Bend Bload Boot Box Bsave Bump Catalog Char Chr Circle Close Clr Cmd Collect Collision Color Concat Cont Copy Cos Data Dclear Dclose Dec Def Delete Dim Directory Dispose Dload Do Dopen Draw Ds Ds string Dsave Dverify El Else End Envelope Er Err Exit Exp Fast Fetch Filter Fn For Fre Get Get num Getkey Go Gosub Goto Graphic Gshape Header Help Hex If Input Input num Instr Int Joy Key Left Len Let List Load Locate Log Loop Mid Monitor Movspr New Next Not Off On Open Or Paint Peek Pen Pi Play Pointer Poke Pos Pot Print num Pudef Quit Rclr Rdot Read Record Rem Rename Renumber Restore Resume Return Rgr Right Rlum Rnd Rreg Rspcolor Rsppos Rsprite Run Rwindow Save Scale Scnclr Scratch Sgn Sin Sleep Slow Sound Spc Sprcolor Sprdef Sprite Sprsav Sqr Sshape St Stash Step Stop Str Swap Sys Tab Tan Tempo Then Ti Ti string To Trap Troff Tron Until Using Usr Val Verify Vol Wait While Width Window Xor Syntax Tokens C128 D64plus Disk Escape Codes Hardware PCxface PETSCII Pet2asc Futurama IBM PC-AT Contact Games Glossary Hall of fame Hall of shame Miscellaneous Privacy policy Programming Twisty puzzles |
DLOAD fileName [ , D driveNumber ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ...
Memory initialization. Load a BASIC program from a "disk" file into memory.
DLOAD is used to load a BASIC program into RAM from a device on the IEEE/IEC bus. The device is identified by unitNumber (default 8) and is typically a disk drive or other mass-storage device. Although values 0 to 30 are valid for an IEEE/IEC device number, DLOAD limits unitNumber to the range 8 to 11 (CBM disk drives typically use values in this range). Note the unitNumber may be given more than once; only the last one is actually used. Some devices may support more than one physical disk (typically floppy disks) or allow multiple partitions on the same disk (typically a hard drive). These multiple "disks" on the same device are identified by a driveNumber (default 0). Although several mass-storage devices allow driveNumber to range from 0 to 255, DLOAD limits the value to either 0 or 1. Several of the most popular CBM disk devices (1541, 1551, 1571, and 1581) only allow 0. Note that 1581 partitions are not selected by driveNumber. The fileName is required; it specifies the name of the "disk" file to load. If the fileName has more than 16 characters then STRING TO LONG ERROR will be generated. 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. If the fileName is a single asterisk (*) then most devices will load the last-referenced fileName (used with that device) or the first file in its directory if no files have been accessed since the device was powered-on or a media change (disk swap) occurred. 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" when used with a computer supporting fast-serial bus protocol (typically only the C128, but possible with a hacked C64). 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). 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 parameter is ignored), and the twoChar parameter which must always be two literal characters (it is ignored too, but it may not be repeated). Now we'll assume the Syntax is correct. In direct mode, the message 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 the first two bytes of the file will be read and discarded (the starting address from which it was saved). The secret variable loadAddress will be set, instead, to the value of another secret variable, "Start of BASIC". Next, in direct mode, the message LOADING will be printed. 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 LOAD 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). Now we'll assume the program file was loaded successfully into RAM. At this point, the secret loadAddress will pointing to the address one byte beyond the the last byte that was read from the file; we'll call this the "End Address" (it is another secret variable that may be PEEK'ed later). On machines with more than 64K of RAM, the "End Address" is simply copied to a secret variable "End of Program". On machines with 64K or less RAM the "End Address" is compared with another secrect variable "End of BASIC"; if the "End Address" is greater then an OUT OF MEMORY ERROR occurs. Otherwise (64K or less machine), if a program is not running, the "End Address" value is copied to the another secret variable, "Start of Variables" (this is equivalant to "End of Program" in machines with more RAM). Next (in version 2+) BASIC will attempt to re-link the data that was loaded into RAM. This is needed in case the current "Start of BASIC" is different than the one used when the program was saved. If the loaded data was not actually a BASIC program, or perhaps the data was corrupt, the re-linking may cause the computer to "freeze" or soft-reset. In BASIC 1, the program is not re-linked and will only work if it was saved from address 1025 (hexadecimal $401). If a program is not running, and regardless of the amount of RAM in the system, BASIC will next call CLR. This is needed in systems with 64K or less RAM to adjust other secret variables, like "Start of Arrays" and "End of Strings". On systems with more than 64K, this is not needed (variables are in a different bank) and in fact is EXTREMELY annoying. Not only does CLR wipe out all work you put into creating your variables, but it also "forgets" all open files. This is not the same as a real CLOSE. In fact, any file opened for writing has effectively been destroyed! There is no way to CLOSE it because BASIC forgot all about it. (You can use the CLOSE command, but nothing will happen). A serious bug, I say. *DLOAD may be used as a statement in a program, but it behaves a bit differently. It has the potential for bugs (different from the CLR problem mentioned above). If a program is running, CLR is not called and the newly-loaded program will start from the first program line. This allows program chaining. However on machines with 64K or less RAM, if the newly-loaded program is larger than the original program that issued DLOAD, some of the BASIC variables will have been destroyed. Worse, because CLR was not called to update the secret variables dealing with variables, the newly-loaded program may destroy the end of itself by writing variables. Other bugs exist with program chaining. For one, TRAP and COLLISION are not disabled. This means, should an error or enabled video event occur, BASIC will go to a "random" program line or generate UNDEF'D STATEMENT ERROR. This is easy to avoid by using the same program lines for TRAP/COLLISION in the newly-loaded program as was active in the original, or the original program can disable TRAP and COLLISION before using DLOAD. Another problem is user-defined functions (see DEF) that were created in the original program will not work in the newly-loaded program unless (very lucky) they appear at the exact same position in RAM. This can be fixed by re-defining the needed functions in the newly loaded program. If a program is running and you do not want to perform program chaining (i.e., you want CLR to be called) then there are three options. If the machine has more than 64K RAM, the newly-loaded program only needs to use CLR (preferably at the beginning of the program). A second option, for machines with 64K or less is to manually POKE the "End Address" into the "Start of Variables" and then perform CLR (at the start of the newly-loaded program). A final option (no matter RAM size) in the original program that uses DLOAD, is to perform some indirection: PRINT the commands DLOAD and RUN on the screen. Stuff 2 carriage-returns into the keyboard buffer and the value 2 into keyboard-use, position the text cursor over DLOAD and end the program. BASIC will then execute those PRINT'ed statements like they were entered in direct mode. An ugly kludge, but I've seen several programs do this. The main problem is this relies on several secret variables which vary between machines. Like all disk-based commands, DLOAD restricts the driveNumber to 0 or 1 which often makes it unusable on a "disk" with multiple partitions. Like all disk-based commands, DLOAD 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, DLOAD will reset DS$ and set the secret variable "DosFA" to the unitNumber. It also indirectly updates ST. Examples:
|