home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / vrac / m218_ch1.zip / MERGE.DOC < prev    next >
Text File  |  1994-09-17  |  20KB  |  363 lines
  1.  
  2.  
  3.    MERGEFILE v1.18 & v2.18         MERGE.DOC                          9/17/94
  4.  
  5.  
  6.    NOTE:  Enter  COPY MERGE.DOC PRN  to  print  this file.   It is  formatted
  7.           to print 6 pages with approximately 60 lines per page.
  8.  
  9.  
  10.    Please see  PACKING.LST for a  complete list of  the files that  should be
  11.    included  with the  MergeFile package.   Refer to  README.DOC for  a brief
  12.    introduction to MergeFile and any late news.
  13.  
  14.                             DISCLAIMER OF WARRANTY
  15.  
  16.          THIS SOFTWARE  AND DOCUMENTATION ARE PROVIDED  "AS IS" WITHOUT
  17.          WARRANTY OF  ANY KIND, EITHER EXPRESSED  OR IMPLIED, INCLUDING
  18.          BUT NOT  LIMITED TO THE IMPLIED  WARRANTIES OF MERCHANTABILITY
  19.          AND FITNESS FOR  A PARTICULAR PURPOSE.  THE ENTIRE  RISK AS TO
  20.          THE RESULTS AND PERFORMANCE OF THIS SOFTWARE IS ASSUMED BY THE
  21.          USER.  IN NO EVENT WILL THE AUTHOR OF THIS SOFTWARE, OR ANYONE
  22.          ELSE  WHO HAS  BEEN INVOLVED  IN ITS  CREATION, PRODUCTION, OR
  23.          DELIVERY, BE LIABLE TO YOU OR  ANY OTHER PARTY FOR ANY DIRECT,
  24.          INDIRECT,  CONSEQUENTIAL, OR  INCIDENTAL DAMAGES  ARISING FROM
  25.          THE USE OF  OR INABILITY TO USE THIS  PRODUCT.  BECAUSE OF THE
  26.          VARIOUS  HARDWARE AND  SOFTWARE ENVIRONMENTS  INTO WHICH THESE
  27.          PROGRAMS  MAY  BE  PLACED,  THEY  SHOULD  ALWAYS BE THOROUGHLY
  28.          TESTED WITH NONCRITICAL DATA BEFORE RELYING ON THEM.  YOUR USE
  29.          OF THIS  SOFTWARE INDICATES THAT  YOU HAVE READ  AND AGREED TO
  30.          THESE AND ANY OTHER TERMS INCLUDED IN THIS PACKAGE OF FILES.
  31.  
  32.    After being  confronted by the disclaimer  above you're probably wondering
  33.    why you even thought about trying this  program, but if I thought it would
  34.    hurt  anything, I  wouldn't be  making it  available.  Unfortunately,  our
  35.    litigious society  has made disclaimers  like this necessary.   Please see
  36.    REGISTER.DOC for terms of distribution and registration.
  37.  
  38.    ACKNOWLEDGMENT
  39.    I  would like  to sincerely  thank Mr.  Bob Pauls,  sysop of  [Parameters]
  40.    Information Services BBS in Carbondale, IL for his patience and assistance
  41.    in helping me gather the data  needed to assemble this collection.  Please
  42.    see the end  of this document for information  on contacting [Parameters],
  43.    which will always have the latest version of MergeFile available.
  44.  
  45.  
  46.    Public Domain version 1.18  9/17/94
  47.  
  48.    There are plenty of routines around to  sort lists, but one night I needed
  49.    a program to merge two lists and  couldn't find any, so I wrote MERGEFILE.
  50.    There is nothing fancy about it, but  it does what it's supposed to do, at
  51.    least it has for me.  Everything that you need to know about how to use it
  52.    can be found on the "help" screen, which you get by entering MERGE without
  53.    any parameters.  It should merge sorted ASCII text files of any size (word
  54.    processor files that contain formatting characters  probably won't sort as
  55.    desired; lines need to be terminated  by a carriage return--a line feed is
  56.    optional, but normally follows the carriage return) since it does all it's
  57.    work on the disk (the minimum free disk space required for the destination
  58.    of the output file would be the combined size of the two input files).  If
  59.    you need to merge  more than two files, they can always be merged two at a
  60.    time.   I am releasing  this version, along  with its  source code, to the
  61.    Public Domain, so you are welcome to do anything with it you want.
  62.  
  63.  
  64.  
  65.    ShareWare version 2.18  9/17/94  (Copyright 1994 Hal Parks)
  66.  
  67.    Everything that  is true for  v1.18 is true  for v2.18, but  the shareware
  68.    version has many additional features.  The discussion that follows applies
  69.    to both versions,  except for items that are marked  with an asterisk (*),
  70.    which are only  available as shareware.  To make it  easier on me (I don't
  71.    have to change  a bunch of version numbers every  time I release something
  72.    new), "PD" stands for the public domain version and "SW" the shareware.
  73.  
  74.      Syntax:  MERGE  FileName1  [FileName2]  [FileName3]  [/C]  [/D]  [/K]
  75.                        * [/H]  * [/?]  * [?]  * [/E]  * [/O]  * [/F1../F9]
  76.  
  77.    FileName1 and FileName2 are the input files and must both be sorted lists.
  78.    The merged list is written to FileName3 if it is  entered (the input files
  79.    are unchanged), otherwise the last  file name serves as both an input file
  80.    and the output file and is overwritten (you are prompted for an overwrite;
  81.    MERGE writes a temporary file, erases the original file when the the merge
  82.    is finished, and then renames the temporary file).  MERGE defaults to case
  83.    sensitive in  ascending order ("H" appears  before "h"),  using the entire
  84.    input line  as the merge key,  and discarding any duplicates  in either or
  85.    both input files (if  each file has the same  key, the line from FileName1
  86.    will be merged).   Lines can be up to 254  characters long (255 for "PD").
  87.    If the files to merge are not in the current directory, enter the complete
  88.    path with the file name.  MERGE does not need to be  in the same directory
  89.    as the files if it is on the path or invoked by specifying its directory.
  90.  
  91.    "PD" has  no error detection capability.   If it encounters an  empty line
  92.    (carriage return/line feed  only) in one of the input  files, it will stop
  93.    processing that file,  but continue with the other file  until the end (or
  94.    another empty line).  It does not halt on a line of all blanks ("spaces").
  95.    "SW" will stop merging both files if  it finds an error in either file and
  96.    display an error message (see ERROR MESSAGES below).  Both versions retain
  97.    the merged file, but only with "SW" does  it end at the point of the first
  98.    error (and leave the input/output file intact if a third file name was not
  99.    specified), which makes it easier to locate a mistake in the input file.
  100.  
  101.    Options (enter without the quotes; they are not case sensitive, can
  102.             appear anywhere on the command  line, and the order is not
  103.             important except for the "F" option as explained below):
  104.  
  105.    "/C" = merge not case sensitive
  106.  
  107.    "/D" = merge  in  descending  order  (the  lists  must  also  be sorted in
  108.           descending order)
  109.  
  110.    "/K" = keep duplicates
  111.  
  112.  * "/E" = disable halt on error.   "SW" tries to detect 4 types  of errors in
  113.           the input files and exits with an error message and errorlevel (see
  114.           ERROR MESSAGES  below) if one is found:  blank  or  empty line  and
  115.           missing key  or field.  If /E is used, the merge continues  without
  116.           reporting errors and all records,  including those with errors, are
  117.           written to the merge file.  If  you are merging files that may have
  118.           a blank key field, e.g., lists of  names to merge on the fields for
  119.           "LAST FIRST MI"  where a middle initial is  not required, you would
  120.           probably want to use /E.  If an empty line happens to occur in both
  121.           input files at the same time, identical keys are being compared; if
  122.           you are not keeping duplicates, a  side effect of entering /E would
  123.           be that only one of the empty lines is written to the merge file.
  124.  
  125.  
  126.  
  127.  * "/O" = disable  overwrite warning on existing files.   This will cause the
  128.           merge  to be  performed without  pausing for  an overwrite  prompt,
  129.           which could be useful during batch processing.
  130.  
  131.  * "/H", "/?", "?" = all  will  access the  "help"  screen,  as will entering
  132.                      MERGE without any parameters
  133.  
  134.  * "/F1../F9[RJn]" = merge field priority
  135.  
  136.  * "/F?" can specify a different field to merge on, up to the first nine (one
  137.    or more "spaces" act as delimiters).  You can enter multiple fields to key
  138.    on, in  sequence of  priority, e.g., /F3 /F1 /F5  will merge  first on the
  139.    third field, then field one,  followed by field five (the lists  must also
  140.    be sorted in that order).  The fields are "free form" in that they are not
  141.    specified by column  numbers and a new field  begins each time a  space is
  142.    encountered (see Examples below).  This can cause a problem for some data,
  143.    e.g., numerical, that should not be left justified (all leading spaces are
  144.    removed).  If  needed, add "RJn" to the end of  the field number  to right
  145.    justify the data in a field with width "n", where "n" is from 1 to 80.
  146.  
  147.    If only one  filename is entered, it will be written back on itself, e.g.,
  148.    to remove duplicates from a sorted list.  All options available to  either
  149.    version can be used, but  using /K would be pointless, since you would get
  150.    the same  list.  You should  not enter the  same file name  more than once
  151.    ("SW" won't  allow it; with three  file names, if an  input and the output
  152.    file have the same name, "PD" will probably crash with a run time error).
  153.  
  154.  * If you enter two file names and the second does not exist,  then FileName1
  155.    will be processed like a single  file name and written to FileName2.  This
  156.    accomplishes the same thing as the  "merge" with one file described above,
  157.    except here  you retain the original.   This could also be  helpful if you
  158.    are batch processing  and one of the files may  or may not exist depending
  159.    on the outcome of some other activity.
  160.  
  161.    Examples
  162.  
  163.    The best method I can think of to explain MERGE's options is by using some
  164.    examples.  Let's assume  you have two files with 3  fields per record that
  165.    are sorted on all three fields (the first field is the primary key, second
  166.    field the  secondary key, etc.) in  ascending order and you  want to merge
  167.    them.  As you can see, I'm not very good at coming up with original names,
  168.    but the  reason I wrote  the first program  was to merge  two sets of file
  169.    names (maybe a better example would  have been to use people's names, like
  170.    LAST FIRST MI, but this by necessity is rather contrived):
  171.  
  172.                 FILE1                                 FILE2
  173.                 -----                                 -----
  174.    C:\BAT\0SIZE.BAT batchfile driveC      A:\WORK.FIL anotherfile driveA
  175.    C:\BAT\0sIZE.BAT batchfile driveC      C:\ANOTHER.FIL thisfile driveC
  176.    C:\BAT\0sIZE.BAT notsamefile driveC    D:\LASTFILE whatfile driveD
  177.  
  178.            if you enter:                             OUTFILE
  179.            -------------                             -------
  180.    MERGE file1 file2 outfile              A:\WORK.FIL anotherfile driveA
  181.                                           C:\ANOTHER.FIL thisfile driveC
  182.    the files are merged on the entire     C:\BAT\0SIZE.BAT batchfile driveC
  183.    line;  since  the  merge  is  case     C:\BAT\0sIZE.BAT batchfile driveC
  184.    sensitive,  there are no duplicate     C:\BAT\0sIZE.BAT notsamefile driveC
  185.    keys and every line is merged          D:\LASTFILE whatfile driveD
  186.  
  187.  
  188.  
  189.    MERGE file1 file2 outfile /c           A:\WORK.FIL anotherfile driveA
  190.                                           C:\ANOTHER.FIL thisfile driveC
  191.    this is the same as above,  except     C:\BAT\0SIZE.BAT batchfile driveC
  192.    the  merge is  not case sensitive;     C:\BAT\0sIZE.BAT notsamefile driveC
  193.    since the first two lines in file1     D:\LASTFILE whatfile driveD
  194.    now match, the second is discarded
  195.  
  196.  * MERGE file1 file2 outfile /f1          A:\WORK.FIL anotherfile driveA
  197.                                           C:\ANOTHER.FIL thisfile driveC
  198.    now the merge is only on the first     C:\BAT\0SIZE.BAT batchfile driveC
  199.    field and since the last two names     C:\BAT\0sIZE.BAT batchfile driveC
  200.    in file1 are  identical,  only the     D:\LASTFILE whatfile driveD
  201.    first of the two is kept
  202.  
  203.  * MERGE file1 file2 outfile /f1 /c       A:\WORK.FIL anotherfile driveA
  204.                                           C:\ANOTHER.FIL thisfile driveC
  205.    now all three keys in file1 are the    C:\BAT\0SIZE.BAT batchfile driveC
  206.    same, so the last two are discarded    D:\LASTFILE whatfile driveD
  207.  
  208.    Coincidentally (hah),  these files just  happen to be  sorted in ascending
  209.    order on all three fields regardless of the priority sequence, which means
  210.    I can use some more examples.
  211.  
  212.  * MERGE file1 file2 outfile /f3          A:\WORK.FIL anotherfile driveA
  213.                                           C:\BAT\0SIZE.BAT batchfile driveC
  214.    since four names are identical in      D:\LASTFILE whatfile driveD
  215.    the third  field,  only the first
  216.    in file1 will be retained  (file1
  217.    always has precedence over file2)
  218.  
  219.  * MERGE file1 file2 outfile /f3 /f1      A:\WORK.FIL anotherfile driveA
  220.  * MERGE file1 file2 outfile /f1 /f3      C:\ANOTHER.FIL thisfile driveC
  221.                                           C:\BAT\0SIZE.BAT batchfile driveC
  222.    for this  example,  both of these      C:\BAT\0sIZE.BAT batchfile driveC
  223.    will produce the same output           D:\LASTFILE whatfile driveD
  224.  
  225.  * MERGE file1 file2 outfile /f3 /f2      A:\WORK.FIL anotherfile driveA
  226.  * MERGE file1 file2 outfile /f2          C:\BAT\0SIZE.BAT batchfile driveC
  227.                                           C:\BAT\0sIZE.BAT notsamefile driveC
  228.    you've probably  got the idea by       C:\ANOTHER.FIL thisfile driveC
  229.    now, but I have one more example       D:\LASTFILE whatfile driveD
  230.    because it's easy
  231.  
  232.    MERGE file1 /c /f1                     C:\BAT\0SIZE.BAT batchfile driveC
  233.  
  234.    If the merge (in  this case, back on itself) is not  case sensitive and on
  235.    the first field, all names in file1  are the same, and only the first name
  236.    will remain.
  237.  
  238.    Incompatibilities
  239.  
  240.    Please  see  INCOMPAT.DOC  for  incompatibilities.   If  you think you are
  241.    having one,  or any other problem,  please contact  me through one  of the
  242.    addresses given at the end of this document.
  243.  
  244.  
  245.  
  246.    Error Messages
  247.  
  248.    Both versions have several error messages  and terminate with an exit code
  249.    (the numbers shown below correspond to the exit code for "SW"), but "PD"'s
  250.    only pertain  to starting errors.  "SW"  can also report on  errors during
  251.    the actual  merge and has  the "/O" option,  which overwrites an  existing
  252.    file without prompting.   This would most likely be used  in a batch file.
  253.    If you are  batch processing, you could use "if  errorlevel==" to test for
  254.    an error, and take action accordingly.
  255.  
  256.     1 : "INPUTFILE1" not found.
  257.     or  "INPUTFILE2" not found.
  258.     or  both.
  259.             The   same   error   number   applies   to   all  three
  260.             possibilities; the  screen display will  indicate which
  261.             file or files were not found.
  262.  
  263.  *  2 : Error with output file "OUTPUTFILE".
  264.             Either the  output file could not  be opened before the
  265.             merge (most  likely due to an  incorrect path) or there
  266.             is an unknown file error with it after the merge.
  267.  
  268.     3 : Cannot use fourth filename "ANYFILENAME".
  269.             You have more than three filenames on the command line.
  270.  
  271.     4 : Incorrect use of parameters.
  272.             Somehow  your  combination  of  options  and  filenames
  273.             caused an error, e.g., too many total.
  274.  
  275.  *  5 : Cannot use filename "ANYFILENAME" more than once.
  276.             You entered the same filename more than one time.
  277.  
  278.     6 : No filename specified.
  279.             You forgot to enter an input filename.
  280.  
  281.  *  7 : "/F?RJn" out of range; number must be from 1 to 80.
  282.             The right justification width "n" for the  field number
  283.             shown is out of range.
  284.  
  285.     8 : "/ " is not a valid option.
  286.             The  slash  and  character  combination  which  will be
  287.             displayed is not a MERGE option.
  288.  
  289.  *  9 : "/F?" is an invalid or duplicate merge key.
  290.             You have two  or more  identical "F"  options,  entered
  291.             more than nine  fields, or the character  following the
  292.             "F" did not  translate to a numeric  value from 1 to 9.
  293.  
  294.  * 10 : Terminated by user.
  295.             You  ended   the  program   by  responding  "N"  to  an
  296.             "overwrite" warning.
  297.  
  298.  * 11 : Input file "INPUTFILE?" is empty.
  299.             The input file exists, so it was "found,"  but its size
  300.             is zero.
  301.  
  302.  
  303.  
  304.  * 12 : Blank or empty line in input file "INPUTFILE?".
  305.         Check file "OUTPUTFILE" for point of merge error.
  306.             All the error messages above  have something to do with
  307.             starting MERGE (except 2 which can also occur after the
  308.             merge is done); the rest  check on the file(s) during a
  309.             merge.  This  error is displayed when  one of the input
  310.             files has a  line of only spaces or  a completely empty
  311.             line (CR/LF only).  To help you locate the error, MERGE
  312.             reports which input file caused the problem and retains
  313.             the output file so you can  see at what point the error
  314.             occurred during the merge (if  the error is at the very
  315.             beginning of one of the input files and the size of the
  316.             output file is zero, MERGE will not retain the file and
  317.             display a message that the file was deleted).
  318.  
  319.  * 13 : Missing merge key in input file "INPUTFILE?".
  320.         Check file "OUTPUTFILE" for point of merge error.
  321.             MERGE can  usually detect a  missing primary merge  key
  322.             field (the  position where it should  be is spaces) but
  323.             not all (detecting missing keys after the first is even
  324.             more difficult).   Because the number  of delimiters is
  325.             not fixed  (you can have  any amount of  spaces between
  326.             fields) there are some combinations of empty fields and
  327.             primary merge keys, and any subsequent merge keys, that
  328.             will not be discovered.
  329.  
  330.  * 14 : Blank or missing field in input file "INPUTFILE?".
  331.         Check file "OUTPUTFILE" for point of merge error.
  332.             This can occur  if a merge key is  not the first field,
  333.             but the first field is  all spaces.  It could also mean
  334.             that because a field or  fields are missing, MERGE went
  335.             past  the end  of the  input line  trying to locate the
  336.             merge key field.
  337.  
  338.    "PD" is free for the taking, but if you find the shareware version more to
  339.    your liking, I  think $10 is a fair contribution.   That 10 bucks will get
  340.    you  a  disk  with  the  latest  shareware  version (less the unregistered
  341.    reminder), its source code, some  utility programs, a technical assistance
  342.    phone  number, and  notification of  anything else  exciting (in a "merge"
  343.    program? well, updates,  bug fixes, new products, etc.)  that comes along.
  344.    Please see REGISTER.DOC and README.DOC for more information.
  345.  
  346.    [Parameters]  can be  reached by  calling 618-549-8448.   Mail can also be
  347.    sent to any of the addresses shown below.
  348.  
  349.    Write to:  Hal Parks            E-Mail:  RIME          ->774 or PARAMETERS
  350.               HAL SoftWare                  FIDO          1:11/153
  351.               404B W. Oak                        Internet
  352.               Carbondale, IL 62901          hal.parks@f153.n11.z1.fidonet.org
  353.  
  354.    Happy Merging!
  355.  
  356.  
  357.    P.S.  You don't have to be "registered" to get in touch.   And if you find
  358.          anything wrong or have any suggestions on how to improve the program
  359.          or a feature you'd like to see, I'd be glad to hear from you.
  360.  
  361.          Live long and prosper.
  362.  
  363.