A more up-to-date help file is in the html help.

SyncDiscs
=========
Version 1.23 (1 Jan 2011)

Disclaimer
~~~~~~~~~~
Neither David Pilling nor Chris Johnson accept any responsibility for
any loss of data which occurs as a result of using this program,
whether as a result of correct, or incorrect, operation. You use
SyncDiscs at your own risk.

Introduction
~~~~~~~~~~~~
What does SyncDiscs do? Quoting from David Pilling's original help
file:

"SyncDiscs makes the contents of two discs or directories the same. I
wrote it to allow me to keep an exact copy of my hard disc on a
removable disc. No doubt it would also be of use for synchronising a
portable computers disc with that on a main machine."

SyncDiscs was originally written by David Pilling. With the full
agreement and encouragement of David, Chris Johnson has taken on the
maintenance and development of SyncDiscs, and the new version is now
available.

A consequence of this is that all correspondence about SyncDiscs
should now be directed to Chris Johnson (Email:
chris@chris-johnson.org.uk), and not to David.

Installation
~~~~~~~~~~~~
For a new installation, simply drag and drop the SyncDiscs application
into the directory of your choice.

If you have a previous copy of SyncDiscs you have two choices.

* Move the old version of SyncDiscs somewhere safe and replace it with
  the new version

* Simply copy the new version over the old version. Set your filer
  options to Force and Newer

Usage
~~~~~
SyncDiscs is run in the usual way by double clicking on its icon. It
will install on the icon bar. The icon bar menu offers the following
options.

Info - This leads to the standard information window, which also
----   contains a web button, allowing a quick way of accessing the
       download site.

Help... - will launch the documentation (this file) in the default browser.
-------

SyncDiscs - will open the main control window. The same action can be
---------   achieved by simply clicking on the SyncDiscs iconbar icon.

Quit - will remove SyncDiscs from the iconbar and terminate the program.
----

The main control window
~~~~~~~~~~~~~~~~~~~~~~~
Screen shots of parts of the main control window are shown below.

The top three writable fields can have directories dropped into them
to provide the filing system paths to be used, or the paths can be
typed in by hand.

Primary- The first field is 'Primary'. This is the main directory
-------   and is the directory that is to be 'backed up'.

Secondary - The second field is 'Secondary'. This is the directory
---------   which is to be changed, and is to be made the same as the
	    Primary directory.

Scrap - The third field is 'Scrap' - any files which have to be
-----   deleted from the Secondary directory are moved here. If the
	scrap directory is left blank, then scrap files will simply be
deleted. It is important to remember that the scrap directory should
not be in either of the primary or secondary directories.

All three icons can contain more than one directory, separated by
commas. In this case there must be the same number of directories in
each. For example, if there are two directories in each, the first
primary directory is backed up into the first secondary directory, and
the second primary directory is backed up into the second secondary
directory. To make this easier, if a directory is dragged into a field
with SHIFT held down, a comma will be inserted at the end of the
current contents of the field, and the new directory will be appended.
If you are using scrap directories, then there must be the same number
entered as for the primary and secondary directories, otherwise the
scrap directory will be treated as blank and files will simply be
deleted from the secondary directory.

Note that each of these fields is limited to a total number of
characters of 255. Thus if you try and drop in several directories
with long path names, this limit will be reached and unpredictable
behaviour will ensue (directory names truncated or missing).

If Control is held down the directory leaf will have one element
removed - this is useful if you want to enter the root directory of a
disc.

Hint: If you are using a scrap directory, then it is useful to have it
on the same device as the secondary directory, especially if it is
being accessed over a network. While a copy would normally load the
data in to memory as an intermediate step, SyncDiscs tries to be a
little more subtle, and attempts a 'delete existing scrap file/rename
old secondary file to scrap' as a first step before resorting to a
'copy to scrap with force set'. The former is very much faster of
course, but renames are only possible if the two filenames are on the
same device.

In the next part of the window are three option buttons, and another
writable field for the logfile path.

The three option buttons control what happens if there are files in
the secondary directory that are newer than, or not present, in the
primary directory.

Copy newer files from secondary to primary - If ticked, any newer
------------------------------------------   files which are found in
					     the secondary directory
will be copied back to the primary directory.

Copy extra files from secondary to primary - If ticked, extra files on
------------------------------------------   the secondary will be
					     copied back into the
primary directory. Note that this option may result in the 77 files in
a directory limit being breached if you are using a version of RISC OS
prior to 4.0. This option should be used with care, since files
deliberately deleted from the primary directory since the last
synchronisation will be copied back into the primary directory,
effectively undeleting them.

Overwrite newer files on secondary - If ticked, any files found on the
----------------------------------   secondary that are newer than the
				     corresponding files in the
primary directory will be replaced by the primary file even although
it is older. 

Logfile - SyncDiscs can create a file which contains a record of all
-------   the file operations carried out. The file will record all
	  files copied, moved or deleted. The file path is set up
either by typing it in manually, or by pressing the menu button to the
right of the writable field and dragging the icon from the resultant
Save As dialogue to your chosen destination. The logfile will only be
used if the option button to the right of the menu button is ticked.
See the section Additional settings for further options to control the
log file. The button to the right provides a quick means of opening
the logfile in a text editor, but only if it has already been created.

Note that SyncDiscs will never attempt to copy the logfile if it
happens to be within the primary directory, whether the logfile is
active or not.

At the bottom of the window are action buttons to control its
operation.

Start - will start the synchronisation process.
-----

Cancel - will simply close the main window.
------

Save - There are two distinct operations that can be carried out.

    1.  Clicking on the Save button will save a default file
    	containing all the settings as shown in the window. When
	SyncDiscs is run again, the current contents will be restored,
	allowing the same operation to be easily repeated.

    2.  Clicking on the Menu button to the right of the Save button
    	will raise a standard Save as dialogue. In this case all the
	current settings (in both the main SyncDisc window and the
	additional Settings window) will be saved as a Syncjob file.
	This file can be saved anywhere, and double clicking it (or
	dragging to the SyncDisc window or iconbar icon) will
	immediately start (or queue if a synchronisation is already in
	progress) the synchronisation job. This provides an easy way
	of repeating a regular backup requirement. Further information
	on using syncjob files is here.



Compare - The 'compare' button initiates a complete comparison of the
-------   primary and secondary paths, although no changes are made to
	  any files. At the end of the process a text file is
automatically opened which displays the results. In this file is
listed all the differences between the contents of the two paths. It
can be useful to do a compare after a synchronisation has finished -
this picks up any inconsistencies in the copying process.

Settings... - This will open the Settings... dialogue, allowing a
--------      number of other preferences to be set (see below).

Additional settings
~~~~~~~~~~~~~~~~~~~
Multitask - When SyncDiscs is either comparing or synchronising two
---------   directories it can be run as a single-tasking or
	    multi-tasking process. When single-tasking the machine is
'taken over' and cannot be used in any other way until the process has
finished. If in multi-tasking mode, then SyncDiscs still polls the
wimp during the processing and so the machine can be used for other
purposes at the same time. Single tasking will be faster than
multitasking.

Allow multiple filer action windows - This is only of relevance when
-----------------------------------   operating in multitasking mode.
				      Filer operations are passed on
to the Filer_Action module, which also multitasks all its operations.
If this option is unticked, then SyncDiscs will wait after initiating
a filer action until it has completed. If multiple filer actions are
allowed (by ticking this option) then SyncDiscs will continually
launch filer actions in parallel, and not wait until any single one
has completed. However, SyncDiscs will not allow too many filer
actions to be active concurrently, since the desktop will become very
unresponsive, so the number of filer actions active at the same time
will be limited. The maximum number of concurrent filer actions can be
set using the bump icons.

Be aware of the following points.

* When SyncDiscs invokes the Filer_Action module, it does so with the
  verbose flag off. This means you will not normally see any
  Filer_Action dialogue boxes on the desktop. You will see the
  Filer_Action windows starting and stopping in the Task Manager
  listing of active application tasks (click SELECT on the right hand
  icon of the iconbar). If there occurs an error condition during a
  copy, however, then you may see the Filer_Action window with the
  buttons Skip, Retry etc. open.

* If you have configured for say ten Filer_Action windows, it does not
  mean there will always be ten running. It will depend upon how much
  data is to be copied, how large the files are and how fast the
  hardware is. Large files, such as digital images, take much longer to
  copy, and there is more chance that SyncDiscs will have started more
  off while earlier ones are still completing. Copying over a network
  will be much slower than copying between two hard drives on the same
  machine. However, you should not normally see more than the
  configured number at any one time.

Copy complete directories - By default this option is selected. If
-------------------------   SyncDiscs finds a directory that does not
			    exist in the backup, it will simply copy
the whole directory as is, and not inspect the objects (files or
directories) within it. This option is faster, but it means SyncDiscs
does not see what is inside the directory, and cannot, for example,
check whether files are open before copying, or whether one of the
ignore zones (if being used) is contained within it. By unticking this
option, SyncDiscs is forced to open up every subdirectory,
recursively, and create each subdirectory and copy each individual
file. For normal purposes, it is recommended that this option is
ticked.

Timestamps equal if within... - One of the criteria used by SyncDiscs
-----------------------------   to determine whether to copy a file or
				not is to compare the date and time
stamp of the two copies. A problem may arise here if you are backing
up to a disc on a different OS because, while RISC OS stores
timestamps to a precision of 1 centisecond, some other OSs use
different precision, which could be better or worse than RISC OS. For
example, if the precision is only 1 sec, as on some Windows file
systems, then the timestamp of the copy will be rounded to the nearest
second. When SyncDiscs comes to do a subsequent backup, it may think
the backup is older than it really is, and copy it again. To reduce
this type of occurrence, when SyncDiscs compares the two timestamps,
it can be made to ignore a small difference in timestamps and treat
them as being equal. Tick this option to turn this behaviour on - the
time difference can be set using the bump icons adjacent. A value of
three seconds is a good compromise.


Ignore filetype differences - SyncDiscs will normally copy
---------------------------   a file if the filetypes of the primary
                              and secondary copies are different. When
copying to 'foreign' file systems using e.g. Fat32FS, the filetype
mapping is controlled by the Mimemap file. Depending on the entries in
this file, some filetypes may change when copied. For example, the zip
filetype (&a91) may revert to archive (&ddc), or DOS filetype (&fe4)
may revert to data or text filetype. This can cause unnecessary copy
actions on subsequent synchronisations. If this option is ticked, then
when SyncDiscs finds the only difference between the primary and
secondary files is in the filetype, then the file will not be copied
again.

The next part of the additional settings dialogue is concerned with
log file management.

New logfile each synchronisation session - By default, SyncDiscs will
----------------------------------------   add all its output to the
					   configured logfile, rather
than starting a new one each session. This means the logfile can
become very large over time (unless you periodically change the name
or delete it). If this option is ticked, then SyncDiscs will clear the
logfile each time it carries out a synchronisation. Since older
records are then lost, there is the further option to save the last
few logs (up to 9). This is accomplished by adding a numerical suffix
to the logfile name. When a synchronisation is started, the oldest
logfile is deleted, and the rest are moved 'down the list' by
renaming. Note that there may be a problem if the logfile name is of
length ten characters on a filing system which does not support
filenames longer than ten characters.

Note that a synchronisation session comprises the processing of a
single queue of jobs, which may be a single job.

Auto-open log file on completion - This simply opens the logfile in
--------------------------------   the default text editor once the
				   synchronisation is finished.
Otherwise you have to find the logfile and open it manually if you
wish to inspect it.

Save - All the current settings can be saved by pressing this button.
----   Note that SyncDiscs will always use the current settings when
starting each synchronisation. When the settings are saved, then
SyncDiscs will use the same ones when run on a future occasion.

Multitasking and the progress window
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If SyncDiscs is configured for multitasking operation, then when
either 'Start' or 'Compare' is clicked, the main SyncDiscs window will
close, and a progress window will open instead. This is shown below.

The progress window shows the operation being carried out, and the
object being operated on. This will continuously update as the
synchronisation or compare continues so you can convince yourself that
things are happening. Note that the display will update only once a
second when scanning through files, but will update immediately when
files are being copied, etc.

If the top right icon (maximise/reduce) is clicked, then the progress
window expands to reveal three buttons.

Pause - Clicking Pause will cause SyncDiscs to stop the processing and
----- 	'mark time'. The Pause button will change to 'Continue'.
	Pressing this will cause SyncDiscs to recommence processing
files, and the continue button will change back into Pause.

Stop - Clicking Stop will terminate the synchronisation or compare
----   process as soon as possible and all processing will stop. If
       there are more jobs remaining in the queue, a dialogue will be
raised asking whether the remaining jobs should be skipped or not.


Note that any Filer_Actions which have already started when either
pause or stop are clicked will continue to completion, but obviously
no more will be started.

If it is necessary to stop the current filer-actions, then they can be
stopped by going in to the Task Manager (click SELECT on the right
hand icon of the iconbar) and click Menu over each filer-action and
choose Quit. Quitting in this way may leave files or directories only
partially copied. Partially copied files will probably be left with
the data file type and are best deleted.

The close button simply closes the progress window, as does the close
icon in the title bar. The progress window can be reopened by simply
clicking on the SyncDiscs iconbar icon. However, if the compare or
synchronisation process has already finished, then the main SyncDiscs
window will be opened instead.

When the SyncDiscs process has completed, then clicking on the iconbar
icon will open the main window again, closing the progress window at
the same time. An alternative is to close the progress window with
ADJUST, when the main window will be automatically reopened.

The Zone file
~~~~~~~~~~~~~
It is possible to have a text file called

!SyncDiscs.Resources.Zone

in which one can specify files that SyncDiscs should ignore when
carrying out a synchronisation. One can match the left hand part of a
path that you want to be ignored by SyncDiscs by using a pattern such
as the following:

ADFS::HardDisc4.$.xxx

It is also possible to match the right hand side of paths by putting
three dots before the file name. So

...tempfile

will make any file called 'tempfile' be ignored.

The facility is made more powerful by the use of wildcards in the zone
file. The character * will match any number of characters, while the
character ? will match one.

Putting all this together, for example, one can ignore all compiler
object files, which are normally in directories named o, with a zone
file entry of

...o.*

This feature should be considered developmental, since it only works
if the individual files are actually seen by the program. If, for
example, the secondary has no 'o' directory, and the setting 'Copy
complete directories' is ticked, then the o directory will be copied
whole.

Note that, if a file to be ignored is found to exist in the secondary,
then that file will be deleted from the secondary.

Command line
~~~~~~~~~~~~
It is possible to call !SyncDiscs with some command line arguments.
You would do this if you wanted to automate the backup procedure. For
example !SyncDiscs can be run from the !Alarm, or !Organizer
applications.

The arguments are:
-quit	            Makes the program execute and then quit. If the
 		    parameter -quit is not used, then SyncDiscs will
		    load to the iconbar with any parameters passed in
		    the command line filled in to the main window. The
		    synchronisation can then be started manually.

-primary<path>    Set the primary path
-secondary<path>  Set the secondary path
-scrap <path>	    Set the scrap path
	
-log<file>	    Set the log file name
~log	            Turn off logging
	
-extra	            Copy extra files from secondary to primary
~extra	            Remove extra files on secondary
	
-newer	            Copy newer files from secondary to primary
~newer	            Don't copy newer files from secondary to primary
	
-over		    Overwrite newer files on secondary
~over		    Don't copy older files from primary to secondary

Missing command line arguments default to the configured values. For
example if no -log argument is provided, the value previously saved
from the main window is used.

Note that SyncDiscs (by design) will not multitask when called from
the command line.

Precautions
~~~~~~~~~~~
SyncDiscs is copying, moving, and perhaps deleting files. Therefore
anything that may interfere with these actions is to be avoided.
Although the operating system should not carry out contradictory
actions on a file at the same time, it may generate errors or error
boxes, which must be dismissed before actions continue, or may
terminate processes prematurely. None of these events are welcome in a
process that may be left to run unattended. If SyncDiscs is being used
in the multitasking environment, then there is even more scope for
unwanted interactions.

When doing a backup, try to ensure that the directory(ies) involved do
not contain any open files, and especially that any files are not
likely to be accessed by other applications while the backup is taking
place. Applications that should be avoided in particular are mail/news
fetchers configured to automatically fetch and debatch periodically,
for example, which do a lot of disc accesses during the fetching and
debatching process.

Note that a number of applications keep files open while they are
running. Some, like Netsurf, for example, keep a log file open at all
times, into which debug information is written. With some
applications, the !Run file is open whenever the application is
running. This is due to there being commands in the !Run file after
the line that launches the application. These commands are not run
until after the application is quit, and so the !Run obey file is
still active. One thing to watch for is the presence of additional
line feeds at the end of a !Run file. These will cause the !Run file
to be kept open until the application is quit. One or other of the
utilities that list open files (e.g. !CloseFiles) is a useful
application to run occasionally, to see what files are actually open.

Contact
~~~~~~~
All communication about SyncDiscs should now be directed to Chris
Johnson (Email:chris@chris-johnson.org.uk). Suggestions for new
features are always welcome.

Web sites
~~~~~~~~~
David Pilling's web site is at http://www.davidpilling.com/, in
particular, the RISC OS section of the site is at
http://www.davidpilling.com/riscos.html.

Chris Johnson's web site is at
http://www.chris-johnson.org.uk/index.html, with his RISC OS software
at http://www.chris-johnson.org.uk/software/index.html.

Screenshots
~~~~~~~~~~~

All the screen shots in these pages were obtained using Snapper, a
versatile screen capture application.

Snapper is another of David Pilling's utilities, and is available from
http://www.chris-johnson.org.uk/software/snap.html



Supplementary information
=========================

More on date and time stamps
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Date and time stamps on RISC OS are simple. There is only one date and
time stamp associated with a file, corresponding to when the file was
last modified (saved). It is therefore simple to compare two date and
time stamps to find which is the newer, or whether they are the same.

Some other OSs have more than one date/time stamp associated with a
file. These may include some or all of:

* Time of creation
* Time last modified (saved)
* Time last accessed
* Time last copied
* Probably others

When using another OS to backup files, time stamps can become a
problem. The following description relates to one of my systems.

I have a type NSLU2 NAS (network attached storage device), which runs
a 'mini' unix OS. I access it using LanMan98. If you copy some files
and/or directories to it and then inspect the date stamps of the
copied files in a filer window using full info mode, you see that the
date/time stamps correspond to the time of the copy, and not when the
file was last modified. The date/time stamps therefore differ between
RISC OS and the external device. Running a SyncDiscs compare will
report that all the files on the NAS (secondary directory) are newer
than those in the primary directory. Very confusing! However, running
a synchronisation at a later date will not copy any files unless their
date/time stamp is later than the time the file was copied to the NAS,
i.e. it is still the case that only changed files will be copied.
There is one complicating factor. You must ensure that the following
options are UNTICKED.

* Copy newer files from secondary to primary
* Overwrite newer files on secondary

If either of these are ticked then there will occur lots of
unnecessary copy operations.

Experiences with other devices and operating systems may be very
different. It would be wise to check any devices you are using for
backups to see how the time stamp behaves in each case, and set the
synchronisation options accordingly.

Syncjob files
~~~~~~~~~~~~~

A syncjob file is created when the menu button to the right of the
Save button in the main control window is used to raise a Save as
dialogue, and the file is saved, either by dragging the file icon to a
Filer window, or by entering the full path and pressing <Return> or
clicking on OK.

The file will contain a complete copy of every setting (as in the main
control window and the additional settings window) as pertaining at
the time the file is created. These settings will be used to start or
queue a synchronisation when the file is subsequently run.

Ways to use syncjob files
~~~~~~~~~~~~~~~~~~~~~~~~~
In order for syncjob files to be recognised and acted on correctly,
then, if SyncDiscs has not already been run, SyncDiscs must have been
'seen' by the filer. This occurs when the directory containing
SyncDiscs is first opened by the filer, or by adding SyncDiscs to
Configure>Boot>Lookat so its !Boot file is run when the machine is
booted.

Double clicking
---------------
Double clicking on a syncjob file displayed in a filer window will
cause SyncDiscs to load and run the file. If SyncDiscs is not already
on the iconbar, then it will be launched first. If SyncDiscs is
idling, then the synchronisation will start immediately. If SyncDiscs
is already running a synchronisation, the new job will be placed in
the job queue, and will be acted on as the queue is processed.

Drag 'n drop
------------
Dragging a syncjob file from a filer display and dropping it onto the
SyncDiscs main window (or progress window) or onto the iconbar icon
will run the file in the same way as double clicking (above). It is
also possible to drag 'n drop a selection of syncjob files, when all
the files will be queued.

Use of the Ctrl key - If the Ctrl key is held down during the drag 'n
drop, then all the settings are loaded into the SyncDiscs control
window, but the job is not run or added to the queue. The settings may
then be modified as required before manually running the
synchronisation or resaving the file. This applies also when double
clicking on a syncjob file. (Note: Dragging a selection of files with
Ctrl held down will load only one set of settings, since the contents
of each file will overwrite the previous contents in the SyncDiscs
dialogue)

Alarm applications
~~~~~~~~~~~~~~~~~~
A common requirement with backup management is to do backups at
regular intervals using an alarm application. This is easily done
using e.g. !Alarm itself or !Organizer.

Alarm
-----
From the iconbar menu select Alarms.... If you already have some
alarms set, the alarm listing will open. Click menu in this window,
and select Set new alarm.

The alarm edit window will open. If you do not yet have any alarms
entered, the alarm edit window will open immediately when you select
Alarms... from the iconbar menu.

You will need to do the following.
* Set the date and time for the first occurrence of the alarm
* Tick the option Task alarm
* Tick the option Repeating alarm. The window will now extend to show
  the frequency options
* Set the frequency at which the alarm is to repeat
* Drag the syncjob file icon from the filer display into the message
  field, where the file path will be entered
* Once happy with the settings click Save. The file will now be run at
the time and frequency specified

Organizer
---------
From the iconbar menu select Alarm.... This will open the dialogue
shown below. To set up an alarm carry out the following.

* Set the time of day when the backup is to take place
* Tick the option Task alarm
* Tick the option Repeating alarm
* In the lower part of the window (only visible once 'Repeating alarm'
  has been ticked) set up the repeat interval
* Drag the syncjob file icon from the filer display into the message
  field, where the file path will be entered
* Once happy with the settings click OK. The file will now be run at
  the time and frequency specified

Obey files
----------
It may be that you want to backup several different directories at the
same time. The simple way is to double click on each of them in turn
to load them into the queue. As an alternative, it may be neater to
set up an obey file to run several syncjobs at the same time. This is
easily accomplished. Create a new obey file in your favourite text
editor. Type in Filer_run followed by a space. Leave the caret where
it is and, while holding down Shift, drag in the syncjob file you wish
to include and then press <Enter>. Holding down the Shift key means
that the file path of the dragged file is entered, rather than the
contents of the file. Repeat for other files as required. 

Now save the file in a suitable location. Make sure it is filetyped as
an obey file. Double clicking on its icon will run it, the effect
being to load all the jobs into the SyncDiscs queue and run them. You
could also set up a task alarm for it in the same way as described
above. When the file is run by the alarm application, the jobs will be
queued in SyncDiscs and processed in turn.

Queue limits
------------
Note that there is a limit to the number of jobs that can be queued at
the same time (20 in version 1.23)


This document last modified on 16th Jan 2011
