| 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 |
DSAVE fileName [ , D driveNumber ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ...
Memory export. Save the BASIC program in memory to a "disk file".
DSAVE is used to store the BASIC program in RAM to a "file" on 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, DSAVE 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, DSAVE 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 to use for the file in the device's "directory". If the fileName has more than 16 characters (or 17 characters if it begins with @) then STRING TO LONG ERROR will be generated. If the fileName consists soley of @, then it will be saved as "@driveNumber" ... this is a bug in BASIC which should generate MISSING FILE NAME ERROR. If the fileName has zero characters then MISSING FILE NAME ERROR occurs. The fileName should not include wild-card characters like ? and *, because, although BASIC will not complain, the typical device will report something like "33, SYNTAX ERROR,00,00". The exceptions dealing with the @ character are used to invoke a "safe" save method when the file already exists on the "disk". The concept is the device will save the new version of the file and once complete the original is deleted. It is suppose to be "safe" because if some "disaster" occurred while saving (for example, loss of power) the original file would still be intact. Unfortunately due to a bug in 1541, 1571 (and probably 1551) this can actually cause the disk to become corrupt (it begins with a corrupt BAM, which later leads to "random" corruption elsewhere). This is the so-called Save-with-Replace bug. It seems the root cause is due to "bad sectors". Most disk drives will automatically retry writing a sector that failed an internal verify operation. This retry is what opens the door to the bug. Because this is an internal operation, you will never know the bug snuck in unless the retry fails repeatedly until the drive gives up and reports a write error. Even when a "bad sector" / retry operation happens, this does not guarantee the bug will strike. In my opinion, the best way to avoid the bug on the 15x1 drives is to use 100% perfect media with 100% reliable hardware. Yeah right. Another impractical solution is to always follow each Save-with-Replace with COLLECT (but this can take the drive quite a while to complete). Even if you trust your media and device, another problem is at one point (when the replacement file is saved but before the original has been deleted) there will be two full copies on the disk. This can cause DISK FULL errors (even though this would not happen with only one of the two versions stored on disk). So most people avoid Save-with-Replace. Do what you want, but I thought you should know the story. Most disk devices will save the program to a PRG-type file unless fileName ends with ",type" where type is one of the characters "P", "S", or "U" corresponding to 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 (assuming no leading @) so adding these 2 characters will cause an error if the "real" filename is 15 or 16 characters in length. 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 (for DSAVE, it is ignored too, but it may not be repeated). In direct mode, the message SAVING driveNumber:fileName will be printed. No message is printed when a program is running. The current secret variable "Start of BASIC" is sent as the first two bytes to the device (low byte first). Next all RAM in the the computer from "Start of BASIC" up to (but not including) the "End of Program" or "Start of Variables" (when the computer has more than 64K RAM or not, respectively) is sent to the device. The value of ST is updated in this process. If an error occurs in the device while saving it usually will not be detected by BASIC. Be sure to check DS or DS$ for an error. Common errors include "63,FILE EXISTS,00,00", "26, WRITE PROTECT ON,18,01", and others like write error or disk full. About the only exception is if the device looses power, in which case you will get DEVICE NOT PRESENT. Like all disk-based commands, DSAVE restricts the driveNumber to 0 or 1 which often makes it unusable on a "disk" with multiple partitions. Like all disk-based commands, DSAVE restricts the fileName to no more than 16 characters (17 if starting with @) which makes it nearly useless if you want to include a path. Like all disk-based commands, DSAVE will reset DS$ and set the secret variable "DosFA" to the unitNumber. It also indirectly updates ST. Examples:
|