Home > CBM > BASIC > Keywords > Backup
180 Subpages: (divide), (equal), (less), (minus), (more), (multiply), (plus), (power), Abs, And, Append, Asc, Atn, Auto, 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, 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

KeywordAbbreviationToken (hex)Version(s)Classification
BACKUPBA{Shift+C}D24.xCommand and Statement
HEX$HE{Shift+X}D23.5, 7.0Function
BACKUPBA{Shift+C}F63.5, 7.0Command and Statement

 Syntax  
BACKUP D originalDrive [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ... TO D copyDrive [ { , | ON } U unitNumber ] ...
 
ParametersTypeLegal Value(s)Default ValueNote(s)
originalDriveInteger0 or 1Non-literal must be enclosed in parentheses ()
copyDriveInteger 0 or 1  Non-literal must be enclosed in parentheses ().  Should be different than originalDrive.
unitNumberInteger 8 ~ 11 8 Non-literal must be enclosed in parentheses () 
twoCharChar[2] any  Must be two literal characters. 
 
 
 Purpose 
Disk archiving.  Copy an entire disk (or perhaps a partition).

 
 Remarks 
BACKUP copies an entire "disk" from originalDrive to copyDrive.  The backup medium (copyDrive) will be formatted and because this is a destructive operation (to the copyDrive) BASIC will ask "ARE YOU SURE?" in direct mode and the user must enter something beginning with "Y".  BACKUP works without question when used as a statement in a program.
 
This only works for copying disks in the same device (unitNumber).  Many of CBM's disk devices, like the 1541, 1551, 1571, and 1581 only have one drive (i.e., only driveNumber 0 is allowed) and on these devices (and many others) the device will report "31,SYNTAX ERROR,00,00" but BASIC will not complain.  In theory BACKUP could be used to copy one partition to another for devices that support CMD-style commands, however I have never seen this actually work.  It will not work to copy 1581-style partitions (well, on a 1581 anyway).  Even if the device does support the BACKUP command, there are several other errors the device might generate (BASIC does not care); be sure to check the device status with DS or DS$.
 
BASIC does not require that originalDrive to be different than copyDrive, although it doesn't make sense to use the same value for both.  Presumably the device would report an error in such a case.
 
BACKUP permits a unitNumber to be used before or after the TO preposition, although BACKUP applies to only one device (unitNumber).  In fact, you may supply the U parameter an unlimited number of times... the last one wins!
 
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 (not 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 generated.
  
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, 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 may not be repeated). 
 
For BACKUP, the R and I (twoChar) parameters are only allowed before TO, not after.  However, they are ignored by BACKUP.  In particular, the created backup will have the same name and "id" as the original.
 
Like all disk-based commands, BACKUP restricts the "drive/parittion" numbers (originalDrive and copyDrive) to either 0 or 1 which often makes it unusable on a "disk" with multiple partitions.
 
Like all disk-based commands, BACKUP will reset DS$ and set the secret variable "DosFA" to the unitNumber (defaults to 8 if not given).  It also indirectly updates ST.
 
Examples:
BACKUP D0 TO D1 : REM copy disk in drive 0 to drive 1, both in unit 8
BACKUP D0 TO D1,U9 : REM copy disk in drive 0 to drive 1, both in unit 9
BACKUP D0,IH2 TO D1 : REM the "ID" H2 is ignored, the backup will have the same ID as the original
 
 
 Compare With 
 
 Contrast With 
 See Also 
DS, DS$, ON, PRINT#, ST, TO 
© H2Obsession, 2014