File Copy / Backup Functions

Copy / Backup Functions

FileCopy Copies file(s) normally or in backup mode
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 a FileCopy()
FileCOpen Tests to see if the file is still open in the backup mode

FileCOpen

FileCOpen

Tests to see if the file is still open in the backup mode

Syntax

      FileCOpen() --> <lOpenFile>

Returns

<lOpenFile> : .T. when all data is not copied during a FileCopy() or FileCCont().

Description

FILE COPY OPEN

FileCOpen() determines whether all data is copied. This concerns the source file, which is specified when the FileCopy() function is called. FileCOpen() returns .T. until all the data in the source file is read, whether by FileCopy or the follow-on function FileCCont()

Note

. If you must abort the copy process, and FileCOpen() continues to returns .T., use FileCClose().

Examples

      Show a back up with FileCopy():

      nCounter   := 1                   // "BIG.001" etc.
      cTargetFile   := "BIG" + NTOC(nCounter, 10, 3, "0")
      FileCopy("BIG.DBF", "A:\" + cTargetFile, .T.)
                                        // Back up mode
      DO WHILE FileCOpen()
         DO NEXTDISK                    // Request disk change
         nCounter     := nCounter + 1
         cTargetFile  := "BIG" + NTOC(nCounter, 10, 3, "0")
         FileCCont(cTargetFile)         // Next disk - new name

      ENDDO
      FileCClose()                      // For safety

Seealso

FileCopy(), FileCCont(), FileCClose(), FileCDaTi()

FileCDaTi

FileCDaTi

Determines which date the target file contains with a FileCopy().

Syntax

      FileCDaTi([<lNewMode>]) --> <lOldMode>

Argument

<lNewMode> : Designates the new status for FileCDaTi(). When .T. is designated, the target file contains the source file date; when it is .F., the system date. The default is the source file date (.T.).

Returns

If no parameter is designated, FileCDaTi() returns the current setting for FileCDaTi(); otherwise, it returns the previous setting.

Description

FILE COPY DATE TIME

FileCDaTi() Determines whether a source file’s date and time stamp or the system’s date and time stamp, should be used to create or copy a file. Use original or system time for a file copy process.

When you partition to several disks in backup mode, this concerns all target files. Default is .T., where the target file contains the date and time of the source file. If you call FileCDaTi() with the parameter designated .F., then the target file contains the system date and time.

Notes

. Use this function before FileCopy().

. If the target file contains a unique setting such as a pseudo serialization, use the SETFDATI() function.

Examples

      .  Query the FileCDaTi() setting:
         ? FileCDaTi()            // The current setting
      .  The target file is to contain the system date and time:
         ? FileCDaTi(.F.)         // Returns the previous setting

Seealso

FileCopy(),  FileCCont(), FileCClose()

FileCCont

FileCCont

Copies sections of a file in backup mode

Syntax

      FileCCont(<cFile>) --> <nCopyByte>

Argument

<cFile> : The file name for the target file.

Returns

<nCopyByte> : number of bytes copied

Description

FILE COPY CONTINUE

Use this function primarily after a FileCopy(). As much as possible of the remaining data is written to a new disk. If the remaining data still does not fit on the designated target disk, call this function repeatedly until it writes all the remaining data. Each time you call FileCCont(), a new name can be designated for the target file. These files are then numbered consecutively (see Examples).

Notes

. If a copy procedure on multiple disks terminates for any reason, call FileCClose().

. Use SETFCREATE() to designate an attribute to form a new file.

. The function acknowledges the CSETSAFETY() implementation, as does FileCopy()

Example

      . Show a back up with FileCopy().  After terminating, close the source
      file:

      FileCopy(cSource, cTarget, .T.)   // Back up mode
      DO NEXTDISK                       // When terminated  Terminated = .T.
      DO WHILE FILECOPEN() .AND. .NOT. Terminated
         FileCCont(cTarget)             // Next disk, new name
         DO NEXTDISK                    // Request for disk exchange
      ENDDO
      IF Terminated
         FileCClose()                   // Close source file!
      ENDIF

Seealso

FileCopy(), FileCOpen(), FileCClose(), FileCDaTi()

FileCClose

FileCClose

Closes a file after backup mode

Syntax

      FileCClose() --> <lClosed>

Returns

<lClosed> : .T., when the the file that was opened with FileCopy() is successfully closed.

Description

FILE COPY CLOSE

After you copy on multiple disks, this function should be routinely called. This is to prevent the source file, previously designed with FileCopy(), from remaining open. For example, this may occur if you terminate the copy procedure.

Note

. Regardless of the share mode, all other users are not allowed access. This situation stays this way without needing a file handle.

Example

      Show a back up with FileCopy().  After terminating, close the source
      file:

      FileCopy(cSource, cTarget, .T.)      // Back up mode
      DO NEXTDISK                          // When terminated Terminated = .T.
      DO WHILE FileCOpen() .AND. .NOT. Terminated
         FileCCont(cTarget)                // Next disk, new name
         DO NEXTDISK                       // Request for disk exchange
      ENDDO
      IF Terminated
         FileCClose()                      // Close source file!
      ENDIF

Seealso

FileCopy(), FileCCont(), FileCOpen(), FileCDaTi()

FileMove

FileMove

Moves files to another directory

Syntax

      FileMove(<cSourceFile>, <cTargetFile>) --> <nResultCode>

Arguments

<cSourceFile> : Designates the name and the path of the source file.

<cTargetFile> : Designates the name and the path of the target file.

Returns

<nResultCode> : a value of 0 when the file can be moved; otherwise, an error code is returned. The codes are defined below:

          FileMove() Return Codes
          ------------------------------------------------------------
          Code    Symb. constants        Definition
          ------------------------------------------------------------
           0      NO_DISK_ERR            No errors
          -2      ER_FILE_NOT_FOUND      File not found
          -3      ER_PATH_NOT_FOUND      Access path not found
          -5      ER_ACCESS_DENIED       Access denied (e.g., network)
          -17     ER_DIFFERENT_DEVICE    Target file not on same drive
          ------------------------------------------------------------

Description

If a file is to be copied within a drive and then deleted it from the original position, it is quicker to move the file. FileMove() makes this possible. The directory entries are also changed, which is much quicker than copying and deleting.

Notes

. You can use drive designators and access paths in <cSourceFile> and <cTargetFile> file names. Wildcards are not permitted.

. You can only move a file within a drive. If the target directory already contains a file with the same name as the one from <cSourceFile>, the move is not completed. In this case, FileMove() returns a value of -5. The only option available in this situation, is to delete the file in the target directory.

Example

      Move a file from "\OLD" to "\NEW":

      IF FileMove("\OLD\CUST.DBF", "\NEW\CUST.DBF") = 0
         ? "The file is now in the \NEW directory"
      ENDIF

Seealso

FileCopy()

FileAppend

FileAppend

Appends data to a file

Syntax

      FileAppend(<cSourceFile>, <cTargetFile>)
             --> <nAttachedByte>

Arguments

<cSourceFile> : Designates the file that is appended to <cTargetFile>. <cTargetFile> : Designates the file to which <cSource> is appended. Drive and path designation are permitted for both files, wildcards are not.

Returns

<nAttachedByte> : the number of characters appended on to <cTargetFile>.

Description

FileAppend() takes fragmented files, split them up on different floppies and reassemble them. This sort of fragmented file could be created with the FileCopy(). Only need is explicit information, such as VOLUME labels, to recognize the different disks.

If the target file does not exist, it is created with FileAppend(). If an error occurs while appending to the target file, the file deletes completely to avoid accidental and incorrect results. Never append data to file if there is no backup copy.

Examples

      Shown below is a simplified program to reassemble a file that is
      divided among several disks by a FileCopy() backup.

       A catalog contains a list of the disks used during backup in the
      form of volume labels and backup file names.

      Structure of the DISKLIST catalog:

      DISKLIST File Structure
      --------------------------------------------------------------------
      Field Name     Field Content
      --------------------------------------------------------------------
      VolLabel       Back up disk drive and volume label
      BackupName     Back up file name, incl. drive and path
      --------------------------------------------------------------------

      The data in DISKLIST is created by a FileCopy() backup:

      USE DISKLIST                                 // Saved volume labels
      cTargetFile  :=  "C:\TARGET.TXT"
      DO WHILE .NOT. EOF()
         IF .NOT. EMPTY( FileSeek(cVolLabel, 8)     // Correct disk ?
            FileAppend(cBackupName, cTargetFile)   // Yes, append data
            SKIP
         ELSE
            ? "Please insert the correct disk  !"
         ENDIF
      ENDDO

Seealso

FileCopy(), FileSeek()

CT_FILECOPY

 FILECOPY()
 Copies files normally or in backup mode
------------------------------------------------------------------------------
 Syntax

     FILECOPY(<cSourceFile>, <cTargetFile>, [<lMode>])
        --> nCopyByte

 Arguments

     <cSourceFile>  Designates the source file.  Drive and path
     designations are permitted, but not wildcards.

     <cTargetFile>  Designates the target file.  Drive and path
     designations are permitted, but not wildcards.

     <lMode>  Designates the backup mode on when designated as .T.  The
     default is no backup mode (.F.).

 Returns

     FILECOPY() returns the number of bytes copied.

 Description

     This function has additional uses besides allowing you to quickly copy
     files.  When you use the optional <lMode> parameter, a unique backup
     mode is switched on.  This allows files that are larger than the target
     disks to be copied.  This function writes the maximum possible number of
     bytes to a disk.  FILECOPEN() allows you to determine whether all data
     from the source file has been copied.  It then continues with the next
     disk.  The target disks should contain unique labels and be saved to a
     catalog.

 Notes

     .  The attribute to be used when newly creating a file can be
        specified with SETCREATE().

     .  As a minimum, the share mode recommends that you do not write
        other program source and target files.

     .  This function acknowledges the CSETSAFETY() setting, and as a
        result, cannot overwrite a target file.

 Examples

     .  Show a simple copy:

        ? FILECOPY("A:\TEXT.TXT", "C:\TEST.TXT")      // Bytes copied

     .  A back up using FILECOPY():

        nCounter  :=  1                               // "BIG.001" etc.
        cTargetFile  := "BIG" + NTOC(nCounter, 10, 3, "0")
        FILECOPY("BIG.DBF", "A:\" + cTargetFile, .T.)
                                                      // Back up mode
        DO WHILE FILECOPEN()
           DO NEXTDISK                                // Request disk change
           nCounter     := nCounter + 1
           cTargetFile  := "BIG" + NTOC(nCounter, 10, 3, "0")
           FILECCONT(cTargetFile)                     // Next disk - new name
        ENDDO
        RETURN

        PROCEDURE NEXTDISK
           ? "Please insert new diskette in Drive A:!"
           WAIT
           RETURN

See Also: FILECCONT() FILECOPEN() FILECCLOSE() FILEAPPEND()

 

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