workbench/system/BHFormat/design.txt

   1 Overview:
   2
   3 On startup, Format will test whether it has been started with CLI or
   4 Workbench arguments.  In the former case, it will run a procedure that
   5 uses standard file streams for interaction with the user.  In the
   6 latter, it will run a procedure that uses one or more windows for
   7 interaction.  These procedures will use common functions for the
   8 actual formatting / file-system functionality.  Errors will be
   9 reported to the user by the functions that detect them, through a
  10 single function that combines a severity level with a system error
  11 code and/or specific error text.  Error messages will be displayed on
  12 the standard error stream if the program is started with CLI
  13 arguments, and in an `easy request' window if it started with
  14 Workbench arguments.
  15
  16 Functions:
  17
  18 int rcCliMain(void)
  19
  20 Read and validate CLI arguments.  Open the drive.  Confirm the command
  21 - abort on Ctrl-C or continue on Return.  Format and verify each
  22 cylinder if required; display progress messages and abort on Ctrl-C.
  23 Make a new file-system and create icon(s) if required.
  24
  25 int rcGuiMain(void)
  26
  27 Open a window.  Display a device selection list if no disks were given
  28 as Workbench arguments.  Display gadgets for specifying the other
  29 arguments.  Validate all input.  If user chooses to continue, open the
  30 drive and confirm the command.  If user confirms, format and verify
  31 each cylinder if required; display a Cancel button and a progress bar;
  32 update the progress bar after each cylinder and abort if the user
  33 selects the Cancel button.  Make a new file-system and create icon(s)
  34 if required.
  35
  36 void ReportErrSz( ErrorType ert, LONG err, const char * pszMessage, ... )
  37
  38 Report an error condition.  The error may be described by DOS error
  39 code err with pszMessage equal to 0, or by DOS error code err and
  40 additional string pszMessage, or by string pszMessage with err equal
  41 to -1.  If err is 0 then the result of IoErr() will be used in its
  42 place.  The error is indicated as a warning, error or failure
  43 depending on the value of ert.  The string pszMessage is used as a
  44 format string for RawDoFmt, with any additional arguments used as
  45 format arguments.
  46
  47 BOOL bSetSzVolumeFromSz( const char * pszVolume )
  48
  49 Validate volume name pszVolume; if it is valid make it the effective
  50 volume name and return TRUE; otherwise return FALSE.
  51
  52 BOOL bSetSzDosDeviceFromSz( const char * pszDevice )
  53
  54 Validate DOS device name pszDevice; if it is valid make it the
  55 effective DOS device name and return TRUE; otherwise return FALSE.
  56
  57 BOOL bSetFstFromSz( const char * pszFileSysType )
  58
  59 Validate file-system type (DosType) string pszFileSysType; if it is
  60 valid set the effective file-system type accordingly and return TRUE;
  61 otherwise return FALSE.
  62
  63 BOOL bSetDevfFromSz( const char * pszDevFlags )
  64
  65 Validate device flags string pszDevFlags; if it is valid set the
  66 effective device flags accordingly and return TRUE; otherwise return
  67 FALSE.
  68
  69 BOOL bGetDosDevice(void)
  70
  71 Attempt to lock the DOS list, if it is not already locked, and find
  72 the DOS list entry for the device to be used.  Check that its settings
  73 are safe; warn about any that we can work around and fail if we can't.
  74 If everything is successful return TRUE; otherwise return FALSE.
  75 bSetSzDosDeviceFromSz must have been called successfully before this
  76 is called.
  77
  78 BOOL bGetExecDevice( BOOL bWillVerify )
  79
  80 Inhibit the DOS device.  Attempt to open the underlying Exec device,
  81 and test that it supports NSD 64-bit trackdisk commands if they will
  82 be needed.  Attempt to allocate and initialise buffers for disk
  83 access.  bWillVerify indicates whether verification will be done; if
  84 it is FALSE then no read buffer is needed.  If everything is
  85 successful return TRUE; otherwise return FALSE.  bGetDosDevice must
  86 have been called successfully before this is called.
  87
  88 BOOL bFormatCylinder( ULONG icyl )
  89
  90 Attempt to format a cylinder of the disk.  Return TRUE if successful;
  91 FALSE if not.  bGetExecDevice must been called successfully before
  92 this is called.
  93
  94 BOOL bVerifyCylinder( ULONG icyl )
  95
  96 Attempt to read a cylinder of the disk and compare it with the data
  97 previously written.  Return TRUE if reading is successful and the data
  98 read matches what was written, FALSE otherwise.  bFormatCylinder must
  99 have been called previously, and the last call must have specified the
 100 same cylinder and been successful.
 101
 102 void FreeDosDevice(void)
 103
 104 Unlock the DOS list and uninhibit the DOS device.
 105
 106 void FreeExecDevice(void)
 107
 108 Free disk buffers and close the Exec device.
 109
 110 BOOL bMakeFileSys( BOOL bFFS, BOOL bOFS, BOOL bIntl, BOOL bNoIntl,
 111                    BOOL bDirCache, BOOL bNoDirCache )
 112
 113 Inhibit the DOS device, if it is not yet inhibited.  Make a
 114 file-system on it.  If the DOS device's current file-system type is a
 115 standard Amiga file-system (DOS\0-DOS\5) and bSetFstFromSz has not
 116 been used to set a specific type, then the current type will be
 117 modified according to the various flags given as arguments.  The rules
 118 used are identical to those used by Commodore-Amiga Format version 40.
 119 Uninhibit the DOS device.  Return TRUE if successful; FALSE if not.
 120 bGetDosDevice must have been called successfully before this is
 121 called.