| 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 |
BSAVE fileName , P startAddress [ , D driveNumber ] [ { , | ON } U unitNumber ] ... [ { , | ON } B saveBank ] [ , ItwoChar ] [ , R ] ... TO P limitAddress [ { , | ON } U unitNumber ] ... [ { , | ON } B saveBank ] [ , R ] ...
Memory export. Save a region of "memory" to a "disk file".
BSAVE is typically used to save a machine-language program or other non-BASIC data from RAM to a disk file. Rarely used to save ROM or I/O registers. The device specified by unitNumber decides what actually happens to the data. It is typically saved in a file on some storage medium (like a floppy disk), but the device could do anything with the "memory", like print it on paper, or insert it into a database (I've never seen a device do this). BSAVE is really nice because in older versions of BASIC there is no way to SAVE anything except a BASIC program (without resorting to machine-specific POKEs and SYSs). Unfortunately, BSAVE doesn't work with cassette! In fact it only works with devices (unitNumber) 8 to 11. If the fileName has more than 16 characters (or 17 characters if it begins with @) then STRING TO LONG ERROR will be generated instead. If the fileName has zero characters then MISSING FILE NAME ERROR occurs. 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. 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. A lot of controversy has surrounded this bug; several "experts" even proclaimed the bug does not exist. Many CBM users (like myself) can testify the bug does exist. The reason for the controversy (in my opinion) is because it is not easy/reliable to trigger the bug. There have been several "solutions" proposed, like always include a drive# with every command (this does not help), and CBM claimed they fixed it in the 1571 but that device bit me with the bug too. It seems the root cause / unreliability 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; it depends on the number of free internal buffers of the device and the number of retry operations. 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. The fileName should not include wild-card characters like ? and *. BASIC will not complain, but most disk devices will report something like "33,SYNTAX ERROR,00,00" and nothing is saved. Most disk devices will save 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 loading. In direct mode, the message SAVING driveNumber:fileName will be printed. No message is printed when a program is running. The startAddress is sent as the first two bytes to the device (low byte first). Next all "memory" in the the computer from startAddress to limitAddress-1 is written to the device. In other words, the parameter limitAddress should be set equal to the desired endAddress + 1. The limitAddress must be greater than the startAddress or an ILLEGAL QUANTITY ERROR occurs. The data will be saved from the specified saveBank or, if omitted, the last value used in a BANK command/statment. You can specify the saveBank either before or after the TO preposition, but not in both places (that will generate SYNTAX ERROR). The driveNumber (default 0) and the (ignored) ItwoChar parameter may only appear before the TO preposition, otherwise you get SYNTAX ERROR. The unitNumber (default 8) may appear before or after the TO preposition. In fact, it may given an unlimited number of time; only the last value will be used. The dummy , R parameter may be repeated an arbitrary number of times, either before or after the TO preposition. 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. 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 (R is ignored), and the twoChar parameter which must always be two literal characters (even though it is ignored for BSAVE). Like all disk-based commands, BSAVE restricts the driveNumber to 0 or 1 which often makes it unusable on a "disk" with multiple partitions. Like all disk-based commands, BSAVE 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, BSAVE will reset DS$ and set the secret variable "DosFA" to the unitNumber. It also indirectly updates ST. Examples:
|