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


Keyword Abbreviation Token (hex) Version(s) Classification
HEADER H{Shift+E} D0 4.x Command and Statement
RDOT R{Shift+D} D0 3.5, 7.0 Function
HEADER HE{Shift+A} F1 3.5, 7.0 Command and Statement

HEADER diskName D fileDrive ] [ { , | ON } U unitNumber ] ... [ , IdiskID] [ , 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 () 
diskID Char[2]  any    Must be two literal characters. 
Media manipulation.  Formats media (for initial use) or deletes all files (for re-use).

HEADER formats a "disk" in (generally) one of two modes.  If the diskID is given, the device will typically perform a "full" or "low-level" format which wipes all information from all blocks on the "disk".  This is often required for floppy disks before than can be used.  Without a diskID, the device typically peforms a "quick" format which simply deletes all files and sub-directories and frees all blocks.  In either case, the diskName gives the "disk" a name which is usually displayed at the top of directory listing.  If a diskID is given, it also typically appears at the top of a directory listing; if not provided, the old value remains.
The diskName 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. 
Depending on the device, the naming rules may be different for diskName as opposed to a typical file name or directory name.  But it is recommended to not use characters that would normally be considered invalid in saving a file name.  Strangly, BASIC does not care if diskName includes wild-card characters, like * and ?, but will give an error with a leading @ (I've never known @ to be a problem with any device).
It is recommended to first perform CATALOG or DIRECTORY to verify the disk is not formatted or does not have files you don't mind loosing before you perform HEADER.  This is quite practical/recommended in direct mode.  In a program however, there is no direct way to determine if the files are important to anyone!  Well, unless you display them to the user and ask...  The reason for the precaution is that a "full" format is unrecoverable.  A quick format may be recovered using special software if no files are written to the disk before you discovered you formatted the wrong disk.
If you want to delete a only a sub-directory, (as opposed to all sub-directories and files), you will probably need to use a special "remove directory" command with the "BASIC 2.0 method" (see PRINT# or documentation on CBM/CMD DOS).  If you want to delete a 1581-partition (a psudo-directory), you can use SCRATCH.
If they 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 format the "disk".  When a program is running, HEADER 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 first character of the new DS$ and generate a BAD DISK ERROR if the character code is 50 or more (this generally corresponds to a DS value of 20 or more, which generally indicates an error by the device during format).  If you get the BAD DISK ERROR, you should print DS$ to see what the error is.  A "bad disk" will usually have a message referring to read/write/verify error, but it may just be the media is write-protected (not really bad), or the name has an invalid character (generally a syntax error message).
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 diskID parameter which must always be two literal characters (it may not be repeated).
Trivia: the HEADER statement is the only disk command which actually uses the two-character parameter (in this case, diskID).  On a practical note, the diskID must immediately follow the the leading "I" character, and there is no way to use a string variable or expression!  If you want to use a variable/expression for the diskID, then you must use the "BASIC 2.0 method" (see PRINT#).
More trivia: the diskID can be any two "characters", even things that would normally cause an error in the middle of a BASIC statement, like mis-matched parentheses "(" and ")", or stray double-quote ("), or a colon (:).  Each "character" may also be a typical (1-byte token) BASIC keyword, or in BASIC 7.0, a 2-byte token can be used for both "characters".  See examples.
Like all disk-based commands, HEADER 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, HEADER will reset DS$ and set the secret variable "DosFA" to the unitNumber (defaults to device 8).
Trivia: this is the only official/standard way to rename a disk.  But since you loose all files in the process, several utility programs have been written that allow you to change diskName or appearantly the diskID.  Such software is often media and device (and sometimes computer) specific, so no examples here.
HEADER "REUSE"     : REM quick format, name disk REUSE on drive 0, unit 8
HEADER "REUSE",U9  : REM quick format, name disk REUSE on drive 0, unit 9
HEADER "FRESH",IH2 : REM full format, disk name 'FRESH' and diskID 'H2'
HEADER "FRESH",I)( : REM full format, disk name 'FRESH' and diskID ')('
HEADER "FRESH",ITHENIF : REM full format, disk name 'FRESH' and diskID [A7][8B]
HEADER "FRESH",IMOVSPR : REM full format, disk name 'FRESH' and diskID [FE][06]
HEADER (N$),U(U)   : REM using variables (on drive 0)
  Compare With  
  Contrast With  
  See Also  
© H2Obsession, 2014