User's Guide

COMBINE

Combines data from user supplied ASCII/labeled table files.

Function:

Combines data from two user supplied data files into an output file using a column from each file as a key to match and find the correct row. Subcommand -2ASC merges columns from two ASCII files into an ASCII file. Subcommand -ALT merges columns from an ASCII file and a labeled table (LT) file into an ASCII file. Subcommand -2LT merges columns from two LT files into a LT file.

Parameters:

Subcommand -2ASC:
Two input ASCII files are combined. All the columns from the first file and one column from the second file are merged into an output ASCII file.

INFILE
Input ASCII files. Two files must be entered. The first file has all of its columns copied. The second file provides one column to be merged with the columns from the first file. This group of columns is written to OUTFILE.

OUTFILE
Output file. The output ASCII file will be in column format and will contain the first ASCII file merged with one column of the second ASCII file.

KEYCOL
Key columns. The column of each input ASCII file where the data, which is used to find the proper row location in the second file, can be found. The data in the KEYCOL of the first file should match the data in the KEYCOL of the second file.

INCOL
Input column. The column in the second ASCII file which will be merged with the columns from the first ASCII file.

OUTCOL
Output column. The column in OUTFILE where INCOL will be placed.

COLWDTH1
Column widths. For each column of the first input ASCII file, an integer corresponding to the width of that column should be entered.

COLWDTH2
Column widths. For each column of the second input ASCII file, an integer corresponding to the width of that column should be entered.

OUTWIDTH(10 )
Width of output column. The integer portion of OUTWIDTH defines the width of OUTCOL. If ODTYPE is REAL then the fractional portion of OUTWIDTH defines the number of decimal places in OUTCOL. If OUTWIDTH is NULL, then ODTYPE must be STRING, and the column will be copied with no modifications.

APPDFLG("NO")
Append flag.

   = YES:  Blank spaces will be added to the output 
           column.  If ODTYPE is set to INTEGER or
           REAL, an extra blank space will be 
           appended to OUTCOL.  If ODTYPE is set to 
           STRING, an extra blank space is added to 
           the beginning of the string.
   = NO:   Blank spaces will not be added.

ODTYPE("STRING" )
Output data type.

   = INTEGER:   OUTCOL is formatted to the size of an 
		integer with OUTWIDTH significant 
	        digits.
   = REAL:	OUTCOL is formatted as a real with 
	   	the specified OUTWIDTH format.
   = STRING:    OUTCOL is formatted to the size of an
		integer with OUTWIDTH spaces.
Subcommand -ALT:
One input ASCII file and one input LT file are combined. All the columns from the ASCII file and one column from the LT file are merged into an output ASCII file.

INFILE
Input ASCII file. This file has all of its columns merged with one column from the INLT file and written to OUTFILE.

INLT
Input labeled table (LT). The input LT file will have one attribute column of data merged with the columns from INFILE.

OUTFILE
Output file. The output ASCII file will be in column format and will contain the ASCII file merged with one column of the LT file.

KEYCOL
Key column. The column of the input ASCII file where the data, which is used to find the proper row location in the LT file, is found. The data in this column will be compared to the data in the first ATRNAME1 attribute column of the LT file to find the proper location in the LT file.

OUTCOL
Output column. The column in OUTFILE where the second ATRNAME1 column will be placed.

ATRNAME1
Attribute names. Two values need to be entered. The first value corresponds to the KEYCOL and the second value corresponds to the input column for the LT file.

COLWDTH1
Column widths. For each column of the input ASCII file, an integer corresponding to the width of that column should be entered.

OUTWIDTH(10 )
Width of output column. The integer portion of OUTWIDTH defines the width of OUTCOL. If ODTYPE is REAL then the fractional portion of OUTWIDTH defines the number of decimal places in OUTCOL. If OUTWIDTH is NULL, then ODTYPE must be STRING, and the column will be copied with no modifications.

APPDFLG("NO")
Append flag.

   = YES:  Blank spaces will be added to the output 
           column.  If ODTYPE is set to INTEGER or
           REAL, an extra blank space will be 
           appended to OUTCOL.  If ODTYPE is set to 
           STRING, an extra blank space is added to 
           the beginning of the string.
   = NO:   Blank spaces will not be added.

ODTYPE("STRING" )
Output data type.

   = INTEGER:   OUTCOL is formatted to the size of an 
		integer with OUTWIDTH significant 
	        digits.
   = REAL:	OUTCOL is formatted as a real with 
	   	the specified OUTWIDTH format.
   = STRING:    OUTCOL is formatted to the size of an
		integer with OUTWIDTH spaces.
Subcommand -2LT:
Two input LT files are combined. All the specified columns of the first LT file and one column of the second LT file are merged into one output LT file.

INLT
Input labeled tables (LT). The first input LT file will have all ATRNAME1 attribute columns copied. The second LT file will have the second ATRNAME2 attribute column copied and merged with the columns from the first LT file and written to OUTLT.

OUTLT
Output LT file. The output LT file will contain all ATRNAME1 attribute columns and the second ATRNAME2 attribute column.

OUTCOL
Output column. The column in OUTLT where the second ATRNAME2 column will be placed.

KEYNAME
Key name. The attribute name of the key column for the first LT file. The data in this column will be compared to the data in the first ATRNAME2 column to find the proper location in the second LT file.

ATRNAME1
Attribute names. The names of the attribute columns from the first LT file which will be merged with one attribute column from the second LT file.

ATRNAME2
Attribute names. Two values need to be entered. The first value corresponds to the KEYNAME and the second value corresponds to the input column for the second LT file.

Examples:

  1. LAS> combine-2asc infile=(stat stat2) outfile=test keycol=(2 2) incol=1 outcol=2 colwdth1=(10,5,4,6) colwdth2=(13,5,2,6) outwidth=14 appdflg=yes

    Column two of file STAT.TXT is located. Then column two of STAT2.TXT is located. The data contained in these two columns is compared line by line. If a match is found, the data contained in column one of STAT2.TXT is read. If no match is found, the next row of STAT2.TXT is checked. If no match is found after every value in column two for STAT2.TXT is checked, a blank column of width 10, the OUTWIDTH default, is used. An extra blank character is added to the beginning of this column; because, APPDFLG = YES, and DTYPE is defaulted to STRING. The first column of STAT.TXT is written to TEST.TXT. Then the column read from STAT2.TXT is written to TEST.TXT (this is column location two). Finally, the remaining columns of STAT.TXT are written to TEST.TXT.

    Assume that STAT.TXT contains:

    . . . . . . . . Brookings 57006 234 HK124 Volga 57071 154 HK429. . . . . . . . .

    Also, assume that STAT2.TXT contains:

    . . . . . . . . South Dakota 57006 3 6AB037 South Dakota 57071 9 6AC984. . . . . . . . .

    Then, TEST.TXT will contain: . . . . . . . . . . Brookings South Dakota 57006 234 HK124 Volga South Dakota 57071 154 HK429. . . . . . . . . . .

  2. LAS> combine-alt infile=stat inlt=pix outfile=test keycol=1 outcol=1 colwdth1=(10,12,4) atrname1=(pixel mean) outwidth=10.2 odtype=real

    Column one of file STAT.TXT is located. Then the PIXEL attribute of the labeled table PIX.LT is located. The data contained in these two columns is compared line by line. If a match is found, the MEAN attribute column of PIX.LT is read and formatted as a real with two places after the decimal. If no match is found, the next row of PIX.LT is compared. If no match is found after every value in attribute column PIXEL in PIX.LT is checked, a blank column of width 10, the integer portion of OUTWIDTH, is used. The column read from PIX.LT is written to TEST.TXT. Then the columns of STAT.TXT are written to TEST.TXT.

  3. LAS> combine-2lt inlt=(pix mean) outlt=test outcol=3 keyname=pixel atrname1=(band npixels std mode) atrname2=(pixel mean)

    The PIXEL attributes for both LT files are located. These two values are compared row by row. If they are the same, the BAND, NPIXELS, STD, and MODE attributes of PIX.LT are located. The MEAN attribute of MEAN.LT is also located. If the two compared values are not the same, MEAN.LT is searched row by row. If no match is found after every value in attribute column PIXEL in MEAN.LT is checked, a default value of zero is used. The attributes are then merged in the order "BAND" "NPIXEL" "MEAN" "STD" "MODE", and are written to TEST.LT.

Description/Algorithm:

COMBINE merges columns from two files and places them in a new output file. The three methods are described next.

SUBCOMMAND -2ASC

Two ASCII files are input, and one ASCII file is output. The first file will have all of its columns copied. The second file will have one column copied (INCOL) and merged with the columns from the first file at column location OUTCOL. The positions of each of these columns are determined from the values entered in COLWDTH1 and COLWDTH2. As these columns are read row by row, the values in the key columns (KEYCOL) are compared. If a match is found, the proper columns will be merged. If the values don't match, the next row of the second file key column is compared. If all the rows of the second file are compared and no match is found, a default string of width, OUTWIDTH, will be merged at the proper location.

SUBCOMMAND -ALT

One ASCII file and one LT file are input, and one ASCII file is output. The ASCII file will have all of its columns copied. The LT file will have one column copied and merged with the columns from the ASCII file at column location OUTCOL. The ASCII file columns are determined from the values entered in COLWDTH1. The LT file column is located using the second attribute name of ATRNAME1. As these columns are read row by row, the values for the LT file key column (the first attribute name of ATRNAME1) are compared to the values found in the first file KEYCOL. If a match is found, the proper columns will be merged. If the values don't match, the next row of the LT is compared. If all the rows of the LT are compared and no match is found, a default string of width OUTWIDTH will be merged at the proper location.

SUBCOMMAND -2LT

Two LT files are input, and one LT file is output. The first LT file will have all of the columns specified in ATRNAME1 copied. The second LT file will have one column, specified by the second attribute name in ATRNAME2, merged with the columns from the first LT file at column location OUTCOL. As these columns are read row by row, the values for the second LT file key column (the first attribute name of ATRNAME2) are compared to the values found in the first LT KEYNAME attribute column. If a match is found, the proper columns are merged. If the values don't match, the next row of the second LT is compared. If all the rows of the second LT are compared and no match is found, a default value of zero will be merged at the proper location.

Nonfatal Error Messages:

  1. [combine-attribute] Attribute <XXXXXX> could not be found

    The specified attribute was not found in the labeled table.

  2. [combine-dtype] Invalid OUTWIDTH or ODTYPE

    OUTWIDTH was NULL and ODTYPE was set to something other than STRING. Either enter a value for OUTWIDTH or set ODTYPE to STRING.

  3. [combine-key] <XXXXXX> KEYCOL not found

    The specified key column was not found. Check to see that the specified key column points to a valid column.

  4. [combine-open] Error opening <XXXXXX> file

    An error occurred opening the specified file. Check to see that the file exists.

  5. [combine-read] Error reading input LT file

    An error occurred while reading the LT file. Check to see if the LT file is valid.

  6. [combine-write] Error writing file encountered

    An error occurred writing to the output file. Contact the LAS system administrator.

Fatal Error Messages:

  1. [combine-fatal] Fatal error encountered

    The prior message describes the exact error.

USERNOTES:

  1. All header information must be removed from input ASCII files.

  2. Input ASCII files must be in column format with each column width being defined in either COLWDTH1 or COLWDTH2.

  3. All ASCII files must have a .txt extension.

  4. Each labeled table file name points to only one labeled table, and must have a .lt extension.

  5. Each file can have a maximum of 3250 records.