User's Guide

MERGE

Transfers data into an existing IBIS tabular file from a second IBIS tabular file based on the equality of specified values.

Function:

Transfers data into an existing image based information system (IBIS) tabular file from a second IBIS tabular file based on the equality of specified values.

Parameters:

INFILE1
First input file. Input IBIS tabular file to be modified. The file must be sorted into ascending order on the columns used as the key columns (KEYCOL1).

INFILE2
Second input file. Secondary input IBIS tabular file containing the data to be entered into the first input file. The file must be sorted into ascending order on the columns used as the key columns (KEYCOL2).

KEYCOL1
First key columns. Columns in the first input file to be used as matching keys.

KEYCOL2
Second key columns. Columns in the second input file to be used as matching keys.

INCOL
Input columns. Columns to be copied from the second input file.

OUTCOL
Output columns. Columns to copy to in the first input file.

DEFVAL(--)
Default value. The value to be output to the OUTCOL columns of the first input file when no match is found. The default value for this parameter specifies that the values in the file are to remain unchanged.

Examples:

  1. LAS> merge infile1=one infile2=two keycol1=1 keycol2=1 incol=2 outcol=2

    Column 1 from file ONE is used as the key column to be checked against column 1 of file TWO. If a match is made, the corresponding value from column 2 of TWO is written in column 2 of ONE. If no match is found for a key in ONE, the value in column 2 is not changed.

    The following diagram illustrates a sample run using the parameters for Example 1.

             Original ONE            TWO	      ONE after merge
    
                1   2 	        1   2	            1   2
              _________           _________           _________ 
             |         |         |         |         |         |
             |  0   3  |	     |  0   2  |         |  0   2  |
             |  0   4  |	     |  1   3  |         |  0   2  |
             |  1   6  |	     |  8   4  |         |  1   3  |
             |  5   8  |	     |  9   5  |         |  5   8  |
             |_________|         |_________|         |_________|
    

  2. LAS> merge infile1=one infile2=two keycol1=(1 2) keycol2=(1 2) incol=2 outcol=3 defval=99

    Columns 1 and 2 from file ONE are used as the key to be checked again columns 1 and 2 of file TWO. If a match is made, the corresponding value from column 2 of TWO is written in column 3 of ONE. However, if no match was found for a key, the default value of 99 is written in column 3 of ONE instead. The following diagram illustrates a sample run using the parameters for Example 2.

               Original ONE            TWO	      ONE after merge
    
                1   2   3 	          1   2          1   2   3
              _____________         _________      _____________ 
             |             |       |         |    |             | 
             |  0   0   0  |       |  0   0  |    |  0   0   0  |
             |  1   0   0  |       |  1   5  |    |  1   0  99  |
             |  2   4   0  |       |  3   7  |    |  2   4  99  |
             |  3   7   0  |       |_________|    |  3   7   7  |
             |_____________|                      |_____________|
    

Description/Algorithm:

The program begins with the standard initialization and retrieval of user-specified parameters. The input files are opened. The values from the key columns in the first row are read from the first input file. This is compared to the first key read from the second input file. Keys are read sequentially from rows of the second file until either a match is made with the first key or the second key becomes greater than the first indicating that there is no match for the first key. The next key is then read from the first file and compared to the current key from the second file. Processing continues as described above for the remainder of the files.

Nonfatal Error Message:

  1. [merge-close] Error closing <XXXXX> file

    An error was encountered while closing the <XXXXX> file. The data may still be valid.

Fatal Error Messages:

  1. [merge-fatal] Fatal error encountered

    A fatal error was encountered during processing. The first input IBIS tabular file may or may not be valid. The message that is displayed immediately preceding this message is the specific error that was encountered.

  2. [merge-key] The number of values specified for KEYCOL1 and KEYCOL2 parameters are not equal

    The KEYCOL1 and KEYCOL2 parameters work together and the same number of values must be entered for each one.

  3. [merge-open] Error opening <XXXXX> file

    An error was encountered while trying to open the specified IBIS tabular file.

  4. [merge-unequal] The number of values specified for the INCOL, OUTCOL, and DEFVAL parameters are not equal

    The INCOL, OUTCOL, and DEFVAL parameters work together and the same number of values must be entered for each one.

User Note:

  1. The input files must be sorted into ascending order on the columns used as the key columns. The LAMS function MTBSORT can be used to do this. Note that the columns must be specified in the same order in MTBSORT as they are listed in the corresponding KEYCOL parameter in MERGE. For example, if the user desires to use columns 1 and 2 as the key columns for the merge, then the sort must be done with column 1 as the primary sort column and column 2 as the secondary one.