home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 6 / FreshFish_September1994.bin / bbs / util / mayflower.lha / MayFlower / ByteX / ByteX.doc < prev    next >
Encoding:
Text File  |  1994-05-05  |  13.2 KB  |  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.       lower case and then have the same device name in upper case. In a
  189.       case like this you would have to use the '-c' option in order to
  190.       change all case differences of the device name.
  191.       An imaginary example would be:
  192.  
  193.        1> ByteX -c Comm Comm1 -s ram: -s RAD:
  194.  
  195.       This changes all case conditions of the word ram (Ram, RAM, etc).
  196.  
  197. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  198. Furthermore:
  199.  
  200.    Another use for the "ByteX" program is to introduce ANSI escape code
  201.    sequences into text files that have been created with Ed, or created
  202.    by any text editor that can not imbed ANSI codes directly.
  203.  
  204.    If you would like to see what "ByteX" can do with a text file that is
  205.    filled with unactivated ANSI codes ("unactivated" meaning = the
  206.    required escape character is missing or waiting to be exchanged for
  207.    another character) then copy files "ansitest.txt" and "ByteX" to
  208.    your ram memory device and then type the following CLI commands
  209.    within a full size CLI window:
  210.  
  211.      > ByteX ansitest.txt -h 405b -h 1b5b
  212.      > type "ansitest.txt.BX"
  213.  
  214.    The "40" on the CLI line above is the hexadecimal number for the
  215.    '@' symbol and "5b" is hexadecimal number for the '[' symbol.
  216.    "1b" is hex for ESCAPE code.
  217.  
  218. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  219. Version History:
  220.  
  221.    The following information briefly describes changes or improvements
  222.    made to each version, and they will be described in descending order;
  223.    meaning latest version information begins first:
  224.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  225.    Version 5.0 (19940302) -
  226.    1) Changed version numbering format. Program can now be used with the
  227.       "Version" command. Date within parenthesis is shown in a somewhat
  228.       international format as (yyyymmdd).
  229.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  230.    Version 19930726 -
  231.    1) Optimized and refined source code thereby making program smaller.
  232.    2) Alas, removed a major programmer's error which occured when using
  233.       option -c, this error would cause improper operation when using
  234.       option -h (hex format -which is used when looking for non-printable
  235.       words). This would happen when attempting to exchange hex words
  236.       containing byte values above hex 7F (127 decimal).
  237.    3) Added "***  WARNING !!!  ***" paragraph to beginning of doc file.
  238.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  239.    Version 19920112 -
  240.    1) Removed a CLI parsing problem.
  241.    2) Removed problem which involved hex arguments.
  242.    3) Removed problem which involved pattern matching.
  243.    4) Can be made resident.
  244.    5) New option -o added for overwriting the input file with new data.
  245.    6) New options -1 and -2 added.
  246.    7) The [-options] argument can now be placed in 1st, 2nd or 3rd
  247.       argument position of the command line which will allow program
  248.       to be used with "s:spat" script file.
  249.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  250.    Version 19910830 -
  251.    1) Runs faster.
  252.    2) New option 'c' for (c)ase insensitive exchanges.
  253.    3) No limit to length of hex words, except the length CLI allows.
  254.    4) The input word formats can be mixed, one word may be in hex format
  255.       and the other word in string format.
  256.    5) Improved program error reporting.
  257.    6) Program (when run from CLI) will now interact with the 'c:Why'
  258.       command after program failures.
  259.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  260.    Version 19910701 - The first version.
  261.  
  262. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  263.       _   _   _   _   _   _   _   _   _   _   _   _   _   _   _   _
  264.      / \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \
  265.     /      <_>     <_>     <_>     <_>     <_>     <_>     <_>      \
  266.    /                                                                 \
  267.   /      21  Death and life are in the power of the tongue: and       \
  268.   \   they that love it shall eat the fruit thereof.                  /
  269.   /                                                                   \
  270.   \            The King James Holy Bible - Proverbs 18:21             /
  271.   /                                                                   \
  272.   \      35  A good man out of the good treasure of the heart         /
  273.   /   bringeth forth good things: and an evil man out of the evil     \
  274.   \   treasure bringeth forth evil things.                            /
  275.   /      36  But I say unto you, That every idle word that men shall  \
  276.   \   speak, they shall give account thereof in the day of judgment.  /
  277.   /      37  For by thy words thou shalt be justified, and by thy     \
  278.   \   words thou shalt be condemned.                                  /
  279.   /                                                                   \
  280.   \            The King James Holy Bible - Matthew 12:35-37           /
  281.    \        _       _       _       _       _       _       _        /
  282.     \   _  <_>  _  <_>  _  <_>  _  <_>  _  <_>  _  <_>  _  <_>  _   /
  283.      \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/
  284.  
  285. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  286.                             End Of Document
  287.  
  288.