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

DCLEAR

Keyword Abbreviation Token (hex) Version(s) Classification
DCLEAR DCL{Shift+E} DB 4.x Command and Statement
VOL V{Shift+O} DB 3.5, 7.0 Command and Statement
DCLEAR DCL{Shift+E} FE 15 7.0 Command and Statement

  Syntax   
DCLEAR [ driveNumber ] [ { , | ON } U unitNumber ] ... [ , ItwoChar ] [ , R ] ... 
 
Parameters Type Legal Value(s) Default Value Note(s)
driveNumber 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. 
 
 
  Purpose  
Initialize media for reading on a specific device.

 
  Remarks  
DCLEAR sends an "initialize" command to the specified (or implied) unitNumber and driveNumber, and then closes all files open on the device (unitNumber), regardless of which driveNumber they are using.  This is similar to CLR, but more specific (only affects one device), and more imporatantly DCLEAR really closes the files (CLR just "forgets" them which can result in corrupted data if any files were open for writing).
 
Most devices that allow media swapping will automatically detect a media change and work without this command.  At least for reading!  For writing, some media may need a one-time special initiialization, often called formatting (see HEADER).  If you just want to close all files on a "disk" device, then see DCLOSE.
 
If 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 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 (ON may do so), 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 last unitNumber is used), and the twoChar parameter which must always be two literal characters (it may not be repeated although it is otherwise ignored). 
 
Assuming the syntax is good, BASIC sends the command known as "initialize" in CBM DOS literature to the device (this updates ST); if the device is not connected and powered-on, DEVICE NOT PRESENT ERROR occurs.  Otherwise BASIC will not complain.  The initialize command basically just tells the drive to re-read the BAM and disk header, as if a new disk were just inserted.  You may want to check the error/status channel with DS or DS$ to ensure the command completed successfully.  Although it usually succeeds, typical errors include no media (like a floppy disk), unformatted media, or (less likely) media in an unknown/incompatible format, or damaged/unreadable media.
 
Like all disk-based commands, DCLEAR restricts the driveNumber to either 0 or 1 which often makes it unusable on a "disk" with multiple partitions.
 
Like all disk-based commands, DCLEAR will reset DS$ and set the secret variable "DosFA" to the unitNumber (defaults to 8 if not given).
 
Examples:
DCLEAR      : REM close all files on unit 8; initialize drive 0
DCLEAR U9   : REM close all files on unit 9; initialize drive 0
DCLEAR U(U) : REM close all files on unit given by variable U; initialize drive 0
 
 
  Compare With  
 
  Contrast With  
  See Also  
DS, DS$, ON, PRINT#ST
© H2Obsession, 2014
Comments