| 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 |
SCRATCH fileName [ D fileDrive ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ...
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). Examples:
|