Media Share 9/MEDIASHARE_09.ISO/utility/xt302.zip/XT.DOC

Text File | 1992-07-06 | 21KB | 502 lines

═════════════════════════════════════════════════════════════════════
XT 3.02 [Jul 06 1992]     Copyright (c) 1991, 1992 by Paul Whittemore
═════════════════════════════════════════════════════════════════════

Summary
═══════
See the license agreement at the end of this  document  before  using
this program.  Don't worry, it's as liberal as they get.

What is XT?    A lot of people demanded this one.   It is one of the
single most important utilities I have (next to my text editor and a
couple others).  It has a single general goal, but in accomplishing
this goal, the program becomes a multi-purpose utility.

XT's goal is to provide a general way of traversing a DOS directory
structure performing an arbitrary operation on a subset of the files
found.  In many ways it resembles an improved version of earlier
'SWEEP'-like utilities.  Much user feedback has been applied since
it's first incarnation and improvements continue to be made to the
program.
                              ══════════
                               WARNING!
                              ══════════
WARNING:  This command is very powerful.  With power comes responsibility.
If you are unsure of a command, do NOT use XT, or use the -n option to
test it first.  The author is not responsible for any loss due to the use
(or abuse) of this program.


Version 3
═════════
Major changes have been made to the program for version 3.0.  Many of
the existing features have been improved upon and many new features
have been added.
                              ══════════
                               WARNING!
                              ══════════
WARNING:  Version 3 is NOT compatible with all of the options and command
template filter escapes of earlier versions!  Most batch files containing
XT commands will need to be converted.


Syntax
══════

This is perhaps the most difficult aspect of XT.  Although completely
consistent, many people find the command line very confusing.  The
syntax is:

        XT  [<options> [<filespec> [<command-template>] ] ]

Before we get to the actual options, an explanation is in order.

XT will traverse a given directory tree applying a command for every
match.  XT without a command template will simply list all matches.
If no filespec (pattern) is specified, "*.*" is assumed.  The
<command-template> field can be as long as DOS will allow the line
and can specify any command including batch (.BAT) files.

Some examples:

  XT readme.doc
    - displays the name of all README.DOC files in and under the
      current directory.

  XT
    - displays the names of all files in and under the current directory.

  XT *.com
    - displays the names of all files whose filename extension is '.COM'.

  XT readme.doc attrib +r readme.doc
    - mark the file readme.doc read-only
      (by executing the DOS ATTRIB command).

In the last example, "attrib +r readme.doc" is the <command-template>
part of the command line.  Rather than retyping the name of the file
(readme.doc), XT has special placeholders which begin with a dollar
sign ($).  For example, $n represents the name (root + extension) of
the file.  Thus, the previous command could have been abreviated to
the following:

        XT readme.doc attrib +r $n

In fact, XT is recursive, so in this case it will search the current
directory as well as all subdirectories for all occurrences of the
file README.DOC.  Unfortunately (or perhaps fortunately?), it will
execute the command "attrib +r readme.doc" once for each match so if
there are four matching files, it will mark the SAME copy of README.DOC
in the current directory read-only each time, or in this case,
FOUR TIMES!

The solution depends on what you wanted to accomplish.  Getting a
little ahead of things, there are many command line options,
including the -r option which disables the recursive decent of the
directory tree.  So the command:

        XT -r *.doc attrib +r $n

will mark read-only all files .DOC files in the CURRENT directory
only.

If you wanted to mark ALL .DOC files in ALL subdirectories (and the
current one) read-only, you could leave out the -r and substitute $f
for $n:

        XT *.doc attrib +r $f

The full set of such template escape sequences is given below.
Template Escape Codes
═════════════════════
The following command template escape codes (placeholders) may occur
as many times as desirable in the <command-template> part of the
command line:

        $f  the full path name of the matching file or directory
        $F  same as $f but with trailing '\' (if -d option used only)
        $p  the base (common) part of the matching path
        $P  same as $p but with trailing '\'
        $d  the relative directory part of the matching path
        $D  same as $d but with trailing '\'
        $n  the filename & ext of the matching file or directory
        $N  same as $n but with trailing '\' (if -d option used only)
        $r  the root file name of the matching file or directory
        $e  the extension name of the matching file or directory
        $?  place marker for $\ escape code
        $\  conditional path separator (\) if non-null since last $?
        $$  a dollar sign ($).  '$' + anything else is that char.

Another example:  Assume your current directory is C:\TOPLEVEL and
you execute the following command:

        XT *.doc

Let's say XT displays the following files:

        1.  C:\TOPLEVEL\README.DOC
        2.  C:\TOPLEVEL\PERSONAL\RESUME.DOC
        3.  C:\TOPLEVEL\SUBDIR1\README.DOC
        4.  C:\TOPLEVEL\UTILITY\XT\XT.DOC
        5.  C:\TOPLEVEL\UTILITY\LS304\LS.DOC
        (The numbers are for reference below.)

The paths above represent the value of $f for each match.  The value
of $p and $P are constant for each execution of XT, in this case they
will have values of "C:\TOPLEVEL" and "C:\TOPLEVEL\", respectively.
The quotes are for readability in this document only.  Note the trailing
slash on the value for $P.  The values of the $d and $D are listed below:

        Match    $d               $D
        ----- ---------------- ----------------
          1      ""               ""
          2   "PERSONAL"       "PERSONAL\"
          3   "SUBDIR1"        "SUBDIR1\"
          4   "UTILITY\XT"     "UTILITY\XT\"
          5   "UTILITY\LS305"  "UTILITY\LS305\"

In the examples above, $n is always "README.DOC", $r is always "README",
and $e is always ".DOC".  The value of $f is always the concatenation of
$P$D$n or $P$D$r$e.  Note that in the case of an empty value for any given
escape code, the corresponding uppercase escape code will also be empty.
(A backslash path separator (\) will NOT be appended to an empty path.)

IMPORTANT:  The $\ escape code represents a conditional path separator.
If the command template's expanded value since the last $? marker is
non-null, a slash will be appended at the point of the $\.  For
example, "$?$d$\abc" will expand to "xyz\abc" if $d is "XYZ", but
will expand to just "abc" if $d is empty (NOT "\abc").
Options
═══════
The following options can be specified before the <filespec> pattern
(if present):

         -h, -?  displays this usage help
             -r  non-recursive (do NOT scan subdirectories)
             -c  change to directory of match before running command
             -d  match directory names only
             -q  enables quiet mode (includes -e)
             -e  disables command echo
             -n  do not execute commands (echo only)
             -f  force continue with next match on program error return codes
             -F  force continue with next match on Ctrl-C/Ctrl-Break in cmd
             -p  patterned list of directories only
             -s  disable line splitting
          -s<c>  use character <c> for line separator (default ';')
          -xext  exclude files with .ext extension
             -!  force use of COMMAND.COM(COMSPEC) if not found
        (-p assumes -n, just lists matches as in template specified)


The -p option is useful in creating batch files.  For example, the
command:

        XT -p *.doc copy $f d:\docs >copydocs.bat

might produce a file COPYDOCS.BAT containing:

        copy C:\TOPLEVEL\README.DOC d:\docs
        copy C:\TOPLEVEL\PERSONAL\RESUME.DOC d:\docs
        copy C:\TOPLEVEL\SUBDIR1\README.DOC d:\docs
        copy C:\TOPLEVEL\UTILITY\XT\XT.DOC d:\docs
        copy C:\TOPLEVEL\UTILITY\LS304\LS.DOC d:\docs
A Word about (!) and (-!)
═════════════════════════
For reliability, the program specified by the COMSPEC environment
variable (usually COMMAND.COM) is NOT used to execute a command (by
default).  When XT does not run programs directly, it cannot tell if
execution was successful or not, neither can it detect what error code
(if any) was returned by the program.  Furthermore, if a secondary program
such as COMMAND.COM is used to execute the command, XT cannot tell if the
command was aborted via Ctrl-C or Ctrl-Break keystrokes.

When given a command template to execute, XT will use the following
procedure:
    1.  If a path (relative or absolute) is part of the command name,
        or if the command name contains a '.', the name will be used
        as is.
    2.  Otherwise, it will search the current directory, then each
        directory in the PATH environment variable for the specified
        program.  In each case, it will first look for a .COM file,
        then a .EXE file, and finally a .BAT file.
    3.  If the matching file is a .BAT file, the command will be
        executed via the program specified by the COMSPEC variable
        (usually COMMAND.COM).
    4.  If the matching file is a .COM or .EXE file, it will be executed
        directly.
    5.  If no matching file is found, XT will abort with an
        appropriate error message.

If the command template starts with an exclamation mark (!), XT will
always execute the command indirectly through the COMSPEC command
interpreter, regardless of the matching file's extension.  In this
case, XT will not be able to detect an error executing the program,
except for errors executing the command interpreter itself.

The -! option forces the use of the COMSPEC interpreter for all
commands regardless of the ! command prefix.

The ! command prefix should be used for commands which are builtin
to the command interpreter (such as COPY and DEL).
A Word About The -d Option
══════════════════════════
The -d option applies the pattern specified by <filespec> to
directory entries rather than regular files.  The matching directory
entry can be referenced by any of the escape codes including the $n
and $f escape codes, just like it is for matching files.  This can be
confusing but is, at least, consistent.

To list all directories starting with 'T', the following command
would be used:

        xt -d t*.*

To remove all such directories, use one of the following:

        xt -d t*.* rd $f
        xt -d t*.* rd $D

or, if your a 'real' geek,

        xt -d t*.* rd $P$D

Note that the point here is that $D *IS* sufficient.  When using
the -d option, $d is the relative name of the *directory*, which in
this case is the *whole* pathname of the matching entry, rather than
'just' the directory part.

Note also that the $n escape code is still important when using the
-d option.  Sometimes it is important to know just the last portion of
a directory name.  The value of the $r and $e escape codes is unclear
when using -d.  They will, however, represent the appropriate pieces
of the $n.
                              ══════════
                               WARNING!
                              ══════════
WARNING:  This represents a significant change from the corresponding
command under earlier versions of XT.  Most batch files containing XT
commands will need to be converted.
The -x Option
═════════════
The -x option allows you to specify a list of files to AVOID
matching.  For example, you wish to backup all files EXCEPT those
with .BAK, .TMP and .$$$ extensions to the floppy in drive A:.

        XT -xbak -xtmp -x$$$ *.* copy $f a:

It is possible to group these into a single option, separated by
commas (,):

        XT -xbak,tmp,$$$ *.* copy $f a:

When combined with the -d option, the arguments to a -x option
represent the WHOLE directory name to avoid matching.  As in our
example above:

        XT -d -xtemp -xbackup *.* copy $f\*.* a:
or
        XT -dxtemp,backup *.* copy $f\*.* a:

will copy all files from all directories under the current directory
to drive A: EXCEPT those files in directories whose last pathname
component is TEMP or BACKUP.


The -s Option
═════════════
XT normally allows you to specify multiple commands in a single
command template.  Commands are separated by semicolons (by default).
The following command displays all .TMP files, then deletes them.

        XT -! *.TMP type $f;del $f

Note the -! option is used since both commands are internal commands
to COMMAND.COM.

This feature may be disabled via the -s option.  If the -s option is
followed by a space, multiple command support is disabled. For
example:

        XT -s *.TMP xyzdebug -sddir1;dir2 prog

Some command interpreters already support multiple commands per line.
To maintain complete compatability with these, you can redefine the
command separator.  If the -s option is not followed by a space, the
character which follows it is assumed to be an alternate command
separator.  For example, if you wanted to use the tilde (~) character
rather than the semicolon (;), the following command is equivalent to
the first example above:

        XT -!s~ *.TMP type $f~del $f

Note that some characters are processed before XT sees the command
line.  Characters used by the DOS command interpreter cannot be used
as command separators (e.g. '<', '>', '|').
File Attribute Options
══════════════════════
If any of the following are specified, it is an explicit list of
the include set (the directory entries to match):
             +r  include read-only files
             +w  include read-write files
             +h  include hidden files
             +s  include system files

For example, "XT +r" lists all read-only files in and under the
current directory.
Recent Revisions
════════════════

Version 3.02:
------------
Fixed the problem with -r being ignored.

Version 3.01:
------------
Fixed ! command prefix.  Also fixed use of extended ascii characters
(those with high bit set, ascii 128-255).  Thought that I had all the
cases where trailing path separators was a problem solved by the
introduction of the uppercase escape codes (e.g. $D) but realized
that was true only if they were followed by another escape code,
spaces or end of line.  For fixed text, it was still a problem.  So I
added $? and $\ escape codes.  I doubt the upper case equivalents are
needed
codes.

Version 3.0:
-----------
Replaced program execution code to allow XT to check the programs'
return codes.  Coded to abort on a non-zero return code.  This allows
XT to abort more cleanly on a Ctrl-C/Ctrl-Break for programs and runtime
libraries returning a non-zero.  Added -f and -F options to override the
abort and force continuation regardless of the programs result status.
Added multiple command syntax and -s<separator-char> override option.
Split -q option into -q and -e for better control.  Responded to
complaints about the way $d worked under the -d option by changing
the escape codes' values.  Added the uppercase escape codes.  Added
the '!' command prefix, the -! option and changed the way this all
worked.

Version 2.4:
-----------
Added -x option for exclusion set.  The version was for Novell use
and internal use only and was not widely distributed.

Version 2.3:
-----------
Added -c option.  When specified, XT will change the current
directory and drive, if necessary, to the directory part of any
matches found.  For directories matched via -d, this includes the
whole directory ($f), not everything except the last component ($p$d).

XT will now always save the current directory on the current drive
(only) and will restore it on normal or CTRL-BREAK termination.

Version 2.2:
-----------
Added attribute patterns (+r +w +h +s).  Recommend +r and +w use
only, since +h and +s may not achieve desired results.  Try XT with
the -n option to verify expectations.

Options may be combined (e.g. +rh).


Version 2.1:
-----------
A lot of people have been pushing for improvements in my XTREE program,
so over the weekend I upgraded it to use my PATHS library...  This combined
with some other work results in several improvements:

    - You can now specify absolute or relative paths in front of the pattern.
    - The command template filter/escape sequences have been revised to
      allow the inclusion of the relative part of a matching path name ($d).
    - The program now aborts cleanly on a Ctrl-Break signal.
    - You can specify (-d) that the pattern should be used to match
      *directory* names.
    - The program is now recursive by default.

Due to the incompatable changes to both the escape filtering and the defaults,
combined with the fact that there is a commercial program named XTREE, I have
decided to rename the executable to XT.EXE.


More Examples:
══════════════

        XT ?   or   XT -?  or  XT -h

        Gives help, the command syntax and options.


        XT *.c

        Like WHEREIS.  Displays all .C files under the current directory.


        XT \*.c

        Like WHEREIS.  Displays all .C files anywhere on the current drive.


        XT -d C:\X*.*

        WHEREIS for directories.  Finds all directories on drive C: that
        start with an X.


        XT -d c:*.* md d:$d

        Copies the directory structure existing under the current directory
        on drive C: to the current directory on drive D:.  Note that $d is
        the *relative* directory name, needed in this case.


        XT c:*.c copy c:$f d:$d$n

        Recursively copies all .C files existing under the current directory
        on drive C: to the corresponding current directory on drive D:.  Note
        that $d is the *relative* directory name, and that the full path of
        the matching (source) file is $f.
License Agreement
═════════════════
Use of this program is ALMOST completely without restriction.  Stupid
little command-line utilities which aid the user in some small manner
should not be restricted since a better working enviroment  helps  us
all and may even lower the cost of more significant programs.

This program may NOT be sold or exchanged for any other consideration
without express written consent of the author.  Where bundled as part
of a larger collection of programs, this program may be  included  in
cases where it does not represent a significant portion (greater than
ten (10) percent) of the functionality of the product being sold.  It
may be included in sales of public domain software disks provided the
charge for such services does not exceed five dollars  ($5) U.S.  for
the disk containing this program.  (I  know  that's  less  than  some
folks charge, but come on guys,  twice  the  cost  of  the  disk  for
something somebody else gave you for free should be enough!)

Other than  this  single  restriction,  this  program  may  be  used,
distributed and/or included with other  products  provided  both  the
program and this document file are included  unchanged.   This  means
that you can use it at home or at  work,  company  software  and  LAN
administrators can distribute  to  it  to  fellow  employees  without
reservation and you can even provide it as  a  bonus  with  your  own
termination emulation, email or other fine product.

Due to the nature of this program, the author wishes to make it clear
that the use of this utility is subject to the discretion of the user
and that no implied warrantee exists.   The  author  will  accept  no
responsibility for its use.  There are no  intentionally  destructive
'features', however commands like "XT *.* del $f" could have  serious
impact on the user's blood pressure (not to mention the hard disk).

The author can be contacted at the following addresses:

                Paul Whittemore
                853 Grenoble Blvd.
                Pickering, Ontario
                Canada     L1W 1T7

CompuServe:     72007,3305
Internet:       [e-mail]
MHS:            pwhittem@novell