CHANGE.TXT 1 Mar 10, 2001 WinXX NOTICE: As with most DOS-based utilities, this program doesn't understand the weird subdirectories, long filenames, invalid characters that are possible under Windows. This is not a bug. It's just the way DOS applications work. For compatibility reasons, most versions of Windows maintain a short filename for each file (in WinNT, you can probably say "DIR /X" in DOS to find them). The short filenames are the ones with "~" characters in them (like "MYFILE~1.TXT"). The short filenames are what these utilities will process. 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 Mar 10, 2001 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. (NOTE: The use of control files does not support column specifications.) 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 Mar 10, 2001 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 Mar 10, 2001 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 Mar 10, 2001 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 ] [ /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 Mar 10, 2001 "/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 Mar 10, 2001 "/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 Mar 10, 2001 "/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. "/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 Mar 10, 2001 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 Mar 10, 2001 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. The ZIP file that contained this program and its associated documentation files is named with a two-digit year followed by a two-digit month. So CHAN0001.ZIP came out in January 2000. Comments and suggestions can be sent to the following. Realistically, I will not be revising this DOS-based program much in the future but it doesn't hurt to suggest things anyway. Please provide an Internet e-mail address on all correspondence.