Jump back to the top page Jump back to the top page
 

 Home
 What is XXCOPY ?
 Products
 Downloads
 F A Q 
 Order
 Support
 About Us (Pixelab) 
On-Line Manual 
XXTB #001 
XXTB #002 
XXTB #003 
XXTB #004 
XXTB #005 
             . . .  


XXCOPY
Version
3.33.3


Released
2016-10-28
©2016 Copyright
Pixelab

 All rights reserved  
    [ Table of Contents ] [ Show as Detached ] [ >> ]

    XXCOPY TECHNICAL BULLETIN #037

    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.
    
    
    
    
    [ Table of Contents ] [ Show as Detached ] [ >> ]