Click above to get retro games delivered to your door ever month!

 C_BACKUP()

 DESCRIPTION

 The C_BACKUP() function copies the specified file(s) from a given
 source drive/path to a specified target drive/path.  Any size and
 type of file can be copied. C_BACKUP() will copy files based on a
 file specification (*.*) or based on an array of specific files to
 copy.  C_BACKUP() maintains a dialog with a specified user-defined
 function (UDF) which controls all of the actions of C_BACKUP() and
 allows customized messages to be displayed to the user.  The amount
 of buffer space needed by C_BACKUP(), which relates to the speed at
 which it copies, is selectable from 1 to 64,000 bytes.

 NOTES

 A user-defined function (UDF) must be linked with the program to
 use C_BACKUP().  An example UDF is included on the ClipOn diskette.

 Be sure that all files being backed-up are closed before calling
 this function.

 The C_RESTORE() function must be used to restore files copied by C_BACKUP().

 SYNTAX

 C_BACKUP(filelist, src_path, tar_path, bufsize, udf [,network] [,stamp])

 PARAMETERS

 filelist (C/A) is the single file (MAIN.DBF), the file
 specification for a group of files (*.DBF), or an array which
 contains specific files to copy.  The following are the parameters
 allowed for filelist:

 One Specific File
 -----------------
 One specific file name can be specified as a character string.  The
 name must be the complete name of the file with the extension.  Do
 not include a drive or path name with the file name.  The parameter
 src_path is used to indicate the drive and path name for one file
 to copy.

 Group of Files
 --------------
 A group of files can be specified as a character string using a
 file specification such as *.DBF.  The wild card characters,
 asterisk (*) and question mark (?), may be used to indicate the
 file specification.  Do not include a drive or path name with the
 file specification.  The parameter src_path is used to indicate the
 drive and path name of the group of files to copy.

 Array of Files
 --------------
 A Clipper array can be specified whose elements contain specific
 files to copy.  The Clipper array is a one-dimensional array of any
 valid size for Clipper.  Each element in the array contains the
 complete file name including the extension, as a character string,
 of the files to copy.  The file name can also contain the drive and
 path name where each file is located allowing files to be copied
 from multiple directories.  If the drive and path name for a file
 is not specified, the default of the current drive and directory is
 used.  Note that the parameter src_path has no effect when using an
 array to copy files.

 src_path (C) is the complete drive and path name (C:\FILES) where
 the specified files to be copied are located.  If either the drive
 or path name is not specified, the current drive and/or directory
 is used.  Note that the src_path parameter has no effect when using
 an array to copy files.

 tar_path (C) is the complete drive and path name (A:\) where the
 specified files are to be copied.  Note that the drive must at
 least be specified for the tar_path parameter.

 bufsize (N) is the buffer space C_BACKUP() needs to copy the files.
 The buffer size is specified as a number from 1 to 64,000.  The
 size of the buffer allocated determines how much memory is used by
 C_BACKUP() and how quickly the files are copied.  A buffer size of
 64,000 allows for the fastest copy but is sometimes difficult to
 allocate due to memory limitations in a Clipper program.  A buffer
 size of 20000 is fast and usually available in the program.

 udf (C) is the name of the user-defined function (UDF) to maintain
 a dialog while calling C_BACKUP().  The UDF is called continuously
 to allow complete access and control of the C_BACKUP() function.
 The UDF accepts as parameters information as to the status of
 C_BACKUP() so that proper, customized messages may be displayed to
 the user.  The UDF returns to C_BACKUP() the appropriate action to
 take based on the information known to the UDF.  The udf parameter
 should be passed in quotes and without parenthesis, for example,
 "BACKUP_UDF", and must be specified for the C_BACKUP() function.
 (Refer to file UDF_BK.PRG on the ClipOn diskette for a functional UDF.)

 network (L) indicates whether or not the program is running on a
 network.  If the program is running on a network pass true (.T.) so
 the file can be opened with the proper share access, otherwise pass
 false (.F.).  If network is not specified, the default of false (.F.)
 is used.

 stamp (L) indicates whether C_BACKUP() should change the date and
 time of the files to match the backup date or maintain each file's
 date and time.  Specify true (.T.) to change the file date/time to
 match the backup or false (.F.) to keep the file's current date and
 time.  If stamp is not specified, the default of true (.T.) is used.

 PARAMETERS AND RETURN VALUES FOR THE UDF

 The following are the parameters accepted by the UDF:

 status (N) is the current status of the C_BACKUP() function.  The
 status codes are as follows:

 STATUS    DESCRIPTION
 ------    -----------
 0         Startup
 1         Ready to check source drive
 2         Ready to copy
 3         Source drive not ready
 4         Target drive not ready
 5         File not found (source)
 6         Copy error / ready to exit
 7         Copy complete (for one file)
 11        Aborted by user / ready to exit
 12        Completed successfully / ready to exit

 disk_no (N) is the current disk number, starting at 1, that is in use.
 file_no (N) is the number of the file, starting at 1, that is ready to copy.
 tot_files (N) is the total number of files copied so far.
 fspace (N) is the amount of free space available on the target drive.
 source (C) is the complete name including the drive, path, and file
 name of the file to be copied.
 target (C) is the complete name including the drive, path, and file
 name of the target file.
 filesize (N) is the size, in bytes, of the file to be copied.
 file_split (L) indicates whether or not the file copied has been
 split across multiple disks.  True (.T.) indicates the file has
 been split, false (.F.) indicates it has not.

 The UDF must return a value to C_BACKUP() to tell it the
 appropriate action to take.  The following are the return values
 that can be passed back to C_BACKUP():

 VALUE     DESCRIPTION
 -----     -----------
 0         Exit, cancel C_BACKUP(), return .F.
 1         Continue, perform action based on the status


 The following are the actions taken based on the status:

 IF STATUS WAS:            PERFORM ACTION:
 --------------            ---------------
 0  (Startup)              Do startup
 1  (Ready to check)       Check source drive
 2  (Ready to copy)        Copy source file
 3  (Source not ready)     Check source drive again
 4  (Target not ready)     Check target drive again
 5  (File not found)       Exit, return .F.
 6  (Copy error/exit)      Exit, return .F.
 7  (Copy complete)        Continue (next file)
 8  (Target disk full)     Prompt for new disk
 11 (Aborted/exit)         Exit, return .F.
 12 (Completed/exit)       Exit, return .T.

 RETURNS

 C_BACKUP() returns true (.T.) if the backup is successful, or false
 (.F.) if the backup is unsuccessful or an error occurs.

 EXAMPLES

 && Copy single file from directory c:\files to a:\ using a 20k buffer.
 if !c_backup("main.dbf","C:\FILES","A:\",20000,"BK_UDF")
   ? "Backup Failed"
 endif

 && Copy all files in current directory to a:\ using a 64k buffer
 retc = c_backup("*.*","","A:\",64000,"BK_UDF")

 && Copy specific files from different directories to B:\ using 10k buffer
 private a_bk[3]
 a_bk[1] = "C:\SYSTEM\MAIN.DBF"
 a_bk[2] = "C:\SYSTEM\MAIN.DBT"
 a_bk[3] = "C:\PROJECT\DATA.TXT"
 retc = c_backup(a_bk,"","B:\",10000,"BK_UDF")

 && Use C_DIRTOA() to backup different file specifications in the
 && same directory
 private file[2]
 file[1] = "*.dbf"      && Setup array with wanted file specs.
 file[2] = "*.dbt"

 private bk_arr[ c_dirtoa(file) ]  && Call c_dirtoa() to declare array

 c_dirtoa(file,bk_arr,.f.,.t.)   && Call again to load files

 && Call C_BACKUP() with BK_ARR[] array which has all *.dbf and
 && *.dbt file names
 c_backup(bk_arr,"","A:",20000,"BK_UDF")

 Note that in the examples above, the code for the callable UDF
 "BK_UDF" is contained in the file UDF_BK.PRG on the ClipOn diskette.