home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 15 / CD_ASCQ_15_070894.iso / vrac / merge217.zip / MERGE.DOC < prev    next >
Text File  |  1994-05-29  |  19KB  |  355 lines
  1.  
  2.  
  3.    MERGEFILE v1.17 & v2.17         MERGE.DOC                          5/29/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.17  5/29/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.17  5/29/94  (Copyright 1994 Hal Parks)
  66.  
  67.    Everything that  is true for  v1.17 is true  for v2.17, 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 to /F9" = 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).
  141.  
  142.    If only one filename is entered, it  will be written back on itself, e.g.,
  143.    to remove duplicates from a sorted  list.  All options available to either
  144.    version can be used, but using /K  would be pointless, since you would get
  145.    the same  list.  You should  not enter the  same file name  more than once
  146.    ("SW" won't  allow it; with three  file names, if an  input and the output
  147.    file have the same name, "PD" will probably crash with a run time error).
  148.  
  149.  * If you enter two file names and the second does not exist,  then FileName1
  150.    will be processed like a single  file name and written to FileName2.  This
  151.    accomplishes the same thing as the  "merge" with one file described above,
  152.    except here  you retain the original.   This could also be  helpful if you
  153.    are batch processing  and one of the files may  or may not exist depending
  154.    on the outcome of some other activity.
  155.  
  156.    Examples
  157.  
  158.    The best  way I can  think of  explaining  MERGE's options is  to use some
  159.    examples.  Let's assume  you have two files with 3  fields per record that
  160.    are sorted  on all three  fields (first field  is the primary  key, second
  161.    field the  secondary key, etc.) in  ascending order and you  want to merge
  162.    them.  As you can see, I'm not very good at coming up with original names,
  163.    but the  reason I wrote  the first program  was to merge  two sets of file
  164.    names (maybe a better example would  have been to use people's names, like
  165.    LAST FIRST MI, but this by necessity is rather contrived):
  166.  
  167.                 FILE1                                 FILE2
  168.                 -----                                 -----
  169.    C:\BAT\0SIZE.BAT batchfile driveC      A:\WORK.FIL anotherfile driveA
  170.    C:\BAT\0sIZE.BAT batchfile driveC      C:\ANOTHER.FIL thisfile driveC
  171.    C:\BAT\0sIZE.BAT notsamefile driveC    D:\LASTFILE whatfile driveD
  172.  
  173.            if you enter:                             OUTFILE
  174.            -------------                             -------
  175.    MERGE file1 file2 outfile              A:\WORK.FIL anotherfile driveA
  176.                                           C:\ANOTHER.FIL thisfile driveC
  177.    the files are merged on the entire     C:\BAT\0SIZE.BAT batchfile driveC
  178.    line;  since  the  merge  is  case     C:\BAT\0sIZE.BAT batchfile driveC
  179.    sensitive,  there are no duplicate     C:\BAT\0sIZE.BAT notsamefile driveC
  180.    keys and every line is merged          D:\LASTFILE whatfile driveD
  181.  
  182.  
  183.  
  184.    MERGE file1 file2 outfile /c           A:\WORK.FIL anotherfile driveA
  185.                                           C:\ANOTHER.FIL thisfile driveC
  186.    this is the same as above,  except     C:\BAT\0SIZE.BAT batchfile driveC
  187.    the  merge is  not case sensitive;     C:\BAT\0sIZE.BAT notsamefile driveC
  188.    since the first two lines in file1     D:\LASTFILE whatfile driveD
  189.    now match, the second is discarded
  190.  
  191.  * MERGE file1 file2 outfile /f1          A:\WORK.FIL anotherfile driveA
  192.                                           C:\ANOTHER.FIL thisfile driveC
  193.    now the merge is only on the first     C:\BAT\0SIZE.BAT batchfile driveC
  194.    field and since the last two names     C:\BAT\0sIZE.BAT batchfile driveC
  195.    in file1 are  identical,  only the     D:\LASTFILE whatfile driveD
  196.    first of the two is kept
  197.  
  198.  * MERGE file1 file2 outfile /f1 /c       A:\WORK.FIL anotherfile driveA
  199.                                           C:\ANOTHER.FIL thisfile driveC
  200.    now all three keys in file1 are the    C:\BAT\0SIZE.BAT batchfile driveC
  201.    same, so the last two are discarded    D:\LASTFILE whatfile driveD
  202.  
  203.    Coincidentally (hah),  these files just  happen to be  sorted in ascending
  204.    order on all three fields regardless of the priority sequence, which means
  205.    I can use some more examples.
  206.  
  207.  * MERGE file1 file2 outfile /f3          A:\WORK.FIL anotherfile driveA
  208.                                           C:\BAT\0SIZE.BAT batchfile driveC
  209.    since four names are identical in      D:\LASTFILE whatfile driveD
  210.    the third  field,  only the first
  211.    in file1 will be retained  (file1
  212.    always has precedence over file2)
  213.  
  214.  * MERGE file1 file2 outfile /f3 /f1      A:\WORK.FIL anotherfile driveA
  215.  * MERGE file1 file2 outfile /f1 /f3      C:\ANOTHER.FIL thisfile driveC
  216.                                           C:\BAT\0SIZE.BAT batchfile driveC
  217.    for this  example,  both of these      C:\BAT\0sIZE.BAT batchfile driveC
  218.    will produce the same output           D:\LASTFILE whatfile driveD
  219.  
  220.  * MERGE file1 file2 outfile /f3 /f2      A:\WORK.FIL anotherfile driveA
  221.  * MERGE file1 file2 outfile /f2          C:\BAT\0SIZE.BAT batchfile driveC
  222.                                           C:\BAT\0sIZE.BAT notsamefile driveC
  223.    you've probably  got the idea by       C:\ANOTHER.FIL thisfile driveC
  224.    now, but I have one more example       D:\LASTFILE whatfile driveD
  225.    because it's easy
  226.  
  227.    MERGE file1 /c /f1                     C:\BAT\0SIZE.BAT batchfile driveC
  228.  
  229.    If the merge (in  this case, back on itself) is not  case sensitive and on
  230.    the first field, all names in file1  are the same, and only the first name
  231.    will remain.
  232.  
  233.    Incompatibilities
  234.  
  235.    Please  see  INCOMPAT.DOC  for  incompatibilities.   If  you think you are
  236.    having one,  or any other problem,  please contact  me through one  of the
  237.    addresses given at the end of this document.
  238.  
  239.  
  240.  
  241.    Error Messages
  242.  
  243.    Both versions have several error messages  and terminate with an exit code
  244.    (the numbers shown below correspond to the exit code for "SW"), but "PD"'s
  245.    only pertain  to starting errors.  "SW"  can also report on  errors during
  246.    the actual  merge and has  the "/O" option,  which overwrites an  existing
  247.    file without prompting.   This would most likely be used  in a batch file.
  248.    If you are  batch processing, you could use "if  errorlevel==" to test for
  249.    an error, and take action accordingly.
  250.  
  251.     1 : "INPUTFILE1" not found.
  252.     or  "INPUTFILE2" not found.
  253.     or  both.
  254.             The   same   error   number   applies   to   all  three
  255.             possibilities; the  screen display will  indicate which
  256.             file or files were not found.
  257.  
  258.  *  2 : Error with output file "OUTPUTFILE".
  259.             Either the  output file could not  be opened before the
  260.             merge (most  likely due to an  incorrect path) or there
  261.             is an unknown file error with it after the merge.
  262.  
  263.     3 : Cannot use fourth filename "ANYFILENAME".
  264.             You have more than three filenames on the command line.
  265.  
  266.     4 : Incorrect use of parameters.
  267.             Somehow  your  combination  of  options  and  filenames
  268.             caused an error, e.g., too many total.
  269.  
  270.  *  5 : Cannot use filename "ANYFILENAME" more than once.
  271.             You entered the same filename more than one time.
  272.  
  273.     6 : No filename specified.
  274.             You forgot to enter an input filename.
  275.  
  276.  *  7 : { reserved for future use }
  277.  
  278.     8 : "/ " is not a valid option.
  279.             The  slash  and  character  combination  which  will be
  280.             displayed is not a MERGE option.
  281.  
  282.  *  9 : "/F?" is an invalid or duplicate merge key.
  283.             You either  have two or more  identical "F" options, or
  284.             the character following the "F"  did not translate to a
  285.             numeric value from 1 to 9.
  286.  
  287.  * 10 : Terminated by user.
  288.             You  ended   the  program   by  responding  "N"  to  an
  289.             "overwrite" warning.
  290.  
  291.  * 11 : Input file "INPUTFILE?" is empty.
  292.             The input file exists, so it was "found,"  but its size
  293.             is zero.
  294.  
  295.  
  296.  
  297.  * 12 : Blank or empty line in input file "INPUTFILE?".
  298.         Check file "OUTPUTFILE" for point of merge error.
  299.             All the error messages above  have something to do with
  300.             starting MERGE (except 2 which can also occur after the
  301.             merge is done); the rest  check on the file(s) during a
  302.             merge.  This  error is displayed when  one of the input
  303.             files has a  line of only spaces or  a completely empty
  304.             line (CR/LF only).  To help you locate the error, MERGE
  305.             reports which input file caused the problem and retains
  306.             the output file so you can  see at what point the error
  307.             occurred during the merge (if  the error is at the very
  308.             beginning of one of the input files and the size of the
  309.             output file is zero, MERGE will not retain the file and
  310.             display a message that the file was deleted).
  311.  
  312.  * 13 : Missing merge key in input file "INPUTFILE?".
  313.         Check file "OUTPUTFILE" for point of merge error.
  314.             MERGE can  usually detect a  missing primary merge  key
  315.             field (the  position where it should  be is spaces) but
  316.             not all (detecting missing keys after the first is even
  317.             more difficult).   Because the number  of delimiters is
  318.             not fixed  (you can have  any amount of  spaces between
  319.             fields) there are some combinations of empty fields and
  320.             primary merge keys, and any subsequent merge keys, that
  321.             will not be discovered.
  322.  
  323.  * 14 : Blank or missing field in input file "INPUTFILE?".
  324.         Check file "OUTPUTFILE" for point of merge error.
  325.             This can occur  if a merge key is  not the first field,
  326.             but the first field is  all spaces.  It could also mean
  327.             that because a field or  fields are missing, MERGE went
  328.             past  the end  of the  input line  trying to locate the
  329.             merge key field.
  330.  
  331.    "PD" is free for the taking, but if you find the shareware version more to
  332.    your liking, I  think $10 is a fair contribution.   That 10 bucks will get
  333.    you  a  disk  with  the  latest  shareware  version (less the unregistered
  334.    reminder), its source code, some  utility programs, a technical assistance
  335.    phone  number, and  notification of  anything else  exciting (in a "merge"
  336.    program? well, updates,  bug fixes, new products, etc.)  that comes along.
  337.    Please see REGISTER.DOC and README.DOC for more information.
  338.  
  339.    [Parameters]  can be  reached by  calling 618-549-8448.   Mail can also be
  340.    sent to any of the following addresses:
  341.  
  342.       Hal Parks                RIME:     ->774 or PARAMETERS
  343.       404B W. Oak              FIDO:     1:11/153
  344.       Carbondale, IL 62901     Internet: hal.parks@f153.n11.z1.fidonet.org
  345.  
  346.    Happy Merging!
  347.  
  348.  
  349.    P.S.  You don't have to be "registered" to get in touch.   And if you find
  350.          anything wrong or have any suggestions on how to improve the program
  351.          or a feature you'd like to see, I'd be glad to hear from you.
  352.  
  353.       Live long and prosper.
  354.  
  355.