[ Back to Table of Contents ]
[ << ]
[ >> ]
XXCOPY TECHNICAL BULLETIN #37
From: Kan Yabumoto tech@xxcopy.com
To: XXCOPY user
Subject: Format Specifications of Command File in XXCOPY
Date: 2003-10-30 (revised)
====================================================================
Introduction:
XXCOPY provides a mechanism to allow the user to specify the
invocation command using text files. Currently, there are two
cases of accepting the command input from a text file.
/CF<cfile> // command file for regular command text
/EX<xfile> // exclusion file; lists exclusion items
-----------------------------------------------------------
The only difference between the two types of text file
is that the command file (by /CF) contains the command
text that consists of ordinary XXCOPY command arguments
and switches whereas the exclusion file (by /EX) holds
a list of exclusion items (file and directory specifiers)
without the "/X" command-prefix on each exclusion item.
Other than this difference, the two types of file follow
the same set of rules in their format.
-----------------------------------------------------------
The purpose of XXCOPY's command file is to allow the user
to compose a command text that may exceed the limit of the
command line length.
Since the command line syntax of the original XCOPY (and
earlier versions of XXCOPY) had to cope with the limit in
the overall length of the command line, the command switches
were designed to be short, hence often cryptic. As a
consequence, the readability suffered.
Once we are free from the limit in text length, we can use
the freedom to our advantage. Of course, the command file
still accepts the same command text that you would enter
directly to the command line. You may think of the command
file as an "include" file that supplies a stream of text to
the command line.
E.g., XXCOPY /CF:myfile.xcf
This invocation is equivalent to running the XXCOPY
program by typing the contents of the myfile.xcf
file directly at the command line.
You may add switches before or after the /CF switch. In
addition, you may use two or more /CF switches in one line.
All of them are evaluated from left to right.
E.g., XXCOPY /Q /CF:myfile.xcf /WE
Examples Speak Tons:
For those who are in a hurry and rely on intuition by looking
at a few examples, let me show a few of them with ample comments.
If you read all the comments in the examples, most of the
key features are explained. But for air-tight definitions
of the format rules, you must read the lengthy (and boring)
details that follow.
Let me start with a short one.
script1.xcf
-----------------------------------------------------------
"C:\My Programs\" c:\backup\ /CLONE // daily backup
-----------------------------------------------------------
This is a one-line script. The line is just like an
ordinary XXCOPY command line except that it does not
contain the "XXCOPY" word itself at the beginning.
Again, to run this script,
XXCOPY /CF:c:\bin\script1.xcf
Note: the comment is allowed even in the real command line
--- this becomes handy in a batch file.
Here comes a little more realistic example.
script2.xcf
-----------------------------------------------------------
// This script should be run once a day.
"C:\My Programs\" // the source specifier
c:\backup\myprog\ // the destination dir
/CLONE // save the latest
/Z0 // don't remove extra files
/oN:c:\bin\script1.log // create a log file
/WE // wait for a key at the end
-----------------------------------------------------------
My first recommendation is to place only one command item
per line and to add a comment on each line.
Finally, let me give you a classy example. The text in it
is meant to explain the various features of the command file.
script3.xcf
-----------------------------------------------------------
/*****************************************************
* *
* script3.xcf created 2002-05-05 *
* *
* This XXCOPY script carries out a daily *
* incremental backup operation from C: to E: *
* The E: drive may be made bootable as C:. *
* *
* Invocation: xxcopy /cf:c:\backup\script3.xcf *
* *
* Log file: c:\backup\script3.log *
* *
* Note: A command filename may have any extension. *
* We use .XCF (for Xxcopy Command File). *
* *
*****************************************************/
C:\ // source (the whole system disk)
E:\ // destination (mirror disk)
/clone // my favorite switch
/PZ0 // prompt killer (for /Z)
/ON:c:\backup\script3.log // create a log file
/Fo:c:\backup\script3.lst // save file list
/FM:dtzl // list file format control
// list of exclusions ------------------------------
/X:*.tmp // no temp files
/X:\Windows\*\cache*\ // cache files of any kind
/X:\*\cookies\ // cookies are junk food
/X:"c:\My documents\my pictures\2002-May// string split
\Susie's birthday\*.jpg" // into 2 lines
/*
A // sequence preceded by a non-blank character
allows you to logically connect two lines.
(This is a traditional C-like comment.)
*/
/EX:c:\backup\exclude.lst // you may use /EX inside
/CF:c:\backup\another.xcf // nestable (up to 8 levels)
:: An in-line comment may start by // or :: which ends
// at the end of the line.
-----------------------------------------------------------
Note to experienced programmers:
The Command File format is modeled after modern
programming languages like C. A few exceptions:
1. A comment does not behave as a blank.
2. A comment may be inside a quoted string.
3. It has a peculiar line-continuation mechanism.
Command File Basic Rules (also applies to Exclusion File):
The XXCOPY command file is an ordinary plain text file that
can be created/edited by any text editor (e.g., Notepad).
Currently, only a 8-bit characters are supported. I.e.,
Unicode text is not supported, yet.
You may add any number of lines in the command file.
Each line is terminated by a CR (Carriage Return),
a LF (Linefeed), or a CR-LF sequence. We call them
line-break, collectively.
A TAB character can be used interchangeably with a space
(also called blank). In this document, we use the word
blank which may actually be a TAB. (A TAB character is
not allowed in a file or directory name.)
A line-break is usually treated as a blank.
There is a provision to make two (or more) lines behave
like a continuous line using the Line Continuation Mechanism
(see below).
All the usual XXCOPY command line syntax applies to the
command file text.
------------------------------------------------------------
The XXCOPY command line contains two kinds of arguments:
1. Command switches (also called options) that always start
with a slash (/) character (one exception to this
rule is a macro reference that has the /$xxxx$ sequence
which may appear as a non-switch argument).
2. Non-switch arguments that do not start with a slash (/).
The first non-switch argument is always the source
specifier and the second (optional) non-switch argument
is always the destination directory specifier.
The two types of arguments can be ordered in any way
except that the source specifier always comes before the
destination specifier.
Command switches are evaluated by the order they appear.
Some related switches are affected by the evaluation order.
--------------------------------------------------------------
Comments:
You are encourage to add abundant comments to clarify
the meaning and the intent of the command switches.
Comments are strictly for people and ignored by XXCOPY.
Two styles of comments are supported:
1. In-line comment // like this one
An in-line comment starts at either // or :: and
extends until the end of line. It can start anywhere
in the line including at the beginning of the line.
2. Bracketed comment /* like this */
A bracketed comment begins at /* and ends at */ which
may straddle over two or more lines.
Precedence of comments:
The two styles are of equal precedence. That is, when
an in-line comment is specified, a /* sequence specified
to the right hand side of the in-line comment header
(// or ::) within the same line is completely ignored.
Similarly, once a bracketed comment field is started by
a /* sequence, either // or :: within the bracketed
comment field has no effect until the terminator, */ is
encountered.
Not a substitute for a blank:
Unlike most programming languages which treat a comment
field as a blank, XXCOPY does not treat either an
in-line comment or a bracketed comment as a blank.
That is, a bracketed comment field that begins at /* and
ends at */ may even be placed within a path specifier
(this bad habit is strongly discouraged, nevertheless,
it is syntactically acceptable).
Comments within a quoted string:
The comments and line-continuation mechanisms are totally
independent of whether or not they appear within a quoted
string (surrounded by a pair of double-quotes, ").
No carry-over of a comment:
An open bracketed comment which is started by /* but not
terminated by */ within the command file will be implicitly
terminated so that a runaway comment (a syntax error) will
not be carried over to outside of the file.
Line Continuation Mechanism:
Since Windows' long filename (LFN) may have as many as
256 characters, the whole string may not be visible in
a window of a text editor if it is entered as one long
string. XXCOPY's command file format allows you to break
up a long string into multiple lines to facilitate the
handling and help improve the readability while treating
it logically as a single string.
There are two ways to logically connects adjacent lines.
Both of them take advantage of the way XXCOPY treats the
comment field (the In-line comment and the Bracketed comment
as discussed above). Let me explain the use of Bracketed
comment first which is probably easier to use.
Bracketed comment to connect adjacent lines:
Since a bracketed comment will be removed by XXCOPY
as the first step in processing a command text, it provies
a simple way to connect two lines. All the characters
between the /* sequence and the */ sequence (including
the beginning and ending two characters) will be completely
reremoved from the text.
Example:
"C:\Documents and Settings\Default User\/* comment
*/Application Data\"
In this example, the above two lines are the same as
"C:\Documents and Settings\Default User\Application Data\"
Unlike in common programming languages such as C, the
bracketted comment will not be substituted by a space
character. Therefore, the absence of any space character
before and after the comment field will result in the
combined string without space. as shown above. You may
also break the line after a space. The following example
is another example to split the same path name above.
"C:\Documents and Settings\Default /* glue comment
*/User\Application Data\" // regular comment
Note that the exact number of the space character is
preserved by this technique.
Needless to say, you may connect an arbitrary number of
lines into one logical string.
Example:
"C:\Program Files\Microsoft Visual /*
*/Studio .NET\Vc7\VCWizards\Classwiz/*
*/\MFC\Simple\Templates\1033/*
*/\doc.cpp"
In-line comment to connect adjacent lines:
A line whose in-line comment field (that starts with //
or ::) is immediately preceded by any character other than
a blank will be logically connected to the first non-blank
character in the next line.
Example:
/ON:c:\my_directory\and_this_path_name_is// comment
\connected_like_this\logfile.txt
In this example, the in-line comment that begins at //
is placed without any blank. Any leading blank
(space or tab) character in the next line will be
discarded. In the above example, the second line that
starts at the backslash connects to the previous line
immediately before the comment-marker (//).
Example:
"C:\Program Files\Micro::
soft Internet\Inter// add comment if you want
net Mail\cookies.txt"
Here, a filename is broken up into three lines and
was not split at a clean boundary of a directory name.
Note that the line-continuation may connect lines
even within a quoted string.
Note:
You may add blanks at the beginning of the continuing
line that follow the line continuation sequence to
improve readability (the leading blanks are ignored).
It is recommended that a filename string be split at
a non-blank character. If you are forced to split a
filename before or after a space character, you may
do so by use of the bracketed comment (/* .. */).
The following two pairs of lines are equivalent.
E.g., "C:\Program Files\Microsoft Internet\Internet//
/* before a space */ Mail\cookies.txt"
"C:\Program Files\Microsoft /* after a space */::
Internet\Internet Mail\cookies.txt"
But, then, it is probably simpler to use the bracketed
comment to begin with.
E.g., "C:\Program Files\Microsoft /*
*/Internet\Internet Mail\cookies.txt"
The choice between the bracketed comment scheme and the in-line
comment scheme as the mechanims for line-connection is totally
up to the user. Some people just do not like the way the
continuing line looks which typically starts with a funny
sequence (*/). The in-line comment method allows you to start
the continueing line with your characters.
Either of the methods does not force you to start the
continuing text at the first colume even though it will
be perfectly legal.
Colon after a command switch:
With the command file feature, the old syntax of making
the command as short as possible is no longer a virtue.
Now, readability has precedence over compactness.
Any XXCOPY command switch that accepts a parameter may use
a colon to separate the command letter(s) from its parameter
except in cases where a non-alphanumeric character is a
syntactic element of the switch.
/ONmyfile.log /IN*.tmp /FMdtl /Q2
/ON:myfile.log /IN:*.tmp /FM:dtl /Q:2
Here are the exceptional cases where a colon cannot be added:
/DA#4 /SZ!5-10 /TD+5
Note: the colon as a separator between the switch letter(s)
and its parameter is strictly optional and is not a
required element in the XXCOPY command.
Of course, there are a few cases where a colon is a
required character that distinguishes between like
variations (e.g., /DA:2002 and /DA#2000).
Nesting:
Since the text in a command file can contain any valid XXCOPY
command arguments and switches, it is natural to allow a /CF
switch within a command file. It is called Nesting.
To avoid a possible recursive inclusion (which would result in
an infinite loop), XXCOPY sets the maximum nesting levels to 8.
Nesting a command file (/CF) or using a exclusion file (/EX)
usually add a complexity to the command organization. But if
used judiciously, the technique may factor common sets of
command switches and exclusion items.
On the other hand, a single /CF file organization (without
embedded /CF or /EX) is most straightforward. It also allows
viewing the entire XXCOPY in one self-sufficient file.
© Copyright 2008 Pixelab, Inc. All rights reserved.
