Formats disks, controlled through a UDF

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


     <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


     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


     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

     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


     .  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

     .  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.


     .  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:

        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!"

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

     .  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
              nRetval := 0            // Continue format
           IF nTrack = -1
              @ 10, 10 SAY "Initializing FAT and Root Directory!"


Introduction Disk Utilities

Fundamental to the disk functions

 Fault tolerance and more

     One of the biggest problems in stable application development is how to
     handle errors.  Errors that occur during hard or floppy disk operations
     are especially frustrating.  You may also encounter critical errors,
     which disable the program or operating system.  The result, known to all
     Clipper programmers, are the DOS error choices:  (A)bort, (R)etry,

 Avoiding Errors

     Error trap functions allow you to react to this type of error, but a
     strategy to avoid them completely is better.  Therefore, Clipper
     Tools includes functions to make it easier to handle floppy and hard
     disk errors.

 Backup Systems

     Backup systems, another component of the Clipper application, are
     also discussed in this chapter.  The recursive FILESEEK() system, which
     allows you to format disks with DISKFORMAT(), is particularly useful.
     Complete directories can be scanned recursively, and queries regarding
     detailed information for every file can be made.  The ideal time to
     carry out this process is during source and target drive back ups,
     because only the information that has changed is copied.

     To avoid the annoying and not particularly fault-tolerant "RUN FORMAT",
     you can format the file disks directly from the application in all
     commonly available formats.  Since the control UDF for DISKFORMAT() uses
     a concept similar to DBEDIT(), you can display the format procedures on
     the screen as desired.

     You can also determine a good deal of varied information about disk
     drives, files, and other things.  This information far exceeds that of
     the FILESEEK() system.

 File Attributes

     Following is the coding for each function where a file can be

     Table 1:
     Value   Symb. constants     Assigned attribute
     0       FA_NORMAL
     1       FA_READONLY         READ ONLY
     2       FA_HIDDEN           HIDDEN
     4       FA_SYSTEM           SYSTEM
     8       FA_VOLUME           VOLUME
     16      FA_DIRECTORY        DIR
     32      FA_ARCHIVE          ARCHIVE

     If multiple attributes are implemented for a file, then the table
     values are added accordingly.  For example, if the HIDDEN and SYSTEM
     attributes are implemented, the function must pass a 6 (2 + 4) as the
     attribute mask.

     All file attributes do not behave the same.  To initiate a file into the
     process, you must explicitly specify the HIDDEN, SYSTEM, VOLUME and DIR
     attributes.  However, if either no attribute, R/O, or ARCHIVE is
     implemented with a file, it does not matter which value is passed.
     These rules for attribute handling are grounded in DOS, which compares
     the specified value with the actual file attributes in this way.  Since
     in some circumstances this may lead to problems, the FILESEEK() function
     allows you to switch on an additional EXACT ATTRIBUTE MATCHING.

 Share Modes

     For DOS version 3.0 or higher, if a function uses the DOS OPEN FILE call
     internally, it must pass a share mode.  This way, one station determines
     how all other stations in the network can access the open file. This is
     valid for as long as the file remains open.  The following variations

     Table 3:  Share Mode
     Code    Symb. constants     Share Modes
     0       SHARE_COMPAT        Compatibility mode.  Here, DOS or the
                                 network software itself, determines the
                                 share mode.  In Novell networks, the
                                 SHAREABLE attribute plays an important role
                                 in this relationship.
     1       SHARE_EXCLUSIVE     Both read and write by other programs are
                                 locked out
     2       SHARE_DENYWRITE     Write by other programs are locked out
     3       SHARE_DENYREAD      Read by other programs are locked out
     4       SHARE_DENYNONE      Not locked.  Read and write by other
                                 programs is allowed

     With the basic setting, all files are opened in the compatibility mode
     (relating to older DOS).  As a rule, the share mode depends on file
     attributes or the network software setting.

     Also in this chapter is the SETSHARE() function, which determines the
     share mode that enables all Clipper Tools functions to open a file.
     Clipper commands or functions are not affected in any way.


     Use the CSETSAFETY() function as a safety switch to protect existing
     files from unwanted overwriting during file operations with Clipper
     Tools functions.  You will find this function in the chapter on Switches
     and Status Information, since it concerns all Clipper Tools file

Tools — Disk Utilities

Introduction Disk Utilities
DELETEFILE() Deletes an error-tolerant file
DIRCHANGE()  Changes the current directory
DIRMAKE()    Creates a directory
DIRNAME()    Determines the name of the current directory
DIRREMOVE()  Removes a directory
DISKCHANGE() Changes the current disk drive
DISKCHECK()  Creates a checksum for a disk
DISKFORMAT() Formats disks, controlled through a UDF
DISKFREE()   Determines the space available on a floppy or hard disk
DISKNAME()   Determines the drive designator for the current drive
DISKREADY()  Tests to see if a disk drive is ready
DISKREADYW() Queries whether you can write to a drive
DISKSPEED()  Determines a comparison value for the drive speed
DISKSTAT()   Determines the status of a drive.
DISKTOTAL()  Determines the total capacity of a floppy or hard disk
DISKTYPE()   Determines the type of data carrier
DRIVETYPE()  Determines the drive type
FILEAPPEND() Appends data to a file
FILEATTR()   Determines a file's attributes
FILECCLOSE() Closes a file after backup mode
FILECCONT()  Copies sections of a file in backup mode
FILECDATI()  Determines which date the target file contains with FILECOPY()
FILECHECK()  Calculates/computes/determines a checksum for a file
FILECOPEN()  Tests to see if the file is still open in the backup mode
FILECOPY()   Copies files normally or in backup mode
FILEDATE()   Determines the file date
FILEDELETE() Deletes file(s) by name and attribute
FILEMOVE()   Moves files to another directory
FILESEEK()   Searches for files by name and attribute
FILESIZE()   Determines the size of a file
FILESTR()    Reads a portion of a file into a string
FILETIME()   Determines a file's time
FILEVALID()  Tests whether a string has a valid file name
FLOPPYTYPE() Determines the exact type of floppy drive
GETSHARE()   Determines the file open (share) mode
NUMDISKF()   Determines the number of installed disk drives
NUMDISKH()   Determines the number of hard disks
NUMDISKL()   Determines the number of available logical drives
RENAMEFILE() Fault tolerant renaming of a file.
RESTFSEEK()  Restores the FILESEEK environment
SAVEFSEEK()  Saves the current FILESEEK environment
SETFATTR()   Sets a file's attributes
SETFCREATE() Default attribute for creating with CA-Clipper Tools functions
SETFDATI()   Sets the date and time of a file
SETSHARE()   Sets default opening mode for CA-Clipper Tools file functions
STRFILE()    Writes a string to a file
TEMPFILE()   Creates a file for temporary use
TRUENAME()   Standardizes the path designation
VOLSERIAL()  Determines the DOS disk serial number
VOLUME()     Establishes a volume label for a floppy or hard disk