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


Keyword Abbreviation Token (hex) Version(s) Classification
SCRATCH S{Shift+C} D9 4.x Command and Statement
TROFF TRO{Shift+F} D9 3.5, 7.0 Command and Statement
SCRATCH SC{Shift+R} F2 3.5, 7.0 Command and Statement

SCRATCH fileName D fileDrive ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ...
Parameters Type Legal Value(s) Default Value Note(s)
fileName String  1 to 16 characters   Must not begin with @ 
fileDrive Integer 0 or 1 0 Non-literal must be enclosed in parentheses ()
unitNumber Integer  8 ~ 11  Non-literal must be enclosed in parentheses () 
twoChar Char[2]  any    Must be two literal characters. 
Media file manipulation.  Deletes a file(s) in the current directory (unless a path can be included).

SCRATCH deletes a file(s) on a "disk" device.  The parameter fileName usually refers to one specific file, but possibly multiple files if it includes wild-card characters, like "*" or "?".  The file(s) must be on the same drive (fileDrive) of the same device (unitNumber).
If using wild-card characters in the fileName, it is recommended to first perform CATALOG or DIRECTORY using the same fileName; this will (should) list all the files (and only the files) that would be deleted with SCRATCH.  This is quite practical/recommended in direct mode.  In a program it may not be needed, and further, there is no direct way to determine the number of files (or their names) returned by CATALOG/DIRECTORY.
The fileName is required.  If it has more than 16 characters then STRING TO LONG ERROR will be generated instead.  If it has zero characters then MISSING FILE NAME ERROR occurs.  If it begins with an @ character, BASIC generates SYNTAX ERROR (even though the device may allow this). 
Some devices allow the name(s) to be in different directories (have different paths).  Due to the 16-character limitation of BASIC (and the way some devices specify a path) you probably can't include a path in the fileName anyway.  Use the "BASIC 2.0 method" if you need this feature (see PRINT# or documentation on CBM/CMD DOS).
Most devices allow deletion of CBM (1581-partition), PRG, REL, SEQ, and "real" (not GEOS VLIR) USR types of files.  Some devices may not work with REL files or CBM files.  Few devices correctly delete GEOS VLIR files (listed as USR types); often the device will delete them from the directory, but not all blocks associated with the file will be freed.  Few devices (if any) allow a directory to be deleted with SCRATCH; they often need a special "Remove Directory" command.
If the Syntax is correct and BASIC is in direct mode, a prompt "ARE YOU SURE?" appears.  At this point the user must enter something beginning with Y to actually perform SCRATCH.  When a program is running, SCRATCH proceeds without question.
Assuming the Syntax is good, BASIC sends a command to the device (this updates ST) which rarely generates an error at this point (only if the command transmission failed, for example, DEVICE NOT PRESENT).  If it succeeded, BASIC will then read in a new value into DS$ (this indirectly updates DS too).  This is stupid when a program is running because (a) it needlessly halts the program while the device carries out the command and (b) it doesn't even test the result.  In direct mode, BASIC will print the new DS$ which is typically "01, FILES SCRATCHED,nn,00" where 'nn' is typically the number of files deleted.  In either case (program running or not) this will never generate a BASIC error, even if the device reported an error like "WRITE PROTECT".  Of course in a program you may want to print the result of DS$ for the user, or perform some action based on the associated error code, DS.
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 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 (R is ignored and only the last unitNumber is used), and the twoChar parameter which must always be two literal characters (also ignored but may not be repeated). 
Like all disk-based commands, SCRATCH restricts the "drive/parittion" number (fileDrive) to be either 0 or 1 which often makes it unusable on a "disk" with multiple partitions.  On the other hand, many CBM drives (1541, 1551, 1571, 1581) only allow drive 0 (which is the default value).
Like all disk-based commands, SCRATCH will reset DS$ and set the secret variable "DosFA" to the unitNumber (defaults to device 8).
SCRATCH "JUNK"    : REM delete the file named JUNK on drive 0, unit 8
SCRATCH "JUNK",U9 : REM delete the file named JUNK on drive 0, unit 9
SCRATCH "J*"      : REM delete all files beginning with J on drive 0, unit 8
SCRATCH "J??K"    : REM delete all 4-char files beginning with J and ending with K
SCRATCH (N$),U(U) : REM using variables (on drive 0)
  Compare With  
  Contrast With  
  See Also  
© H2Obsession, 2014