DISKFORMAT()
 Formats disks, controlled through a UDF
------------------------------------------------------------------------------
 Syntax

     DISKFORMAT(<cDrive>, [<nCapacity>], [<cUDF>],
        [<cBootText>], [<nRepetitions>]) --> nErrorCode

 Arguments

     <cDrive>  Designates the disk drive to format.  Only a floppy drive
     is permitted.  You may optionally specify a colon (:).

     <nCapacity>  Designates the appropriate disk capacity for the disk
     you are about to format.  Possible values are 160, 180, 320, 360, and
     1200 for 5.25"; 720 and 1440 for 3.5" disks.  The default is the maximum
     drive capacity.

     <cUDF>  Designates the name of a user-defined function call before
     each format step (track or head change).  The default is no UDF called.

     <cBootText>  This optional parameter designates text, with a maximum
     of 255 characters, to display if the formatted disk is booted.  The
     default is described in the "Notes" section on the following page.

     <nRepetitions>  Designates the number of repeat attempts you should
     make, to format a track before the function aborts.  The default is one
     repetition.

 Returns

     The function returns 0 when the disk is successfully formatted.

     Table 7-5:  DISKFORMAT() Error Codes
     ------------------------------------------------------------------------
     Error Codes  Symb. constants     Definition
     ------------------------------------------------------------------------
      0           NO_DISK_ERROR       Format successful
     -1           DF_WRONG_DRIVE      Illegal drive, only A: and B:  allowed
     -2           DF_WRONG_DISK_SIZ   kB value not supported
     -3           DF_INTERRUPTED      Terminated by control UDF
     -4           DF_WRITE            Write error
     ------------------------------------------------------------------------

 Description

     DISKFORMAT() formats a disk under full CA-Clipper program control, so
     there is no need for a RUN FORMAT.  You cannot create bootable disks,
     only data disks.

     Since you can call a separate function (UDF) prior to every track and
     head change and the respective track and head number are passed, you can
     construct the visual display of the format process constructed as
     desired.

     You can only format floppy disks, so even with unforeseen incorrect
     parameters, your hard disk is safe.  All the standard floppy types are
     supported -- 160kB, 180kB, 320kB, 360kB, 1.2MB, 720kB, and 1.44MB.

     DISKFORMAT() is useful for formatting disks, at least when the preset
     repetition rate is retained or decreased.  After an unsuccessful attempt
     to format a track, the process is repeated one more time.  If this
     repetition also fails, the entire format is aborted.  If you want to be
     as safe as possible about the quality of the disk in used, select a
     repetition rate of 0.

 The Control UDF

     DISKFORMAT() calls the control UDF, which is specified as the third
     parameter, prior to each head and track change.  Both values, head and
     track, are passed as a parameter to the function.  As soon as all tracks
     are formatted and DISKFORMAT() has initialized the FAT and directory
     area, a value of -1 is passed for both parameters to the UDF.  Please be
     aware that both parameters must be passed.

     The numeric value returned for UDF can further influence DISKFORMAT():

     Table 7-6:  Control UDF Returned Values
     ------------------------------------------------------------------------
     Returned Value    Explanation
     ------------------------------------------------------------------------
     0                 Continue format
     1                 Do not format this track (parameter 1)
     2                 Abort format
     ------------------------------------------------------------------------

 Notes

     .  If the defined control UDF does not exist, the function
        uninstalls itself and triggers a runtime error.  If an error message
        concerning a missing procedure is required during linking, you can
        specify EXTERNAL <function> in the program.

     .  If you attempt to boot with a data disk created with
        DISKFORMAT() and did not designate any other text for the <cBootText>
        parameter, the following text is displayed:

         "No system disk.  Insert new disk, press any key to continue"

     .  DISKFORMAT() begins to format a disk with the highest track
        number.  Therefore, an existing FAT and directory label are the last
        items deleted.

     .  DISKFORMAT() always reformats a track, even if it is already
        formatted.  Therefore, when a format is successful, all the data is
        deleted.

     .  Each track is verified again after it is formatted.

     .  After the last track is formatted, the function continues to
        work a few seconds more.  The FAT and directory must be established
        and the boot text must be written.

 Examples

     .  An example for formatting a disk in A: drive:

        DISKFORMAT() first determines whether the desired capacity is
        appropriate for the drive.  The control UDF "CONTROL" is concerned
        with the display of the track and head that are currently being
        formatted.  "This is a data diskette" is used as boot text for the
        disk.  The repeat rate is highly effective at 0.  Only the highest-
        quality disks are accepted.

        To provide an additional example of the return value for the UDF,
        only tracks 80 to 11 are formatted here, not the first 10:

        CLEAR
        cBootText  :=  "This is a data diskette"
        @ 10, 02 SAY "Track:
        "@ 11, 02 SAY "Head:
        "IF FLOPPYTYPE("A:") = 2
                                      // 1.2 MB disk
           nErrCode := DISKFORMAT("A:", 1200", CONTROL", cBootText, 0)
           IF nErrCode = 0
              ? "Format successful!"
           ENDIF
        ENDIF
        RETURN

        FUNCTION CONTROL(nTrack, nHead)
           LOCAL nRetval
           IF Track >= 11
              @ 10, 08 SAY STR(nTrack)
              @ 11, 08 SAY STR(nHead)
              nRetval := 0            // Continue format
           ELSE
              nRetval := 2            // Abort
           ENDIF
           RETURN(nRetval)

     .  Shown below is another variation of the UDF.  Press the ESC
        key to abort the format.  If the format is completed, then the
        function displays the FAT initialization and root directory:

        FUNCTION CONTROL(nTrack, nHead)
           LOCAL nRetval
           IF INKEY() = 27
              nRetval := 2            // Abort
           ELSE
              nRetval := 0            // Continue format
           ENDIF
           IF nTrack = -1
              @ 10, 10 SAY "Initializing FAT and Root Directory!"
           ENDIF
           RETURN(nRetval)