BU.DOC

		An incremental back-up program for CP/M 80  
			by  Ian Ashdown

		with additional features including
		attribute-setting functions 
			by Peter G. Martin

***************************************************************************
........with acknowledgement and thanks to the author, to Dr Dobbs and Anthony
Skjellum.
***************************************************************************


Copyright notice :  

This program is the copyright property of 

			Ian Ashdown
			byHeart Software
			2 - 2016 West First Avenue
			Vancouver, B.C. V6J 1G8
			Canada

BU is an incremental back-up program for CP/M 80 and CP/M 86 using setting of
'archive attribute' (Bit 7 of the 3rd char in the 'TYP' ( a la 'FILENAME.TYP')
in the directory listing of a CP/M file.    Its general purpose is to make 
the task of regular backing up of files easier, and with its simplest options,
(eg, A>BU A B<ret> ) it copies files, setting the archive bit on each one 
copied, and (unless an overriding command is given) will only then copy those
files which do NOT have the archive bit (t3') set.

The system logic is NOT perfect, because CP/M does not automatically reset the
archive bit on ALL files that are changed.   However, it's probably true to say
that most file RE-writing does reset the bit, and it's relatively easy to pick
the exceptions.

This (May 1986) version 2.0 of BU is for BDS-C (CPM/80) only.

Some of the earlier versions have options for C compiling under AZTEC CII vers.
1.06b (CP/M 80),   DESMET C88 v2.2 (CP/M-86) and later, for BDS-C v. 1.50a 
(CP/M 80) as well.

Considerable changes have now been made to the original version as published, 
and in particular, version 2.0 :

(a) ALLOWS for problems with changed files which have not had the archive bit
reset by including the option (when a 'SAME DRIVE' command is given) to change
any or ALL of the 'TYP' ATTRIBUTES of files, either on individual files, on all
files on the disk, on all files matching an (ambiguous) filename, on all files
in a given user area, or on combinations of these;  

(b) can search all user areas for active files matching the file specification,
and will report and display the user areas involved;

(c) is restructured to permit the user to run quickly down a check-list of
filenames for action, after which the program gets on with the task of dealing
with all files as requested.

Code has been adapted from Leor Zolman's 'wildexp.c' to allow in particular for
the different way BDS's I/O handles filename formats , compared with the format
found in the fcb for directory entries.


USAGE:

1. For file back-up functions (as opposed to attribute-setting only) :

			BU x[:afn] y [-AFHQCSn]

		WHERE
			x = drive name of disk to be backed up
			y = drive name of backup disk

		AND 
		
		    optional arguments are :

		     -A		ALL files to be backed up, regardless.
		     -F		FAST copying -- ie, omitting verification
		     -H		HARD disk copying (files may be split)
		     -Q		QUERY each file before backup
		     -C		Change disks after BU is loaded
		     -S		SYSTEM attribute copied, as is, to backup
		     -n		Backup USER 'n' files only (0-15 ? 0-31)
		     afn	A legal CP/M ambiguous filename 


2. For attribute-setting function only :

	    BU x[:afn.aft] x  [-AQCn]

	    Where drive-names ('x') are EQUAL  (eg BU A A)

	    AND options accepted are as above, but -H -S and -F are
		illegal, and -A is accepted but unnecessary.
    
GENERAL BACKGROUND:

The old 'STAT.COM' operations of '$R/O', and '$R/W' set and reset
(respectively) bit 7 of the FIRST (ie, "T") letter in a filename tag or 'TYP',
while 'STAT <fn.typ> $SYS' and 'STAT <fn.typ> $DIR' set and reset
(respectively) bit 7 of the SECOND (ie "Y") character in the 'TYP'. 

This program uses the setting and resetting of bit 7 in the THIRD 'TYP'
character (in the "P") position to keep track of whether a given file has been
backed up or whether it has been changed or written-to since it was last backed
up.

It can therefore be used for 'incremental' (lovely jargon!) back-up procedures.

That simply means, after you've done one big back-up, later back-up efforts are
usually (EXCEPT with the '-A' option) going to simply pick out those files that
NEED to be backed up  (ie, have been CHANGED, or not backed-up before.)

DRI, according to legend, had always intended that this 'attribute bit' as it
is known, should be set aside for use as an "archive attribute", but appears
only to have proceeded with implementation of that idea for MPM and CPM+.

MEANWHILE, the general idea is that the program will check the 'archive
attribute' on files in the directory for the disk and/or user area to be backed
up, and will usually (ie, UNLESS the '-A' option  is selected -- see below)
then copy ONLY those files which do not have this bit set.

So if bit 7 of the 3rd TYP character is set, BU 'KNOWS' that the file has been
backed-up and has NOT been written to or changed since it WAS backed up.

THIS 'KNOWLEDGE' IS SOMETIMES WRONG !

PIP.COM, for example may sometimes leave attribute bits set, and many programs
which work to 'APPEND' data to an existing file may not clear the attribute
bits -- NOTABLY LU.COM, when it adds members to a  .LBR file .

You may need to be careful about whether you want the file backed up and
whether BU has recognized it in the right way.	  That is one of the reasons
for now including in the program the function of setting or resetting attribute
bits of any files nominated.


USAGE EXAMPLES:

BU a b

(note no ':' involved here)

	Will copy 'updated' (ie, either changed or previously un-backed-up )
files from drive A: to drive B:.   WON'T copy files already 'thought' to have
been backed up (ie, which have archive bit set).   WILL check each file copy
against the original (ie, 'verify' each copy) and abort if for some reason the
original and the back-up do not match up.  WILL check ALL USER areas and copy
on B: into the same USER area the file came from on A:

				*****************
BU c a -F

	As above, but from drive C: to drive A: , and no 'verification' will
take place.    As verification involves re-reading BOTH files each time a copy
is made, this is F for FASTER.

				*****************

BU a:filename.typ b -5

	Copies ONLY file 'filename.typ' from USER area 5 on A: (if it's there)
to USER area 5 on B:  --- unless it's ALREADY BEEN BACKED-UP (archive bit
set).

	(note the use of the colon REQUIRED here as a delimiter )

				*****************

BU a:*.typ b 

    OR

BU  a:filename.* b:

	Copy all UNBACKED-UP or CHANGED files matching the '*.typ' (or
'filename.*' ) if they exist in ANY USER AREA on A:, each into the SAME USER
area on B:

VERSION	 2.0 NOTICE :  NOTE THAT THE -n tail IS NO LONGER ABSOLUTELY REQUIRED,
but is now a genuine OPTION to limit copying to a given user area .

The program now checks ALL files in the directory ( by putting a '?' into 
fcb[0]), then builds a 'map' of active user areas, displaying on screen those
that have been found active in file specification terms.

Files are then checked and/or copied in USER AREA order (0-15) .

				*****************

BU c a -AF

   OR

BU C A -a -F

	Copies ALL files without verification ('-F' option) in ALL USER areas
on C: into same USER areas on A:, and does this REGARDLESS of whether they've
been backed up before.	

NOTE THAT THIS MEANS ANY EXISTING FILES ON A: OF SAME NAME AS FILES ON C: WILL
BE ERASED --- THIS APPLIES WHETHER THEY ARE SET 'R/O' OR NOT !!!

*******************************************************************************
*************** BU SETS ALL BACK-UP COPIES TO 'R/O'   ************************
*************** BUT WHEN THE '-A' OPTION IS SPECIFIED ************************
*************** IT CAN AND WILL ERASE EXISTING 'R/O   ************************
*************** FILES ON THE DESTINATION DISK !!!!    ************************
******************************************************************************

(also note, as a minor point, that the '-' options can be separated or run
together.)

				*****************

BU a b -H

	The 'HARD DISK' option is for a situation where you may be copying very
large files from a hard disk onto floppies.   Obviously, you have a problem if
a file is actually bigger than the floppy capacity.    This option allows a way
out of that. When a disk taking the back-up is 'found' to be full under this
option, the user is warned of that fact, and reminded that that the 'HARD DISK'
option is in force.

	He or she then has the option EITHER to abort (which results in erasing
that section of the file that had been written out to the back-up disk at that
stage) OR of changing over back-up disks in the back-up drive (getting a bdos
'reset' on the way) and having the partly-written file closed down under its
original name, and the NEXT SECTION of the file written to the new back-up disk
under an artificially-created new filename, in the form 'FILE--01.TYP'... ie,
with the 2 'file segment' numbers replacing the LAST TWO characters of the
original 'filename' and with '-' characters replacing any preceding blanks in
the filename.	 HENCE, 'FILENAME.FOO' under the hard-disk operation may become
two files, 'FILENAME.FOO' and 'FILENA01.FOO' (...'FILENA02.FOO'...etc).

Users unfamiliar with the (many) vaguenesses (and usefulnesses) of PIP.COM
should note that PIP can combine files that have been separated back into one
file, although obviously both file segments have to be 'on-line' (ie in a disk
drive somewhere).    The general PIP command format for this uses commas for
separation of the file segments, thus :

PIP A:BIGFILE.TYP=B:FILE.TYP,C:FILE--01.TYP

makes up one file on A: of the files on B: and C:.

WITHOUT the HARD-DISK specification in the command line, a full-disk
encountered in backing up will still provide a warning and an option to abort,
but the partly-written file will be erased.   If a new disk is inserted
according to the prompt, copying will proceed on the next disk inserted in the
back-up drive.

				*****************

BU a b -S

	Does the usual things (ie, copy files that 'need' to be backed up FROM
A: onto B: into their respective USER areas, WITHOUT file-splitting (ie, no -H
was specified)	BUT if the original files on A: were set to $SYS when copying
began, the back-up copies will also be set to $SYS (ie, invisible to the normal
directory or DIR: command).	 FEAR NOT, they'll still be THERE ! (and SET
R/O and with their archive bit set etc.....



Add '-Q '  to any of these valid commands, and you'll be prompted to give a
yes/no answer as to whether you want the named file copied/backed-up.

Add '-C'  and before the program goes anywhere, it will pause and prompt you
to insert source and destination disks for copying or attribute-setting into
the relevant drives nominated in your command line, and reset drives so that
copying can take place without a system error.


ATTRIBUTE SETTING OPTIONS:

(a) WITHOUT THE -Q COMMAND TAIL:

Given commands like :

BU B B
BU B:*.typ B:
BU B:afn.* B:
BU B:filename.typ B
BU B:*.* B:
BU B B -0

the program (surprise, surprise !) will NOT attempt to copy files from one disk
onto the same disk, but will display usage for attribute setting, and because
the -Q command tail option has not been specified, will display the 'normal'
setting pattern for attributes for files -- ie, R/W DIR NRC  (read/write,
directory and non-archived) and prompt you for a setting-pattern to be applied
to the (specified) files.

This pattern may include the option to leave a particular attribute AS IS,
REGARDLESS.  

Thus, to change all files to ARCHIVED, but leave their status as r/o, r/w, dir
or sys AS IS,  you may enter :
		      --- --- ARC 
as the 'pattern' for attribute-setting, where '---' in the appropriate position
means LEAVE THIS ATTRIBUTE BIT AS YOU FIND IT

Once you give the pattern under this general-pattern option, each of the files
affected will have user area and filename displayed, along with the attribute
status of the file after the requested change.

(B) USING -Q WITH ATTRIBUTE-SETTING:

Commands using the SAME-DRIVE format and adding -Q result in the display of the
user area and filename of each file matching the file specification (if any)
given, together with a display of the CURRENT SETTING of each file's
attributes.

With each file, you are prompted to answer whether you wish to alter attributes
on the particular file.

If you choose NOT to, the program moves on to the next file.

If you choose to change, the cursor moves back to the display of the current
setting of the attributes, and you may enter the desired form.	Your entry may
include the '---' (LEAVE ALONE) option, or any of the standard options,
provided these are entered in the right position.  The program, however, will
NOT accept an entry like SYS R/W ARC (because it's in the wrong order and
should be R/W SYS ARC, and moves back and waits for corrections on wrong
entries.

Once the checklist under the -Q option is complete, a new list of files is 
shown, as each file is set according to your specifications, and the CHANGED
status of the attribute bits is shown as they are set.


That's about it.. Again, thanks to Ian Ashdown, Anthony Skjellum, Leor Zolman
and all...


Recommended compile commands for BU version 2.0 in BDS-C are:

cc bu.c -e4700
cc bu2.c -e4700
cc bu3.c -e4700
cc bu4.c -e4700
l2 bu bu2 bu3 bu4

for L2.COM


				----	Peter G. Martin	 

/* End of BU.DOC version 2.0 May 1986 */