Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : BR02A.ZIP
Filename : BACKRITE.DOC

BACK*RITE
Version 0.2

Fast Back-up Utility for Clipper, Summer '87

(C) 1989, Mark J. Bachrach and David McConnell



DISCLAIMER AND USAGE AGREEMENT

The authors make no warranty, either expressed or implied, and will
assume no liability, pertaining to the operation of this library or
its suitibility for a particular application.

This version of BACK*RITE is for beta-testing and usage only by
registrees of the KWIBBLE BBS.

By using BACK*RITE, you agree to the following terms:

1) You will not sell BACK*RITE in any form.
2) You will not distribute BACK*RITE to any other BBS.

Since this is the beta-test version, the only compensation we ask is
that you take a few minutes and let us know what you think of the
library. We welcome all comments and suggestions.

Mark J. Bachrach
1725 Jefferson Davis Hwy.
Suite 1003
Arlington, VA 22202

KWIBBLE: MARK BACHRACH


BR02.ZIP INVENTORY

This package includes:

BACKRITE.LIB Back-up/Restore Utility Library
BACKRITE.DOC This Manual
SAMP_UDF.PRG Sample User Defined Screen Control Function


INTRODUCTION

Back*Rite provides a fast, efficient, and flexible back-up utility to
link into your Clipper, Summer '87 applications. It is written in 98%
Clipper. Back*Rite employs a format which utilizes every available
byte on the back-up diskette. (Although no data compression is
provided in this version.) Files which are too big to fit on a
diskette are continued on the next diskette. Files can be backed-up
from any directory, and you may provide the file specifications in a
number of ways.

Two functions are provided in BACK*RITE. B_BACKUP is the function to
back-up user files to diskette. B_RESTORE reads the files made by
B_BACKUP to restore the backed-up files. Since B_BACKUP uses a
special file format, back-ups created with B_BACKUP can only be read
by _RESTORE.


LINKING BACK*RITE INTO YOUR APPLICATION

To link Back*Rite into your application, copy BACKRITE.LIB into your
Clipper directory. Then, simply include BACKRITE in your PLINK86 (or
other linker's) library list. Example PLINK86 syntax:

PLINK86 FI myprog LIB clipper, extend, BACKRITE


MEMORY USAGE

To determine the effect of BACK*RITE on your EXE's load size

If you use B_BACKUP add 2.5 K
B_RESTORE add 3 K

Additionally, If your program does not currently use:
EXTEND.LIB add 1.5 K
ARRAYS add 3.5 K
LOW LEVEL FILE HANDLING add 1.5 K


B_BACKUP

Use the function B_BACKUP to back-up all or some files on a directory.

There are two different ways to call B_BACKUP. If you can specify the
files to be backed-up using DOS wildcards, use the following syntax:

B_BACKUP([C1, [C2, [C3, [L1, [C4]]]]])

Where C1 = Back-up drive
C2 = Path of source files
C3 = File specification (DOS wildcards permitted)
L1 = .T. if you want the back-up disk automatically
erased
C4 = Name of a user defined function for screen
control

Examples:

B_BACKUP("A", "\DATA", "*.DBF", .T., "MYUDF")

Will back-up all DBF files on the current drive's \DATA
directory to the root directory of Drive A:, after
erasing the root directory on A:. Control will be
passed to MYUDF for screen control

B_BACKUP("B", "D:\", "*.*")

Will back-up all files on Drive D:'s root directory to
the root directory of Drive B:, without erasing the
root directory on B:. Screen control will be performed
by default procedure.

B_BACKUP("", "")

Will back-up all files on the current drive's current
directory to the root directory of Drive A:, without
erasing the root directory on A:. Screen control will
be performed by default procedure.

B_BACKUP()

Will do the same as the last example.


If the files can not be specified using DOS wildcards, use the
optional syntax:

B_BACKUP(C1, C2, A1, [L1, C4]])

Where C1 and C2 are defined as before, but are not optional.
A1 is a previously declared array of filenames (with
extensions).
L1 and C4 are the same as before.

example:

DECLARE myfiles[3]
myfiles[1] = "first.dbf"
myfiles[2] = "second.wk1"
myfiles[3] = "third.txt"
B_BACKUP("A", "\FILES", myfiles, .T.)

Will back-up the three files in the array, found on the
current drive's \FILE directory, to the root directory
of Drive A:, after erasing Drive A:'s root directory.

B_BACKUP works on DOS files of any type. It is not limited to
databases. However, it will not work on READ/ONLY files, or with
directory entries of type DIRECTORY.

B_BACKUP makes a complete new back-up each time it is run. In other
words, if the back-up diskettes contained a five file back-up, and you
overwrite those diskettes with a back-up of only three of those files,
the other two files will have been lost. This version does not
support incremental back-ups.

NOTE: B_BACKUP creates and includes in the back-up its own
directory file. Therefore, the number of files shown by the
file counter will be one greater than the number of files
included in the file specification.


B_RESTORE

B_RESTORE reads the back-up files made by B_BACKUP, and restores them
to the specified path in DOS format. (NOTE: Unlike DOS BACKUP, files
need not be restored to the same directory they were backed-up from.)
Like B_BACKUP, you may specify the files to be restored either using
DOS wildcards, or by passing an array of filenames. It is not
necessary to restore all the files contained in the back-up.

The syntax for using wildcards is:

B_RESTORE([C1, [C2, [C3, [C4]]]])

Where: C1 = The drive to be restored from
C2 = The path to be restored to
C3 = The file(s) to restore (DOS wildcards permitted)
C4 = Name of a User Defined Function for screen
control

Examples:

B_RESTORE("B", "\DATA", "MYDATA.DBF", "MYUDF")

Locates MYDATA.DBF in the back-up diskette in
Drive B:, and restores it to the current drive's
\DATA directory. Control will be passed to MYUDF
for screen control.

B_RESTORE("A", "D:\MY\FILES", "FILE??.*")

Restores, from Drive A:, files with names like
FILE01.DBF, FILEZZ.TXT, and FILEIT to Drive D:'s
\MY\FILES directory. Screen control will be
performed by default procedure.

B_RESTORE()

Will restore all files in Drive A:'s back-up disk
to the current directory. Screen control will be
performed by default procedure.

If you can not use wildcards to specify the file list, use the
optional syntax:

B_RESTORE(C1, C2, A1, [C4])

Where: C1 and C2 are defined as before, but are not
optional.
A1 is a previously declared array.
C4 is the same as before.

Example:

DECLARE myfiles[2]
myfiles[1] = "first.dbf"
myfiles[2] = "second.txt"
B_RESTORE("A", "", myfiles)

Will restore the two listed files from the back-up
diskette in Drive A: to the current directory.

NOTE: Back-up diskettes must be inserted in the order they were
created by B_BACKUP. Failure to do so will result in an
error.


ERRORS

DRIVE NOT READY. A flashing message will appear, and the program will
wait until the drive is ready. Processing will then proceed
automatically. The message will be triggered by any of the following
conditions.

- Disk drive inaccessible
- Door not closed
- Disk not formatted
- Disk is write-protected

Hitting the key will terminate BACK*RITE and return control to
the calling program. In this version, the DRIVE NOT READY message and
the associated actions may not be altered.

All other errors which may occure are not recoverable in this version.
An error message will appear, with an explanation of the type of
error. BACK*RITE will then terminate and return control to the calling
program. If you specify your own UDF (see next section) you can
change how the error screen appears.


USER SCREEN CONTROL.

If the default screen format is not satisfactory, you may write your
own Clipper UDF to handle outputs. If you specify the name of a UDF
in B_BACKUP parameter #5 or B_RESORE parameter #4, your UDF will be
called before each action. Five parameters will be passed each time,
which provide information about the event to occur next. Your UDF is
free to use or ignore any of this information.

Included in this package is SAMP_UDF.PRG, which is the actual source
code for the default BACK*RITE UDF. You may modify this code, or use
it as a basis for writing your own UDF.

BACKRITE calls your UDF with the following syntax:

YOUR_UDF(N1, N2, N3, C1, N4)

Where: N1 = Status Code

0 = Start-up
1 = Initialization
2 = Disk Change (UDF must not return control
until user is ready to proceed)
3 = Backing-up
4 = Restoring
5 = Erasing
6 = Searching
7 = Finished
8 = Error


N2 = The current file number being backed-up or
restored
N3 = Total number of files to be backed-up or
restored
C1 = Name of the file being backed-up or restored
N4 = Percent complete, based on:
(Bytes Copied / Total Bytes In Job) * 100

In the case of an error (Status = 8), the type of error will be passed
in the PERCENT (N4) parameter. Possible errors and their type codes
are:

1 = No files found matching specification
2 = Error opening file
3 = Error reading file
4 = Error writing to drive
5 = Error back-up drive full to start


NOTE: BACK*RITE is the fastest back-up routine currently available as
a Clipper add-in. However, the performance may be degraded by
an inefficient UDF.


COMING IN FUTURE VERSIONS

* Data Compression
* Selective/Incremental Back-ups
* Optional Front End Control Program