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