home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 12 / CD_ASCQ_12_0294.iso / vrac / chang401.zip / CHANGE.DOC < prev    next >
Text File  |  1994-01-08  |  15KB  |  307 lines
  1. CHANGE.DOC
  2. 01/08/94
  3.  
  4. The CHANGE.EXE program allows you to make changes in binary or text files of any
  5. size.  Features:
  6.  
  7.   * Can handle files of any size provided you have enough room on your disk
  8.     to hold a copy of resulting file
  9.   * Can be used to change text files or binary files
  10.   * Can be used to remove trailing spaces from a file
  11.   * Can specify different lengths for the input strings and the output strings
  12.   * Can specify that the changes only be done in lines that include a certain
  13.     character string.  This selection string can be case-insensitive
  14.   * Can handle up to 25 change requests at a time
  15.   * Can specify the input/output strings as ASCII characters, hexadecimal
  16.     values, or as decimal values
  17.   * Handles the changes fairly quickly
  18.   * Can either replace the original file with the resulting file or else
  19.     create a new changed file (using /Noutfile specification)
  20.   * Changes can be verified before they are made
  21.   * Changes can be entered in any of the following ways:
  22.       - from the command line (one TO/FROM pair allowed)
  23.       - interactively (one TO/FROM pair allowed)
  24.       - from a controlfile (up to 25 TO/FROM pairs allowed)
  25.   * Boolean operators can be used if the TO/FROM pair is specified from the
  26.     command line (e.g. CHANGE TEST.TXT /FROM One /TO Many /IN Apples OR Oranges
  27.  
  28.  
  29. Program written by:
  30.                         Bruce Guthrie
  31.                         Room H-4885
  32.                         U.S. Dept of Commerce/ESA/OBA/BSISD
  33.                         Washington, D.C. 20230
  34.  
  35.                         (202) 482-3234
  36.  
  37. You may freely copy and re-distribute this program; however, the U.S.
  38. Department of Commerce neither guarantees nor assures compatibility of the
  39. program with all computer software or hardware.
  40.  
  41. Foreign users:  Please provide an Internet address in all correspondence or
  42. and just e-mail your problems to me at bgu@cu.nih.gov
  43.  
  44.  
  45. Syntax:
  46.  
  47.     CHANGE infile [ ctlfile | /FROM string /TO string [ /IN search ] ]
  48.       [ /LINES { line1-line2 | line1 linect } ... ] [ /V | /-V ] [ /I | /-I ]
  49.       [ /Noutfile [ /OVERWRITE | /-OVERWRITE | /OVERASK ] ]
  50.       [ /Fflag_file ] [ /Ttemp_file ] [ /TRIM | /-TRIM ]
  51.       [ /BINARY | /TEXT ] [ /VERIFY | /-VERIFY ] [ /Q ] [ /? | /?&H ]
  52.  
  53. where:
  54.  
  55. "infile" can include a drive and path designation.  It is the file name you
  56. want changed.  Unless you specify a /Noutfile parameter, the infile will be
  57. overwritten by this program.
  58.  
  59.  
  60. "ctlfile" contains the change commands to make.  If a ctlfile is not provided
  61. and a FROM/TO option is not specified, the routine will prompt you for one FROM
  62. (what's the text you want to change from; case is significant unless /CASE is
  63. specified), TO (what's the text you want to change to; case is always
  64. significant), and IN (what string the line must be contain before the change is
  65. applied; case is always significant unless /CASE is specified) request.  If a
  66. ctlfile is used, you can specify up to 25 change requests at a time.  Each line
  67. of the change file should consist of records of one of four record types:
  68.  
  69.   * blank lines or those beginning with semi-colons are treated as comments.
  70.   * lines beginning with "-F" or "-f" provide FROM options.
  71.   * lines beginning with "-T" or "-t" provide TO options.
  72.   * lines beginning with "-I" or "-i" provide IN options.  These are optional;
  73.     if not provided, all lines will be searched for the FROM string.  Any
  74.     IN request forces /TEXT mode to be invoked
  75.  
  76. If more than one set of FROM/TO/IN records is provided, the -F specification
  77. must precede the others.  Each option is local to a given FROM/TO/IN
  78. specification.  For example:
  79.  
  80.         ; Sample file
  81.         -FPRINT
  82.         -TPrinting
  83.         -I"
  84.         -fUSING
  85.         -tused
  86.  
  87. contains two FROM/TO/IN specifications.  "PRINT" will be changed to "Printing"
  88. in any line with a double quote.  "USING" will be changed to "used" in all
  89. lines; no -I option is applied for the second FROM/TO/IN specification.
  90.  
  91. The FROM/TO/IN specifications can include any text characters.  They can also
  92. contain ASCII codes, created either using the Alt key in combination with the
  93. numeric keypad (e.g.  Alt-228 to get a Sigma character) or else by imbedding a
  94. hexadecimal code (in the form &Hxx) or a decimal code (in the form \nnn) in the
  95. text.  You can get a table of hexadecimal codes at the end of this documentation
  96. or by saying "CHANGE /?&H".  For example, to change a double carriage
  97. return/line feed to a single carriage return/line feed, you could say:
  98.  
  99.         -F&H0D0A0D0A
  100.         -T&H0D0A
  101.  
  102. (Note that the above example would require you to use the /BINARY option as well
  103. since it extends beyond line boundaries.)
  104.  
  105. If you need to follow a hexadecimal specification with normal text characters,
  106. follow the hex spec with one space (which CHANGE will ignore).  For example,
  107.  
  108.         -F&H0c Hi!
  109.         -T&H0d0a Bye!
  110.  
  111.  
  112. "/FROM string /TO string [ /IN search ]" allows you to specify the from/to
  113. parameters on the control line.  Quotation marks are required around the strings
  114. if they include spaces or special characters.  Note that certain characters
  115. cannot be passed in because DOS considers them special characters and steals
  116. them first.  This includes ">" and "|" characters.  You'll have to use the
  117. control file or the interactive mode in this case or else use the &Hxx or \nnn
  118. conventions.  "search" is further described below.
  119.  
  120. "/LINES line1-line2" says to restrict the search to lines between line numbers
  121. line1 and line2 inclusive.  You can have multiple line requests in any order
  122. such as "/LINES 1-10 90-100 30-50".  The routine skips all lines after the
  123. largest line number is encountered.  Defaults to "/LINES 1-9999999".
  124.  
  125. "/LINES line1 linect" says to restrict the search to lines beginning with line1
  126. and continuing for a total of linect lines.  So "/LINES 10 20" is actually the
  127. same as "/LINES 10-29".
  128.  
  129. "/V" says to find those items that do NOT match the specification.
  130.  
  131. "/-V" is the opposite of /V and is typically the default; CONFIGWS-able.
  132.  
  133. "/I" says to make it a case-insensitive search.
  134.  
  135. "/-I" is the opposite of /I and is typically the default; CONFIGWS-able.
  136.  
  137. "/Noutfile" is the name of the new file to create.  If a /Noutfile is not
  138. specified, the source document (infile) will be replaced by the changed file.
  139.  
  140. "/OVERWRITE" says to write over the outfile (if requested) if it exists
  141. already.
  142.  
  143. "/-OVERWRITE" says to abort if the outfile exists already.
  144.  
  145. "/OVERASK" says to ask if the outfile exists already.  This is the default.
  146.  
  147. "/Fflag_file" is the name of a file to contain all changed lines.  This allows
  148. you to see what the lines were changed to for verification purposes.  This
  149. option automatically invokes /TEXT.
  150.  
  151. "/Ttemp_file" is the name of the temporary file to create.  The actual changes
  152. are written to a temp file and then the source file is replaced with the temp
  153. file is everything works and there were actually changes to be found in the
  154. source document.  By default, the temp file is written to the same path as the
  155. input file.  The temporary file will be as big as the final file is.  If you
  156. don't have enough room for it to be on your source disk, specify another
  157. temporary file name with a different path (e.g. "/TG:\TEMP.TXT").
  158.  
  159. "/TRIM" says to remove trailing spaces from the end of each line.  Automatically
  160. forces you into TEXT mode.
  161.  
  162. "/-TRIM" is the opposite of /TRIM and is the default.
  163.  
  164.  
  165. "/TEXT" puts you into TEXT mode.  TEXT mode means that all data in the file are
  166. read in and processed as separate text records.  Alternatively, the file can be
  167. processed in BINARY mode in which case the file is read in in 8,000-byte blocks.
  168. BINARY mode is quicker and is required for EXE and COM files.  TEXT mode
  169. presents some information like the number of lines in your file and is
  170. *required* if you specify any of the following options:
  171.  
  172.         * an IN (or -I) request
  173.         * /LINES
  174.         * /Fflag_file
  175.         * /TRIM
  176.         * /VERIFY
  177.  
  178. "/BINARY" is the opposite of TEXT mode.  It's faster than TEXT and is the
  179. default for CHANGE.  It is overridden if you specify certain options listed
  180. above.
  181.  
  182. "/VERIFY" says to prompt you before changing any lines.  You are asked to
  183. confirm that you in fact want to make each change requested.  Automatically
  184. forces you into TEXT mode.
  185.  
  186. "/-VERIFY" is the opposite of /VERIFY and is the default.
  187.  
  188. "/Q" turns off the line-by-line status messages.
  189.  
  190. "/?" or "/HELP" or "HELP gives you syntactical help.
  191.  
  192. "/?&H" gives you a hexadecimal and decimal conversion table.
  193.  
  194.  
  195.  
  196. For search, the syntax is:
  197.   [ ( ]... search_item [ boolean [ ( ]... search_item [ ) ]...] [ ) ]...
  198. where:
  199.   ( and )     are used to group items
  200.   search_item is shown below
  201.   boolean     is AND, OR, or XOR (NOT is included with search_item)
  202.  
  203. for search_item, the syntax is:
  204.   [ NOT ]  "string" [ column ]
  205. where:
  206.   NOT         is obvious
  207.   string      the string to search; the quotation marks are typically not
  208.               required unless the string contains a space or a reserved word
  209.   column      is the column in which the string must be found.
  210.  
  211. So, let's cover some examples:
  212.  
  213.         CHANGE TEST.TXT /FROM Apple /TO Banana /IN "Bugs Bunny" OR "Elmer Fudd"
  214.  
  215. Changes the string "Apple" to "Banana" in any lines that have either the text
  216. "Bugs Bunny" or "Elmer Fudd" in them.
  217.  
  218.         CHANGE TEST2.TXT /FROM Bugs /TO Bunny /IN (Apples or Oranges) AND NOT
  219.            Pears /LINES=1-1000 /COLS=1/5
  220.  
  221. Changes "Bugs" to "Bunny" in the first thousand lines of TEST2.TXT.  The line
  222. itself must contain the words "Apples" or "Oranges" in them and any lines are
  223. ignored that contain "Pears".  Note that the quotes around the search words are
  224. not required unless the words include spaces or unless they could be confused
  225. with some other keywords.  "CHANGE TEST3.TXT /FROM Bugs /TO Bunny /IN OR OR AND"
  226. might cause the program to get confused since "OR" and "AND", which you want to
  227. look for as also keywords.
  228.  
  229.         CHANGE /I TEST.TXT /FROM One /TO Many /IN "Bugs Bunny" AND Martians
  230.  
  231. This changes "One" to "Many" is any lines that contain both "Bugs Bunny" and
  232. "Martians".  The search is case-insensitive so lines with either "BUGS BUNNY"
  233. and "Bugs Bunny" will be changed.
  234.  
  235. NOTE:  THIS EXTENDED SEARCHING CAPABILITY IS SUPPORTED ONLY FOR /IN REQUESTS
  236. MADE FROM THE COMMAND LINE.  IT IS NOT SUPPORTED IN EITHER THE CTLFILE OR IN THE
  237. INTERACTIVE TO/FROM SELECTION MODE.
  238.  
  239.  
  240. Return codes:
  241.  
  242. CHANGE returns the following ERRORLEVEL codes:
  243.         0 = no problems, changes made
  244.         1 = no problems, nothing found to change
  245.       253 = routine aborted early
  246.       254 = internal problems
  247.       255 = syntax problems, file not found, or /? requested
  248.  
  249.  
  250. Decimal and hexadecimal codes:
  251.   e.g. "\066\097\116" and "&H426174" both are "Bat"
  252. +--------------------------------------------------------------------------+
  253. | dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr |
  254. +--------------+--------------+--------------+--------------+--------------+
  255. | \000 &H00 nul| \052 &H34 4  | \104 &H68 h  | \156 &H9C £  | \208 &HD0 ╨  |
  256. | \001 &H01   | \053 &H35 5  | \105 &H69 i  | \157 &H9D ¥  | \209 &HD1 ╤  |
  257. | \002 &H02   | \054 &H36 6  | \106 &H6A j  | \158 &H9E ₧  | \210 &HD2 ╥  |
  258. | \003 &H03   | \055 &H37 7  | \107 &H6B k  | \159 &H9F ƒ  | \211 &HD3 ╙  |
  259. | \004 &H04   | \056 &H38 8  | \108 &H6C l  | \160 &HA0 á  | \212 &HD4 ╘  |
  260. | \005 &H05   | \057 &H39 9  | \109 &H6D m  | \161 &HA1 í  | \213 &HD5 ╒  |
  261. | \006 &H06   | \058 &H3A :  | \110 &H6E n  | \162 &HA2 ó  | \214 &HD6 ╓  |
  262. | \007 &H07 bel| \059 &H3B ;  | \111 &H6F o  | \163 &HA3 ú  | \215 &HD7 ╫  |
  263. | \008 &H08 bs | \060 &H3C <  | \112 &H70 p  | \164 &HA4 ñ  | \216 &HD8 ╪  |
  264. | \009 &H09 tab| \061 &H3D =  | \113 &H71 q  | \165 &HA5 Ñ  | \217 &HD9 ┘  |
  265. | \010 &H0A lf | \062 &H3E >  | \114 &H72 r  | \166 &HA6 ª  | \218 &HDA ┌  |
  266. | \011 &H0B vt | \063 &H3F ?  | \115 &H73 s  | \167 &HA7 º  | \219 &HDB █  |
  267. | \012 &H0C pg | \064 &H40 @  | \116 &H74 t  | \168 &HA8 ¿  | \220 &HDC ▄  |
  268. | \013 &H0D cr | \065 &H41 A  | \117 &H75 u  | \169 &HA9 ⌐  | \221 &HDD ▌  |
  269. | \014 &H0E   | \066 &H42 B  | \118 &H76 v  | \170 &HAA ¬  | \222 &HDE ▐  |
  270. | \015 &H0F   | \067 &H43 C  | \119 &H77 w  | \171 &HAB ½  | \223 &HDF ▀  |
  271. | \016 &H10   | \068 &H44 D  | \120 &H78 x  | \172 &HAC ¼  | \224 &HE0 α  |
  272. | \017 &H11   | \069 &H45 E  | \121 &H79 y  | \173 &HAD ¡  | \225 &HE1 ß  |
  273. | \018 &H12   | \070 &H46 F  | \122 &H7A z  | \174 &HAE «  | \226 &HE2 Γ  |
  274. | \019 &H13   | \071 &H47 G  | \123 &H7B {  | \175 &HAF »  | \227 &HE3 π  |
  275. | \020 &H14   | \072 &H48 H  | \124 &H7C |  | \176 &HB0 ░  | \228 &HE4 Σ  |
  276. | \021 &H15   | \073 &H49 I  | \125 &H7D }  | \177 &HB1 ▒  | \229 &HE5 σ  |
  277. | \022 &H16   | \074 &H4A J  | \126 &H7E ~  | \178 &HB2 ▓  | \230 &HE6 µ  |
  278. | \023 &H17   | \075 &H4B K  | \127 &H7F   | \179 &HB3 │  | \231 &HE7 τ  |
  279. | \024 &H18   | \076 &H4C L  | \128 &H80 Ç  | \180 &HB4 ┤  | \232 &HE8 Φ  |
  280. | \025 &H19   | \077 &H4D M  | \129 &H81 ü  | \181 &HB5 ╡  | \233 &HE9 Θ  |
  281. | \026 &H1A eof| \078 &H4E N  | \130 &H82 é  | \182 &HB6 ╢  | \234 &HEA Ω  |
  282. | \027 &H1B esc| \079 &H4F O  | \131 &H83 â  | \183 &HB7 ╖  | \235 &HEB δ  |
  283. | \028 &H1C   | \080 &H50 P  | \132 &H84 ä  | \184 &HB8 ╕  | \236 &HEC ∞  |
  284. | \029 &H1D ???| \081 &H51 Q  | \133 &H85 à  | \185 &HB9 ╣  | \237 &HED φ  |
  285. | \030 &H1E ???| \082 &H52 R  | \134 &H86 å  | \186 &HBA ║  | \238 &HEE ε  |
  286. | \031 &H1F ???| \083 &H53 S  | \135 &H87 ç  | \187 &HBB ╗  | \239 &HEF ∩  |
  287. | \032 &H20    | \084 &H54 T  | \136 &H88 ê  | \188 &HBC ╝  | \240 &HF0 ≡  |
  288. | \033 &H21 !  | \085 &H55 U  | \137 &H89 ë  | \189 &HBD ╜  | \241 &HF1 ±  |
  289. | \034 &H22 "  | \086 &H56 V  | \138 &H8A è  | \190 &HBE ╛  | \242 &HF2 ≥  |
  290. | \035 &H23 #  | \087 &H57 W  | \139 &H8B ï  | \191 &HBF ┐  | \243 &HF3 ≤  |
  291. | \036 &H24 $  | \088 &H58 X  | \140 &H8C î  | \192 &HC0 └  | \244 &HF4 ⌠  |
  292. | \037 &H25 %  | \089 &H59 Y  | \141 &H8D ì  | \193 &HC1 ┴  | \245 &HF5 ⌡  |
  293. | \038 &H26 &  | \090 &H5A Z  | \142 &H8E Ä  | \194 &HC2 ┬  | \246 &HF6 ÷  |
  294. | \039 &H27 '  | \091 &H5B [  | \143 &H8F Å  | \195 &HC3 ├  | \247 &HF7 ≈  |
  295. | \040 &H28 (  | \092 &H5C \  | \144 &H90 É  | \196 &HC4 ─  | \248 &HF8 °  |
  296. | \041 &H29 )  | \093 &H5D ]  | \145 &H91 æ  | \197 &HC5 ┼  | \249 &HF9 ∙  |
  297. | \042 &H2A *  | \094 &H5E ^  | \146 &H92 Æ  | \198 &HC6 ╞  | \250 &HFA ·  |
  298. | \043 &H2B +  | \095 &H5F _  | \147 &H93 ô  | \199 &HC7 ╟  | \251 &HFB √  |
  299. | \044 &H2C ,  | \096 &H60 `  | \148 &H94 ö  | \200 &HC8 ╚  | \252 &HFC ⁿ  |
  300. | \045 &H2D -  | \097 &H61 a  | \149 &H95 ò  | \201 &HC9 ╔  | \253 &HFD ²  |
  301. | \046 &H2E .  | \098 &H62 b  | \150 &H96 û  | \202 &HCA ╩  | \254 &HFE ■  |
  302. | \047 &H2F /  | \099 &H63 c  | \151 &H97 ù  | \203 &HCB ╦  | \255 &HFF    |
  303. | \048 &H30 0  | \100 &H64 d  | \152 &H98 ÿ  | \204 &HCC ╠  |              |
  304. | \049 &H31 1  | \101 &H65 e  | \153 &H99 Ö  | \205 &HCD ═  |              |
  305. | \050 &H32 2  | \102 &H66 f  | \154 &H9A Ü  | \206 &HCE ╬  |              |
  306. +--------------+--------------+--------------+--------------+--------------+
  307.