XXCOPY
[ 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 2016 Pixelab All rights reserved.

[ XXCOPY Home ] [ Table of Contents ] [ << ] [ >> ]

Join the XXCOPY group