home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 6 / FreshFish_September1994.bin / bbs / util / mayflower.lha / MayFlower / Sift / Sift.doc < prev    next >
Encoding:
Text File  |  1994-06-10  |  7.6 KB  |  176 lines
  1.                                                    --- ---
  2.                           Sift 5.0 19940312        (o) (o)
  3.                                                       ^
  4.                          by Stephen D Childers     \_____/
  5.  
  6. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  7.            ***  WARNING !!!  ***         ***  WARNING !!!  ***
  8.  
  9.    This program can damage [ouch] important files if not used properly.
  10.    Do not use this program on original files unless you know exactly
  11.    what you are doing.
  12.  
  13.    This is the warning that should have been given with previous
  14.    releases of this program.
  15.  
  16. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  17. Program Description:
  18.  
  19.    1) This program will sift out user defined byte values from a file.
  20.  
  21.       The range of byte values that may be sifted out of a file
  22.       is the normal values that a byte may represent ( 0 through
  23.       255 decimal ).
  24.  
  25.    2) Can run only from CLI. Can be made resident.
  26.  
  27.    3) Program (when run from CLI) will interact with the 'c:Why' command
  28.       after program failures; this command may provide a more detailed
  29.       explanation of why the program failed.
  30.  
  31.       The 'Why' command should be used immediately after a program
  32.       failure to extract the last program's result code, because
  33.       that result code is changed upon the execution of the next CLI
  34.       command.
  35.  
  36.    4) Certain error reports will contain the name of the argument, file,
  37.       device, (etc) that is associated with failure when it occurs.
  38.  
  39. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  40. CLI Usage:
  41.  
  42.   Usage > Sift [!] [[-options] input [output] filter]
  43.  
  44.       ! = show author info
  45.  
  46.       options:  q = Quiet; do not print messages
  47.                 o = Overwrite input, [output] not needed
  48.  
  49.       input   = file to be sifted
  50.       output  = file to receive sifted data
  51.       filter  = This is a text file which informs Sift which byte
  52.                 values to sift while reading the inputfile.
  53.  
  54. CLI Usage notes:
  55.  
  56.    1) Input arg must be a file and can not be a device or directory, and
  57.       output arg can now designate a device and/or directory as the
  58.       destination for sifted data. If output arg is not a file then
  59.       input file name will be taken and used for the output file name.
  60.  
  61.          ie > Sift noisycapture.txt  df0:        filter2.txt
  62.          or > Sift noisycapture.txt  df0:stuff/  filter2.txt
  63.  
  64.    2) If the output arg is not given (and option -o is not selected) then
  65.       the input arg (file name) will be used in creating the output file
  66.       name, and that name will have the extension ".SFT" appended to it.
  67.       Output will be put in the same directory as the input file.
  68.  
  69.    3) If the output arg is a device or directory name then the output of
  70.       the sifted input file is sent to the given directory.
  71.  
  72.    4) Option -o does not require the output file arg, and program will
  73.       ignore output arg if option -o is given.
  74.  
  75.    5) Option -o requires loading all of the input file into memory, and
  76.       if there is not enough memory the program will inform you to try
  77.       again without option -o.
  78.  
  79.    6) Option -o will not overwrite input file unless the bytes sifted is
  80.       greater than zero.
  81.  
  82.    7) The <-options> arg can appear any where within the command line
  83.       template, thereby allowing this program to be used with various
  84.       "S:SPAT" like script files, thus allowing the use of wild
  85.       characters.
  86.  
  87.          ie > Execute SPAT Sift  *.txt  -o  filter1.txt
  88.          or > Execute SPAT Sift #?.txt  -o  filter1.txt
  89.          or > Execute SPAT Sift #?.txt  df1:  filter1.txt
  90.          or > Execute SPAT Sift #?.txt  df1:texts/  filter1.txt
  91.  
  92. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93. How to create a filterfile:
  94.  
  95.    1) First line of filterfile must have the word "Sift.filter" on it
  96.       or Sift complains.
  97.  
  98.    2) This text file can be created and modified by the user using any
  99.       editor program. The values that you put into this file will tell
  100.       Sift which character codes to ignore when reading your inputfile
  101.       and making your outputfile.
  102.  
  103.    3) The filter text file may contain user notes, and any notes that
  104.       you write within your own filter files must be preceded with
  105.       semi-colons ";" or else the Sift program may not filter properly
  106.       after reading your filter file into memory.
  107.  
  108.    4) The filter text file character values may be writen as hex or
  109.       decimal. Hex values must have an 'h' attached to the front of it.
  110.  
  111.    5) One character or a range of characters may be indicated.
  112.  
  113.    6) Putting a dash between values indicates a range of characters to
  114.       sift.
  115.  
  116.    7) A comma must be inserted between each character or between each
  117.       range of characters, and the values at the end of any line do not
  118.       need anything after them.
  119.  
  120.    8) See the files "filter.txt" and "filter.ed" for examples of how to
  121.       write your own filter files.
  122.  
  123. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  124. Version History:
  125.  
  126.    The following information briefly describes changes or improvements
  127.    made to each version, and they will be described in descending order;
  128.    meaning latest version information begins first:
  129.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  130.    Version 5.0 (19940312) -
  131.    1) Changed version numbering format. Program can now be used with the
  132.       "Version" command. Date within parenthesis is shown in a somewhat
  133.       international format as (yyyymmdd).
  134.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  135.    Version 19930803 -
  136.    1) Optimized and refined source code thereby making program smaller.
  137.    2) Added "***  WARNING !!!  ***" paragraph to document file.
  138.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  139.    Version 19920108 -
  140.    1) Removed a CLI parsing problem.
  141.    2) Can be made resident.
  142.    3) Added option -o.
  143.    4) The <-options> arg can now appear any where within the command
  144.       line template, thereby allowing this program to be used with
  145.       various "S:SPAT" like script files, thus allowing the use of wild
  146.       characters.
  147.    5) Input arg must be a file, and output arg can now designate a path.
  148.       and/or directory as the destination for sifted data.
  149.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  150.    Version 19910917 -
  151.    1) This version should be a wee bit faster than previous version.
  152.    2) Usage template has changed.
  153.    3) First line of filterfile must have the word "Sift.filter" on it
  154.       or Sift complains.
  155.    4) Improved error reports.
  156.    5) Program (when run from CLI) will now interact with the 'c:Why'
  157.       command after program failures.
  158.    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  159.    Version 19910712 - The first version.
  160.  
  161. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  162.       /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
  163.      /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
  164.     /\/                                                          \/\
  165.    /\/     6  Better is the poor that walketh in his uprightness, \/\
  166.    \/\  than he that is perverse in his ways, though he be rich.  /\/
  167.    /\/                                                            \/\
  168.    \/\              The King James Holy Bible - Proverbs 28:6     /\/
  169.     \/\                                                          /\/
  170.      \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
  171.       \/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/
  172.  
  173. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  174.                            End Of Document
  175.  
  176.