CHANGE.TXT                           1                         Aug 26, 1999

WIN95 AND WINNT NOTICE:  As with most  DOS-based  utilities,  this  program
doesn't  understand  the  weird  subdirectories,  long  filenames,  invalid
characters that  are  possible  under  Windows  95  and  Windows/NT.   Both
operating systems alias long filenames into names like MYFILE~1.TXT and you
will need to specify the aliased versions of file names to process them. If
you're not sure what the pseudo-name is, use the "DIR /X" command in DOS to
check.  Under some file structure systems in NT, the program may  not  work
at all.

The CHANGE.EXE program allows you to make changes in binary or  text  files
of any size.  Features:

  * Can handle files of any size provided you have enough room on your disk
    to hold a copy of resulting file.
  * Can be used to change text files or binary files.
  * Can be used to remove trailing spaces from a file.
  * Can specify different lengths for the  input  strings  and  the  output
    strings.
  * Can specify that the changes only be  done  in  lines  that  include  a
    certain   character   string.    This   selection   string    can    be
    case-insensitive.
  * Can handle up to 30 change requests at a time.
  * Allows you to recurse through child subdirectories.
  * For text input files, handles DOS text (all lines end with CR/LF),  Mac
    text (all lines end with CR), or Unix text  (all  lines  end  with  LF)
    files.
  * Can specify the input/output strings as ASCII  characters,  hexadecimal
    values, or as decimal values.
  * Handles the changes quickly.
  * Can either replace the original file with the resulting  file  or  else
    create a new changed file (using /Noutfile specification).
  * Changes can be interactively verified before they are made.
  * Changes can be entered in any of the following ways:
       - from the command line (one TO/FROM pair allowed)
       - interactively (one TO/FROM pair allowed)
       - from a controlfile (up to 30 TO/FROM pairs allowed)
  * Boolean operators can be used if the TO/FROM pair is specified from the
    command line; for example:
       CHANGE TEST.TXT /FROM One /TO Many /IN Apples OR Oranges
  * The input file specification can include standard DOS wildcards  or  an
    external  file  (@listfile)  containing  the  files  to  be   processed
    (although either prohibits using the /Noutfile feature).
  * The input change specification can end  with  "*"  in  which  case  all
    subsequent characters are changed to the end of the line.  For example:
       CHANGE       TEST.TXT       /FROM       DEVICE=C:\BIN\AD*        /TO
       DEVICE=C:\BINNEW\ADNEW.COM
  * The input change specification can include a  column  specification  so
    only characters that fall within a given range of columns are changed.
  * You can exclude files from processing based on file attributes.
  * Can be used to eliminate lines that you don't want.  For example:
       CHANGE TEST.TXT /FROM DEVICE=C:\DOS\SMARTDRV.EXE /TO NULL /ZAPNULL
  * Pressing escape stops the program early.



CHANGE.TXT                           2                         Aug 26, 1999

Specifying parameters:

Parameters for this program can be set in the  following  ways.   The  last
setting encountered always wins:
  - Read from an *.INI file (see BRUCEINI.TXT file),
  - Through the use of an environmental variable (SET CHANGE=whatever), or
  - From the command line (see "Syntax" below)


To/From/In Specifications:

The CHANGE program allows you to specify three parts to a change request:

  * The text to be replaced
  * The text to replace it with
  * Optionally, a string which the line must contain before the change is
    made

For example, in the following two lines:

        The quick brown fox jumped over
        the lazy brown dog.

the program allows you to replace the string "brown" with the string  "red"
only in lines that contain the string "fox" (so "brown  fox"  becomes  "red
fox").  This would change the "brown" in the first line but not the one  in
the second line.

In order to enter your change request(s), you can use one of three methods:

  *  Enter it from the command line using /FROM  string,  /TO  string,  /IN
     string
  *  Let the program prompt you for the /FROM, /TO, and /IN specifications
  *  Use a control file

The control file is a regular  ASCII  text  file  (created  with  any  text
editor).  It can contain up to 30 change requests (the other two approaches
only allow for one).  Each line of  the  control  file  should  consist  of
records of one of four record types:

  *  blank lines or those beginning with  semi-colons,  colons,  or  single
     quotes are treated as comments.
  *  lines  beginning  with  "-F"  or  "-f"  provide  FROM  options.   FROM
     specifications must precede TO specifications.
  *  lines  beginning  with  "-T"  or  "-t"   provide   TO   options.    TO
     specifications must precede IN specifications (if any are used).
  *  lines beginning with "-I" or  "-i"  provide  IN  options.   These  are
     optional; if not provided, all lines will be  searched  for  the  FROM
     string.  Any IN request forces /TEXT mode to be invoked.


CHANGE.TXT                           3                         Aug 26, 1999

If  more  than  one  set  of  FROM/TO/IN  records  is  provided,   the   -F
specification must precede the others.  Each option is  local  to  a  given
FROM/TO/IN specification.  For example:

        ; Sample control file
        -FPRINT
        -TPrinting
        -I"
        -fUSING
        -tused

contains  two  FROM/TO/IN  specifications.   "PRINT"  will  be  changed  to
"Printing" in any line with a double quote.  "USING"  will  be  changed  to
"used" in all lines; no -I option is  applied  for  the  second  FROM/TO/IN
specification.

If you want to specify your from/to request from the command line  and  any
of your strings contains one or more spaces, enclose the string  in  double
quotation marks.  For example:

        CHANGE BUGBUNNY.TXT /FROM "Elmer Fudd" /TO "Daffy Duck"

The FROM/TO/IN specifications can include any text  characters.   They  can
also contain ASCII codes, created either using the Alt key  in  combination
with the numeric keypad (for example, Alt-228 to get a Sigma character)  or
else by embedding a hexadecimal code (in the form &Hxx) or a  decimal  code
(in the form  \nnn)  in  the  text.   These  codes  are  described  in  the
BRUCEHEX.TXT file. (Do not use &Hxx from the  command  line  under  Windows
NT.) For example, to change a double carriage return/line feed to a  single
carriage return/line feed, you could say:

        -F&H0D0A0D0A
        -T&H0D0A

(Note that  the  above  example  would  require  you  to  use  the  /BINARY
option--the default-- since the lines encountered will extend  beyond  line
boundaries.)

WARNING:  Do not use &H codes from the command line if you're using Windows
NT.  That operating system pre-processes the hexadecimal codes before  they
reach the program.  You can use &H codes in control files but not from  the
command line.  The decimal codes in the form \nnn work fine under NT.

If you  need  to  follow  a  hexadecimal  specification  with  normal  text
characters, follow the hex spec with one space (which CHANGE will  ignore).
For example,

        -F&H0c Hi!
        -T&H0d0a Bye!

DOS considers certain characters ("|" and ">") to be  pipe  characters  and
will strip them away from the command line before CHANGE gets them.  If you
need to specify a change that includes these characters and you want to use
the command line for it, use the  hexadecimal  or  decimal  codes  instead.
Alternatively, putting them in quotes seems to usually work.


CHANGE.TXT                           4                         Aug 26, 1999

If the "/FROM string" specification ends with  an  asterisk  (for  example,
"/FROM BRUCE*"), the program will look  for  any  instance  of  the  string
before the asterisk and replace that string and all  subsequent  characters
in the line with the designated "/TO string".   Asterisks  embedded  within
the string (as opposed to being the trailing character of the string)  will
be read as regular characters.  If you actually want to replace an asterisk
as a trailing character, use the &Hxx or \nnn  conventions.   (Do  not  use
&Hxx under Windows NT.) Specifying a wildcard like this puts you into /TEXT
mode  automatically.   Wildcards  cannot  be  used  in  the  "/TO   string"
specification.

The "/FROM string" parameter can  include  a  column  indicator  after  the
string (and the asterisk if used).  A single column  can  be  specified  in
which case the string to be changed has to start at that specific column:

        CHANGE TEMP.X /FROM ";" 1 /TO NULL /NTEMP.X2
        CHANGE TEMP2.X /FROM "Apple" 5 /TO "Banana" /NTEMP2.X2

Alternatively, the column specification can include a range of columns. The
"from" specification has to start within that range (although  it  can  end
outside of that range).  For example:

        CHANGE TEMP.X /FROM "\" 3/50 /TO "/" /NTEMP.X2

To remove a string entirely, use the -T without anything after  it  or  use
"-TNULL" or "/TO NULL" from the command line.  If the /ZAPNULL parameter is
provided, if the entire line is reset to nothing,  the  line  will  not  be
written out at all.  This allows you to drop lines if necessary.

As far as case-sensitivity is concerned, the /FROM and  /IN  specifications
are case-sensitive unless  /I  is  specified.   The  /TO  specification  is
*always* case-sensitive.



CHANGE.TXT                           5                         Aug 26, 1999

Syntax:

    CHANGE { filespec | (filelist) | @listfile } [ /ATTR=attribs ] [ /S ]
      [ /-PROMPT ] [ /Cctlfile | /FROM string /TO string [ /IN search ] ]
      [ /LINES { line1-line2 | line1 linect } ... ] [ /V ] [ /I ]
      [ /Noutfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ] ]
      [ /Frptfile ] [ /Ttempfile ] [ /TRIM ] [ /ZAPNULL ]
      [ /TEXT | /BINARY ] [ /VERIFY ] [ /Q | /Qn ] [ /W | /W0 | /-W ]
      [ /MONO ] [ /Iinitfile | /INULL ] [ /-ENV ] [ /? ] [ /?HEX ]

where:

"filespec" tells the routine which file or files are to be  processed.   It
can include path information if desired.  It can also include standard  DOS
wildcards as long as the  /Noutfile  parameter  is  not  specified.   If  a
/Noutfile parameter is not provided, the input files are overwritten by the
results of this program.  If you'd like to process a lot of files and still
create new files, use the DOS FOR  command  instead.   Try  something  like
this:

        FOR %A IN (*.TXT) DO CHANGE %A /FROM "A" /TO "B" /N\TEMP\%A

"(filelist)" allows you to specify multiple files to be processed from  the
command line.  File names should be separated by spaces.  They may  include
drive, path, and wildcard information.  Remember that a command line in DOS
cannot exceed 127 characters so you're limited as  to  how  many  different
file specifications you can provide in this fashion.

"@listfile" allows you to have a variety of file specifications saved in  a
text file named "listfile".  Each line in the file should  consist  of  one
file specification, each of which can  include  a  path  and  wildcards  if
desired.  Blank lines and lines  beginning  with  semi-colons,  colons,  or
quotes are ignored.

"/ATTR=attribs" allows you to specify a combination of attributes that  you
want considered.  You can specify  any  combination  of  R  (read-only),  H
(hidden), S (system), or A (archive bit).  Precede  any  character(s)  with
"-" to exclude instead of include.  Unlike with the DOS  DIR  command,  the
inclusions and exclusions are subject to  "OR"  conditions;  /ATTR=HS  will
retrieve any file that is either hidden or a system file or both.  You  can
specify "/ATTR=ALL"  to  specify  that  all  files  are  to  be  processed.
Initially defaults to /ATTR=-H-S-R (exclude  any  files  that  are  hidden,
system, or read-only).

"/S" processes files in subdirectories off the specified subdirectory. This
is a powerful option but it also allows you to  do  dumb  things  that  you
really shouldn't do (like change every "A" on your hard disk to "a") so  be
careful with it.  Initially defaults to "/-S".

"/-PROMPT" suppresses  the  normal  "Cascading  subdirectory  parameter  /S
specified.  Okay?" prompt  is  cascading  ("/S"  parameter)  is  specified.
Initially defaults to "/PROMPT".


CHANGE.TXT                           6                         Aug 26, 1999

"/Cctlfile" specifies a control file with the change commands to make.  See
"To/From/In Specifications" above.

"/FROM string /TO string [ /IN search ]" allows you to specify the  from/to
parameters on the control line.  See "To/From/In Specifications" above. The
"/IN search" parameter invokes text mode and is not recommended for  binary
files.

"/LINES line1-line2" says to restrict the  search  to  lines  between  line
numbers line1 and line2 inclusive.  You can have multiple line requests  in
any order such as "/LINES 1-10 90-100 30-50".  The routine skips all  lines
after the largest line  number  is  encountered.   The  "/LINES"  parameter
invokes text mode and is not recommended for  binary  files.   Defaults  to
"/LINES 1-9999999".

"/LINES line1 linect" says to restrict the search to lines  beginning  with
line1 and continuing for a total of linect lines.  So  "/LINES  10  20"  is
actually the same as "/LINES 10-29".  The "/LINES" parameter  invokes  text
mode and is not recommended for binary files.

"/V" says to find those items that do NOT match the specification.

"/-V" is the opposite of /V and is typically the default.

"/I" says to make it a case-insensitive search.

"/-I" is the opposite of /I and is typically the default.

"/Noutfile" is the name of the new file to create.  If a /Noutfile  is  not
specified, the source document (infile) will be  replaced  by  the  changed
file.

"/OVERWRITE" says to write over the outfile (if  requested)  if  it  exists
already.

"/-OVERWRITE" says to abort if the outfile exists already.

"/OVERASK" says to ask if the outfile exists already.  This is the default.

"/Frptfile" is the name of a file  to  contain  all  changed  lines.   This
allows you to see what the lines were changed to for verification purposes.
This option automatically invokes text mode  and  is  not  recommended  for
binary files.  The report file is always  appended  to  so  new  lines  are
written at the end of any existing report file.

"/Ttempfile" is the name of the  temporary  file  to  create.   The  actual
changes are written to a temp file and then the  source  file  is  replaced
with the temp file is everything works and there were actually  changes  to
be found in the source document.  By  default,  the  temp  file  is  called
{CHANGE}.TMP and it is written to the same path as  the  input  file.   The
temporary file will be as big as the final file  is.   If  you  don't  have
enough room for it to be on your source  disk,  specify  another  temporary
file name with a different path (for example, "/TG:\TEMP.TXT").


CHANGE.TXT                           7                         Aug 26, 1999

"/TRIM" says  to  remove  trailing  spaces  from  the  end  of  each  line.
Automatically forces you into TEXT mode.

"/-TRIM" is the opposite of /TRIM and is the default.

"/ZAPNULL" says that if the output line is changed and ends up empty,  then
the line should be dropped entirely from the output file.  Requires you  to
be in TEXT mode.

"/-ZAPNULL" retains all lines.  This is initially the default.

"/TEXT" puts you into TEXT mode.  TEXT mode means that all data in the file
are read in and processed as separate  text  records.   Alternatively,  the
file can be processed in BINARY mode in which case the file is read  in  in
large blocks.  BINARY mode is quicker and is required for binary files like
EXE and COM files.  TEXT mode may or may not work if you use it on a binary
file.  TEXT mode is *required* if you specify any of the following options:

        * an /IN (or -I) request
        * /LINES
        * /Frptfile
        * /TRIM
        * /VERIFY

Under /TEXT mode, the program will read DOS text (lines  end  with  CR/LF),
Mac text (lines end with CR), or Unix  text  (lines  end  with  LF)  files.
However, under /TEXT mode, all lines will be written out as DOS text (lines
end with CR/LF).

"/BINARY" is the opposite of TEXT mode.  It's faster than TEXT and  is  the
default for CHANGE.  It is overridden if you specify certain options listed
above.

"/VERIFY" says to prompt you before changing any lines.  You are  asked  to
confirm that you in fact want to make  each  change  requested.   "/VERIFY"
invokes text mode and is not recommended for binary files.

"/-VERIFY" is the opposite of /VERIFY and is the default.

"/Q" turns off the record-by-record status report.   (In  /TEXT  mode,  the
status records appear every  25  records.   In  /BINARY  mode,  the  status
records appear every 6000 bytes.)

"/Qn" shows a status message every n-number of records.  This only  effects
/TEXT processing, not binary processing.  The default is "/Q10".


CHANGE.TXT                           8                         Aug 26, 1999

"/W" says to pause with a "Press any key to  continue"  message  after  the
program finishes if any hits were found.   This  parameter  is  ignored  if
redirection out is being used.

"/W0" says to pause afterward whether any hits were found or not.  This  is
initially the default if the program is run under Windows3.1 or  Windows95.
CHANGE won't detect if you're running under  Windows  NT  though;  you  can
manually specify this parameter if the window closes up on you  before  you
can read the results.  This parameter is  ignored  if  redirection  out  is
being used.

"/-W" says to not pause afterward at all.  This is initially the default if
the program is run under DOS or Windows NT.

"/MONO" (or "/-COLOR") does not try to override screen  colors.   Initially
defaults to "/COLOR".

"/COLOR" (or "/-MONO") allows screen colors  to  be  overridden.   This  is
initially the default.

"/Iinitfile" says to  read  an  initialization  file  with  the  file  name
"initfile".  The file specification *must* contain a period.  Initfiles are
described in the BRUCEINI.TXT file.  Initially defaults to "/ICHANGE.INI".

"/INULL" says to skip loading the initialization file.

"/ENV" says to look for %var% occurrences in the command line  and  try  to
resolve any apparent environmental variable references.   See  BRUCEINI.TXT
for more information.  This is initially the default.

"/-ENV" says to skip resolving apparent %var% occurrences  in  the  command
line.  Initially defaults to "/ENV".

"/?" or "/HELP" or "HELP" shows you the syntax for the command.

"/?HEX" gives you a hexadecimal and decimal conversion table.



CHANGE.TXT                           9                         Aug 26, 1999

For search, the syntax is:

  [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...

where:

  ( and )     are used to group items
  search_item is shown below
  boolean     is AND, OR, or XOR (NOT is included with search_item)

for search_item, the syntax is:

  [ NOT ]  "string" [ column ]

where:
  NOT         is obvious
  string      the string to search; the quotation marks are typically not
              required unless the string contains a space or a reserved
              word or begins with a slash ("/")
  column      is the column in which the string must be found.

So, let's cover some examples:

         CHANGE TEST.TXT /FROM Apple /TO Banana /IN "Bugs Bunny" OR
           "Elmer Fudd"

Quotes are needed around a string if it begins with a slash:

        CHANGE TEST.TXT /FROM "/1997" /TO "/1998" /IN "Revised"

The above changes the string "Apple" to "Banana" in  any  lines  that  have
either the text "Bugs Bunny" or "Elmer Fudd" in them.

        CHANGE TEST2.TXT /FROM Bugs /TO Bunny /IN (Apples or Oranges) AND
           NOT Pears /LINES 1-1000

The above changes  "Bugs"  to  "Bunny"  in  the  first  thousand  lines  of
TEST2.TXT.  The line itself must contain the words "Apples" or "Oranges" in
them and any lines are ignored that contain "Pears".  Note that the  quotes
around the search words are not required unless the words include spaces or
unless they could be confused with some other keywords.  "CHANGE  TEST3.TXT
/FROM Bugs /TO Bunny /IN OR OR AND" might cause the program to get confused
since "OR" and "AND", which you want to look for, are also keywords.

        CHANGE /I TEST.TXT /FROM One /TO Many /IN "Bugs Bunny" AND Martians

The above changes "One" to "Many" is any  lines  that  contain  both  "Bugs
Bunny" and "Martians".  The search is case-insensitive so lines with either
"BUGS BUNNY" and "Bugs Bunny" will be changed.

NOTE:  THIS  EXTENDED  SEARCHING  CAPABILITY  IS  SUPPORTED  ONLY  FOR  /IN
REQUESTS MADE FROM THE COMMAND LINE.  IT IS NOT  SUPPORTED  IN  EITHER  THE
CTLFILE OR IN THE INTERACTIVE TO/FROM SELECTION MODE.



CHANGE.TXT                           10                        Aug 26, 1999

Return codes:

CHANGE returns the following ERRORLEVEL codes:

        0 = no problems, changes made
        1 = no problems, nothing found to change
      253 = routine aborted early
      254 = internal problems
      255 = syntax problems, file not found, or /? requested


Author:

                        Bruce Guthrie
                        Room H-4885
                        U.S. Dept of Commerce/ESA/STAT-USA
                        Washington, DC 20230

                        voice: (202) 482-3234
                        e-mail: bruce.guthrie@mail.doc.gov

You may freely copy and  re-distribute  this  program;  however,  the  U.S.
Department of Commerce neither guarantees nor assures compatibility of  the
program with all computer software or hardware.

Additional information about this and other Bruce Guthrie programs  can  be
found in the file BRUCE.TXT which should be included in  the  original  ZIP
file.  The recent change  history  for  this  and  the  other  programs  is
provided in the HISTORY.ymm file which should be in the same ZIP file where
"y" is replaced by the last digit of the year and "mm"  is  the  two  digit
month of the release; HISTORY.611 came out in  November  1996.   This  same
naming convention is used in naming the ZIP file (CHANGymm.ZIP)  that  this
program was included in.

Please provide an Internet e-mail address on all correspondence.


