Author: Ralf Quint
Description: 
   This document describes the usage for the Backup and
   the Restore program as available in the FreeDOS distribution
KeyWords: Backup, Restore, User Manual


User manual for the FreeDOS Backup & Restore program

                     BACKUP and RESTORE

Usage and Messages
Due to the different versions of BACKUP and RESTORE in the
different DOS versions, there are a lot of differences in
the usage of the programs too.

As FreeDOS basically claims compatibility to MS-DOS 3.3,
the FreeDOS BACKUP and RESTORE programs default to the usage
of this MS-DOS version.  As far as compatibility for different
versions are implemented, a few additional switches and
options are introduced.

Additional Switches
    /?,/h       show short usage/help message on the screen

                The /? is a requirement of FreeDOS, the /h is
                added for convenience.  All other options given
                in combination with these switches are ignored

    /v[version] define the version of compatibility

                As far as compatibility for different DOS
                versions is implemented, the /v switch can
                force the programs to behave accordingly.
                32 or 3.2 The program uses data format and
                          options of the BACKUP/RESTORE
                          command of MS-DOS 3.2x and earlier
                33 or 3.3 The program uses data format and
                          options of the BACKUP/RESTORE of
                          MS-DOS 3.3 to 5.0x
                          This is the default for both programs

                So far, this switch is only required for the
                BACKUP program as the RESTORE program is able
                to determine the data format on it's own.


BACKUP
Back up one or more files from one disk onto another.

    Syntax:
    backup <source> <destination-drive:> [/s] [/m] [/a] 
           [/f[:size]] [/d:date] [/t:time] 
           [/l[:[drive:][path]logfile]] [/p] [/{?,h}]

    Parameters:
    source
      Specifies the location of the files you want to back up.
    Source can consist of a drive letter and a colon, a directory
    name, a filename or a combination.

    destination-drive:
      Specifies the drive that contains the disk on which you
    want to store any backup files. The backup files are stored
    accordingly to the chosen compatibility mode (default is
    MS-DOS 3.3+)

    Switches:
    /s Backup all files of all subdirectories recursed into
    /m Back up only files that have been changed since the last
       backup (that means all files where the Archive attribute
       is set) and turns off the archive attribute of the
       original file.
    /a Add backup files to an existing backup disk without
       deleting existing files
    /f[:size] Format the destination drive.  If no size is given,
       the default for this drive is selected.
       <Not implemented yet!>
    /d:date Backup all matching files changed on or after the
       given date
       <Not implemented yet!>
    /t:time Backup all matching files changed at or after the
       given time
       <Not implemented yet!>
    /l[:[drive:][path]logfile] Write the filesname of all
       backed up files and all error messages to a logfile.
       <Not implemented yet!>
    /p <Not implemented yet!>
    /{?,h} This is a FreeDOS specific extension to show a help
        screen with the usage explanations.

Return codes/Errorlevels
The BACKUP command sets the ERRORLEVEL (return code) as follows:
 0 Normal completion
 1 No files were found to backup
 2 Some files not backed up due to sharing conflicts
 3 Terminated by user (Ctrl-Break or ESC)
 4 Terminated due to error

    Notes:
    - The BACKUP program allows only to do backups from a fixed
    disk to a diskette (removable disk). Other combinations will
    only be implemented if there are enough resonable requests
    for it.
    - The BACKUP program doesn't do a format of the destination
    diskettes (yet).

    Examples:
    <none>

RESTORE
Restore files that have been backed up by the BACKUP command.

    Syntax:
    restore <drive1:> <drive2:>[path[filename]] [/s] [/p] 
            [/b:date] [/a:date] [/e:time] [/l:time][/m] [/n] [/d]

    Parameters:
    drive1: The drive that contains the backed-up files
    drive2: The drive to which the backed-up files are going to
       be restored
    path The directory to which the backed-up files are going
       to be restored. In MS-DOS you had to specify the same
       directory form which the files were backed-up. The
       FreeDOS restore program allows to specify any directory
       as the base for the to be restored directory structure.
    filename The names of the files that are going to be restored

    Switches:
    /s Restore all subdirectories
    /p Prompt for permission to restore files that are marked as
       read-only or that have changed since the last backup
       (archive bit set)
    /b:date Restore only those files modified on or before the
       given date.

The following switches are only valid for backup files with the data format of the DOS versions 3.3x to 5.0x
    /a:date Restore only those files modified on or after the
       given date.
       Note: As country specific settings are not implemented yet,
             the format for the date has to be given as YYYY-MM-DD.
             This is Y2K safe and the most universal format anyway.
    /e:time Restore only those files modified at or earlier than
       the given time
    /l:time Restore only those files modified at or later than
       the given time
       Note: the time has to be given in 24h format. A check for
             the american 12h format has not (yet) be implemented
    /m Restore only those files modified since the last backup
       (archive bit set)
    /n Restore only those files that dont exist on the
       destination drive
    /d Display those files that match the files specified for
       backup without actually restoring any files
       Note: even though no files are actually restored, you have
             to specify drive2
    /{?,h} This is a FreeDOS specific extension to show a help
       screen with the usage explanations.

Return codes/Errorlevels
The RESTORE command sets the ERRORLEVEL (return code) as follows:
 0 Normal completion
 1 No files were found to restore
 2 Some files not restored due to sharing conflicts
 3 Terminated by user (Ctrl-Break or ESC)
 4 Terminated due to error

    Notes:
    - To do a better job on restoring incomplete backup sets, the
    /d option uses a different format for the output list of files.
    It will show the sequence number of the disk (in case the disks
    are not marked properly) and it will also show special notes
    about split files at the beginning or the end of the disk.
    In case of the restore of an incomplete backup set, this way
    the user can make a decision to restore partial files before
    the actual restore procedure.

    Examples:
    <none>

End.
