home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 9 / FreshFishVol9-CD2.bin / bbs / util / mayflower.lha / MayFlower / ByteX / ByteX.doc < prev    next >
Text File  |  1994-05-04  |  13KB  |  288 lines
  1.  
  2.                          ByteX 5.0 (19940302)
  3.  
  4.                        by  Stephen D. Childers
  5.  
  6. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  7.   --\ /--      ***  WARNING !!!  ***         ***  WARNING !!!  ***
  8.   (o) (o)
  9.      ^      This program, if not used properly, can damage files. [ouch]
  10.   \_____/
  11.  
  12. Do not use this program on original files unless you know exactly what
  13. you are doing.
  14.  
  15. This is the warning that should have been given with the first version of
  16. this program.
  17.  
  18. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  19. Program Description:
  20.  
  21.    1) Program is used to alter TEXT or BINARY files.
  22.  
  23.       This program will take an input file and exchange an old word
  24.       pattern for a new word pattern. All old word patterns in the file
  25.       will be exchanged with the new word pattern. The format for the
  26.       old word pattern and new word pattern may be as strings or
  27.       hexadecimals.
  28.  
  29.    2) Program will print out the total number of exchanges made.
  30.  
  31.    3) Runs only from CLI. Can be made resident.
  32.  
  33.    4) The [-options] argument can be placed in the 1st, 2nd or 3rd
  34.       argument position of the command line; placing the [-options] in
  35.       the 2nd argument position will allow this program to be used with
  36.       the S:SPAT script file, thus allowing the use of wild characters.
  37.  
  38.       The following examples are for proper SPAT operation:
  39.  
  40.       ie > Execute SPAT Bytex *.c -o -s "DF0:" -s "RAM:"
  41.       or > Execute SPAT Bytex in:here/#?.c out:there/ -c -s "DF0:" -s "RAM:"
  42.  
  43.       The following SPAT example will not work as expected:
  44.  
  45.       no > Execute SPAT Bytex -o #?.c -s "DF0:" -s "RAM:"
  46.  
  47.       IMPORTANT NOTE:
  48.       The SPAT script file must be modified to receive 7 opts before it
  49.       can accept the ByteX command line.
  50.  
  51.    5) Program (when run from CLI) will now interact with the 'c:Why'
  52.       command after program failures; this command may provide a more
  53.       detailed explanation of why the program failed.
  54.  
  55.       The 'Why' command should be used immediately after a program
  56.       failure to extract the last program's result code, because
  57.       that result code is changed upon the execution of the next CLI
  58.       command.
  59.  
  60.    6) Certain error reports will contain the name of the argument, file,
  61.       device, (etc) that is associated with failure when it occurs.
  62.  
  63. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  64. CLI usage:
  65.  
  66.    1 > ByteX [!|?] [[-options] input [output] -opt1 word1 -opt2 word2]
  67.  
  68.     options c = Case insensitive exchange
  69.             o = Overwrite input file
  70.             1 = Algorithm 1 (use maximum memory)
  71.             2 = Algorithm 2 (use minimum memory)
  72.             q = Quiet; do not print messages
  73.             ! = Show author info
  74.  
  75.     input  = The input file; source
  76.     output = The output file; destination
  77.  
  78.     opt1 or opt2;  'h' = word is in HEX format.
  79.                    's' = word is in STRING format.
  80.  
  81.     word1 = the old word to replace.
  82.     word2 = the new word that will replace word1.
  83.    _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
  84.  
  85.    1) The formats for words (word1 & word2) can be mixed. One word
  86.       may be in the HEX format and the other in the STRING format.
  87.  
  88.    2) Lengths allowed for argument word1 and word2 are restricted by the
  89.       maximum limits imposed by the CLI.
  90.  
  91.    3) When altering TEXT files it does not matter if the length of word1
  92.       is not equal to the length of word2, but program will run slower.
  93.  
  94.    4) Certain restrictions must be observed when altering BINARY program
  95.       files. When altering binary program files you must insure that the
  96.       old word (word1) and the new word (word2) are the same lengths or
  97.       else the altered program file will most likely fail to run.
  98.  
  99.    5) Option 'c' is for (c)ase insensitive exchanges. Under this
  100.       option the case condition of the new word will be exchanged with
  101.       the old word regardless of the case condition of the old word.
  102.  
  103.    6) If the [out] (output file) arg is not given (and option -o is not
  104.       selected) then the input file name will be used in creating the
  105.       output file name, and that name will have the extension ".BX"
  106.       appended to it.
  107.  
  108.    7) Option -o does not require the output file argument, and program
  109.       will ignore [out] arg if given.
  110.  
  111.    8) Option -o requires algorithm #1 and will load all of the input
  112.       file into memory, and if there is not enough memory the program
  113.       will inform you to try again without option -o, thereby allowing
  114.       algorithm #2 to be used.
  115.  
  116.    9) Option -o will not overwrite inputfile unless the number of
  117.       word pattern exchanges is greater than zero.
  118.  
  119.   10) Options -1 & -2 allows user to choose the Read/Write algorithm that
  120.       is needed for your system configuration.
  121.  
  122.       ByteX has 2 algorithms, and will automatically choose the algorithm
  123.       that your system will allow, or you can force the algorithm of your
  124.       choice. The algorithms are for Read/Write operations and are:
  125.  
  126.       -1 Algorithm #1 is the fast mode and attempts to put all of the
  127.          input file into system memory when it is available, thus
  128.          allowing faster Read/Write operations when working with files
  129.          on any device (ie DF0:), thereby reducing drive clatter and
  130.          gronking (alias: wear and tear) on drives.
  131.  
  132.       -2 Algorithm #2 is the slow mode and uses a small amount of system
  133.          memory (regardless of inputfile size), this will cause drive
  134.          gronking and clatter, unless the input file and output file are
  135.          on different drives.
  136.  
  137.       To avoid the posibility of drive clatter when working on files
  138.       greater than 10000 bytes then use option -1 which will force ByteX
  139.       to fail if it is unable to get the memory needed for fast mode.
  140.  
  141. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  142. CLI Examples:
  143.  
  144.    1> ByteX anytext newtext -h 0a -h 0a0d
  145.  
  146.       This example will take the inputfile 'anytext' and exchange all
  147.       occurances of the hex value '0a' for the new hex value of '0a0d'.
  148.       0a = Line Feed (LF), 0d = Carriage Return (CR).
  149.  
  150.       NOTE: This comes in handy when capturing text files from different
  151.       computer BBS services that use different line ending formats. You
  152.       can now exchange the CR/LF control character combinations to
  153.       whatever CR/LF combination suits your particular need.
  154.  
  155.    ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
  156.    2> ByteX -c dpaint -s df1:     -s RAD:    ; exchange string with string
  157.       ByteX -c dpaint -h 6466313a -s RAD:     ; exchange hex with string
  158.       ByteX -c dpaint -s df1:     -h 52414d3a  ; exchange string with hex
  159.       ByteX -c dpaint -h 6466313a -h 52414d3a   ; exchange hex with hex
  160.  
  161.       All of the lines given in this example will accomplish the same
  162.       thing; 'df1:' will be replaced with 'RAD:'.
  163.  
  164.       This example will take file 'dpaint' (Deluxe Paint V2.0) and take
  165.       all the occurances of the string 'df1:' and exchange them with the
  166.       'ram:' string, and the default output file will named dpaint.BX
  167.  
  168.       NOTE: The reason I altered the dpaint (v2.0) program was because it
  169.       would keep me from getting the file input window IF the df1: disk
  170.       drive was empty. It may be a nice safety feature but I got tired of
  171.       having to insert a diskette into df1: just so I could gain access to
  172.       the file input window. I do art work in memory first and then save
  173.       it to disk (unless the power goes out <smile>).
  174.  
  175.    ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
  176.    3> ByteX Comm Comm1 -s RAM: -s RAD:
  177.  
  178.       This example will replace the string 'RAM:' with 'RAD:' and
  179.       the output file will be named as 'Comm1'.
  180.       'Comm' is a public domain communications program.
  181.  
  182.       NOTE: The reason I altered this program was because it would bring
  183.       up a little window saying 'wrong diskette' if it could not find the
  184.       'RAM:' device available. I would rather use RAD.
  185.  
  186.       Please notice the case differences between this example and example
  187.       #2; it is possible for a single program to have a device name in
  188.