[ Back to Table of Contents ]
[ << ]
[ >> ]
XXCOPY TECHNICAL BULLETIN #19
From: Kan Yabumoto tech@xxcopy.com
To: XXCOPY user
Subject: XXCOPY in batch files
Date: 2000-12-31 (revised)
===============================================================================
Introduction:
XXCOPY as a general purpose file management tool, works well
as a hand-typed command in a DOS Box. It is also a useful
building block of a complex task written as a batch file
for a job like a full system backup, daily incremental backup
as well as a specialized project archiving. In these cases,
the whole job is made of a series of XXCOPY commands since
XXCOPY is better suited to handle one directory (and its
subdirectories) at a time. It is not uncommon that a well-
written batch file for a backup job consists of ten or more
lines of XXCOPY commands.
Since XXCOPY plays an important role in batch programming,
mastering its command switches which are designed for such
purposes will help you write better batch files. The switches
that are particularly useful inside a batch file are:
/YY /CB /CBQ /CE /EC /IA /IP
How to get rid of the Y/N prompt.
This is probably the most frequently asked question with
regard to batch files.
-------------------------------------------------------------
The following command shows the switches which prompt you.
XXCOPY /YY /?
-------------------------------------------------------------
XXCOPY provides various switches to suppress specific
user prompts. For example, /ZY is a variation of /Z
which does not produce user prompts and good for batch
file. Similarly, /PD0 suppresses a user prompt for
directory processing (mostly for deletion). But, it becomes
a hassle even to an experienced XXCOPY users. Yes, XXCOPY
has grown to be a monster with so many switches, you just
can't remember all. So, we now have an all-purpose prompt
buster switch, /YY (super-YES).
-------------------------------------------------------------
Note: although the use of /YY is very convenient to remove
the various warning prompts, it is recommended only
in well-tested batch files where any typing error
would not cause any serious damage.
E.g. XXCOPY %1 %2 /CLONE /YY
This is probably the worst place to use the /YY
switch. A user-supplied parameters (%1 and %2)
in a batch file make the command is susceptible to
human error.
Just remember that the various warning prompts are
there for good reason. Using the /YY switch, you
are denying yourself benefit of the safeguard.
------------------------------------------------------------
Example of a standard batch file.
Advanced batch programmers test the exit code (ERRORLEVEL)
returned by a program and branch off if certain conditions
are met (e.g., terminate when a fatal error occurs). Due to
the severe limitation in the batch language, a typical batch
file with conditional branching usually looks quite unsightly.
------------------------------------------------------
XXCOPY c:\windows\ d:\backup\windows\ /S /Y
IF ERRORLEVEL 100 GOTO step2
IF ERRORLEVEL 1 GOTO end
:step2
XXCOPY c:\mydir\ d:\backup\mydir\ /S /Y
IF ERRORLEVEL 100 GOTO step3
IF ERRORLEVEL 1 GOTO end
:step3
XXCOPY c:\yourdir\ d:\backup\yourdir\ /S /Y
IF ERRORLEVEL 100 GOTO step3
IF ERRORLEVEL 1 GOTO end
...
:end
------------------------------------------------------
Here, the ERRORLEVEL returned by XXCOPY is tested for both
the lower and the upper bounds to perform the conditional
branching. Most of the typing is consumed for the error
handling. It takes a lot of self discipline to write a good
bath file with proper testing.
By the way, a list of the exit code generated by XXCOPY can
be viewed by running the following command:
XXCOPY /HELPE
Also see article: XXTB #31, about Exit Code.
Using the /CB switch, the same sequence becomes...
------------------------------------------------------
XXCOPY c:\windows\ d:\backup\windows\ /S /Y
XXCOPY /CB c:\mydir\ d:\backup\mydir\ /S /Y
XXCOPY /CB c:\yourdir\ d:\backup\yourdir\ /S /Y
...
:end
------------------------------------------------------
In this alternative batch file, the IF ERRORLEVEL... lines
are eliminated by the use of the /CB switch (except the first
line). The /CB switch which stands for "Continue-Batch"
examines the exit code returned by the previous execution of
XXCOPY and immediately terminates the current execution if
the previous error condition was fatal (such as disk-full,
or a user-abort). How does one instance of XXCOPY know
the exit code of its previous run? Simple. XXCOPY stores
its exit code in the system registry for its own retrieval
later. Notice that there is no awkward branching in the
batch file. Actually, the exit code of one XXCOPY is NOT
examined by the batch execution mechanism. Therefore, the
flow of the batch file is always to execute all the lines
in the file. The /CB switch provides a mechanism where a
fatal error reported by one XXCOPY instance will propagate
through the rest of the batch file execution that all
subsequent XXCOPY lines with the /CB switch will be nullified.
Note: The position of the /CB switch within the command
line is not significant. Because of it's early action,
it seems most appropriate to place it early on the line.
/CBQ for a cleaner screen when the batch file is aborted.
Actually, /CBQ (the quiet version) is preferred by most
users since this version will keep the console screen
much cleaner when it is combined with a "ECHO OFF"
statement in the batch file.
------------------------------------------------------
@ECHO OFF
XXCOPY c:\windows\ d:\backup\windows\ /S /Y
XXCOPY /CBQ c:\mydir\ d:\backup\mydir\ /S /Y
XXCOPY /CBQ c:\yourdir\ d:\backup\yourdir\ /S /Y
...
:end
------------------------------------------------------
The virtue of running the batch file with the ECHO OFF
setting is that the XXCOPY lines subsequent to a fatal error
of an XXCOPY will not clobber the screen. The last XXCOPY
line with the error message will not be pushed off the screen
with echoed command lines even though they terminate immediately.
---------------------------------------------------------
What does the @ECHO OFF statement do?
ECHO OFF inside a batch file turns off the display
of the command line (the current line in the batch
file. Without it, every line in the batch file will
appear on your console. An at sign (@) at the beginning
of a line in a batch file turns off echoing just one
line (You may add an at sign (@) on every line to have
the same effect as ECHO OFF. The first at sign (@) in
the first line suppressing the echoing of its line, too.
---------------------------------------------------------
/EC and /CE for even a better batch file.
The problem of running the batch file with ECHO OFF mode
is that the screen will not show the command invocation.
What we really want is to generate no output to the console
when XXCOPY is terminated by the /CB mechanism but to echo
the invocation line if it will continue the execution.
That is what /EC (to echo the command line) does. Moreover
the /CBQ/EC combination is so handy in a batch file, XXCOPY
assigns a new switch, /CE as the shortcut for /CBQ/EC.
So, rewriting the same batch file, it should look like
------------------------------------------------------
@ECHO OFF
XXCOPY /EC c:\windows\ d:\backup\windows\ /S /Y
XXCOPY /CE c:\mydir\ d:\backup\mydir\ /S /Y
XXCOPY /CE c:\yourdir\ d:\backup\yourdir\ /S /Y
...
:end
------------------------------------------------------
Note that it is not a typo! The first line uses /EC (echo)
and the other lines are with /CE (shortcut for /CBQ/EC).
It looks symmetrical and even cute.
Using XXCOPY macro to create a unique destination.
When you create a batch file for a periodic (daily) backup,
you may want to encode the current date (today) as a part
of the destination directory name you create. XXCOPY's macro
reference feature (/$xxxx$) was designed exactly for that.
For example, when you can enter
XXCOPY C:\ D:\mybackup\DB/$YYMMDD$\ /CLONE
and it will be expanded to
XXCOPY C:\ D:\mybackup\DB011225\ /CLONE
(assuming the current (today's) date is December 25, 2001.)
See article: XXTB #24, about Macros.
Testing if a directory exists
The following sequence is a well established technique to
test whether or not a directory exists in a batch file.
------------------------------------------------------
IF EXIST d:\backup\mybackup\nul goto next
XXCOPY c:\ d:\backup\mybackup\ /CLONE
:next
------------------------------------------------------
The IF EXIST (and IF NOT EXIST) construct is good only for a
file, not a directory. Here, the neat trick is based upon the
fact the virtual file, "NUL" is guaranteed to exist on any
directory.
Now, using XXCOPY'S /IA (which stands for "If Absent"),
the same command line will be re-written as
------------------------------------------------------
XXCOPY c:\ d:\backup\mybackup\ /IA /CLONE
------------------------------------------------------
The /IA switch continues to run only if the destination directory
is absent (that is, /IA will terminate immediately if the
destination exists). It is equivalent to the "IF NOT EXIST"
construct in the batch file. On the other hand, /IP (If Present)
continues to run only if the destination is present (that is,
/IP will terminate immediately if the destination does not exist).
it is exact opposite of /IA.
Testing a directory using macro.
The power of /IA and /IP becomes even more evident when you use
a destination directory which is specified by a macro reference.
------------------------------------------------------
XXCOPY c:\ d:\backup\DB/$YYMMDD$\ /IA /CLONE
------------------------------------------------------
In this case, it's not a matter of making the batch file shorter
and prettier. There is no simple way to test the presence or the
absence of a directory whose name is "synthesized".
This command executes only when the directory is absent.
This technique prevents running the same daily backup routine
twice on the same day.
© Copyright 2010 Pixelab, Inc. All rights reserved.
