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

BACKUP

Keyword Abbreviation Token (hex) Version(s) Classification
BACKUP BA{Shift+C} D2 4.x Command and Statement
HEX$ HE{Shift+X} D2 3.5, 7.0 Function
BACKUP BA{Shift+C} F6 3.5, 7.0 Command and Statement

  Syntax   
BACKUP D originalDrive [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ... TO D copyDrive [ { , | ON } U unitNumber ] ...
 
Parameters Type Legal Value(s) Default Value Note(s)
originalDrive Integer 0 or 1 Non-literal must be enclosed in parentheses ()
copyDrive Integer  0 or 1    Non-literal must be enclosed in parentheses ().  Should be different than originalDrive.
unitNumber Integer  8 ~ 11  Non-literal must be enclosed in parentheses () 
twoChar Char[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$, ONPRINT#ST, TO 
© H2Obsession, 2014
Comments