| 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 |
HEADER diskName [ D fileDrive ] [ { , | ON } U unitNumber ] ... [ , IdiskID] [ , R ] ...
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 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. Examples:
|