XXCOPY
[ 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:    2010-01-01 (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 disk)
     E:\backup\/%USERNAME%\     // dst (the subdirectory
                                // is named after the value
                                // in Environment Variable
                                // USERNAME)

     /clone                      // my favorite switch     
     /PZ0                        // prompt killer (for /Z)
     /ON:c:\backup\/$yyyy-mm-dd$.log   // create a log file
                                 // Macro for today's date
     /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$ (or /%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.

  Macro reference (/$xxxx$ and /%xxxx%):

    A sequence that starts with a slash followed by word(s) that
    are sandwiched by a pair of dollar signs (/$xxxx$) will be
    substituted by the value pre-defined by the macro rules.
    For example, the sequence, /$yyyy-mm-dd$ will be replaced by
    today's year, month and day value.

    Similarly a slash followed by a word sandwiched by a pair of
    percent signs (/%xxxx%) are substitued by the corresponding
    environment variable (E-var).  This is similar to the command
    line processing rule that also applies to batch files.  Note
    that the command line text that XXCOPY receives from the system
    are pre-processed for E-vars whereas the E-vars that are
    referenced inside XXCOPY's command file is beyond CMD.EXE's
    reach (that XXCOPY will process using its rule).  Note that
    a reference to an E-var inside command file requires a leading
    slash character.

    (See XXTB #24 for details.)


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

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

Join the XXCOPY group