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

 C_RESTORE()

 DESCRIPTION

 The C_RESTORE() function restores the specified file(s), previously
 copied by C_BACKUP(), from a given source drive/path to a specified
 target drive/path.  C_RESTORE() can restore any size and any type
 of file from the given drive.  C_RESTORE() can restore a single
 file, files based on a file specification (*.DBF), all files, or an
 array of specific files.  C_RESTORE() maintains a dialog with a
 specified user-defined function (UDF) which controls all of the
 actions of C_RESTORE() and allows customized messages to be
 displayed to the user.  The amount of buffer space needed by
 C_RESTORE(), 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_RESTORE().  An example UDF is included on the ClipOn diskette.

 Be sure that all files being restored are closed before calling
 this function.

 The C_RESTORE() function only restores files previously copied by C_BACKUP().

 SYNTAX

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

 PARAMETERS

 filelist (C/A) is the single file (MAIN.DBF), all files (""), or an
 array which contains specific files to restore.  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 the file
 to restore.

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

 All Files
 ---------
 The restoration of all files can be specified by passing a null
 string ("") or the file specification (*.*) for the filelist
 parameter.  Do not include a drive or path name.  The parameter
 src_path is used to indicate the drive and path name of the files
 to restore.

 Array of Files
 --------------
 A Clipper array can be specified whose elements contain specific
 files to restore.  The Clipper array is a one-dimensional array of
 any valid size for Clipper.  Each element in the array contains the
 file name including the extension, as a character string, of the
 files to restore.  Do not include a drive or path name as part of
 the file name.  The parameter src_path is used to indicate the
 drive and path name of the files to restore.

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

 tar_path (C) is the complete drive and path name (C:\FILES) where
 the specified files are to be restored.  If the drive or path name
 is not specified, the current drive and/or directory is used.

 bufsize (N) is the buffer space C_RESTORE() 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_RESTORE() 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 if fast and usually available in the program.

 udf (C) is the name of the user-defined function (UDF) to maintain
 a dialog with during the
 C_RESTORE() call.  The UDF is called continuously to allow complete
 access and control of the C_RESTORE() function.  The UDF accepts as
 parameters information as to the status of C_RESTORE() so that
 proper, customized messages may be displayed to the user.  The UDF
 returns to C_RESTORE() 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, "RESTORE_UDF", and
 must be specified for the C_RESTORE() function.  (Refer to file
 UDF_RT.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_RESTORE() should change the date and
 time of the files to match the restore date or maintain each file's
 date and time.  Specify true (.T.) to change the file date/time to
 match the restore 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_RESTORE() 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         Source file not found
 6         Copy error / ready to exit
 7         Not enough space on target / ready to exit
 8         Wrong disk number
 9         No file(s) found matching file specification
 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.
 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 being copied is
 split across multiple disks when it was originally copied by
 C_BACKUP().  True (.T.) indicates the file is split, false (.F.)
 indicates it is not.

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

 VALUE  DESCRIPTION
 -----  -----------
 0      Exit, cancel C_RESTORE(), return .F.
 1      Continue, perform action based on the status
 2      Restore is complete
 3      Prompt again for disk

 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  (Not enough space)   Exit, return .F.
 8  (Wrong disk)         Check source disk again
 9  (No files found)     Exit, return .F.
 11 (Aborted/exit)       Exit, return .F.
 12 (Completed/exit)     Exit, return .T.

 RETURNS

 C_RESTORE() returns true (.T.) if the restore was successful,
 otherwise false (.F.) if the restore was unsuccessful or an error
 occurred.

 EXAMPLES

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

 && Restore all files from a:\ to the current directory using a 64k buffer
 retc = c_restore("","A:\","",64000,"RT_UDF")

 && Restore specific files of various types from b:\ to the current
 && directory using a 10k buffer
 declare a_rt[2]
 a_rt[1] = "MAIN.DBF"
 a_rt[2] = "TRANS.DBT"

 if !c_restore(a_rt,"B:\","",10000,"RT_UDF")
   ? "Restore Failed"
 endif

 && Restore all *.DBF files from A: to the current directory
 retc = c_restore("*.dbf","A:\","",20000,"RT_UDF")

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