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