Help for TRNSCOL2

PURPOSE:

"trnscol2" performs two functions, depending on the options specified.

The first of these is to convert long, vertically-aligned columns
of data in an IBIS-format file into smaller vertical columns based 
on a list of values supplied by the user.  Anytime one of these values
is found in a user-specified index column, the value in a corresponding
data column is transferred to a specified output column.  This operation
may be followed by AGGRG2 to obtain a more compact file.

The second function "trnscol2" performs is the inverse of the first.
If the relevant options are specified, "trnscol2" will convert short
vertically-aligned columns of data to a longer column.

EXECUTION:

    Note that if the options specified don't fully and uniquely
specify one of the two modes, an error message will be generated.
Options are listed with their relevant function numbers in 
parentheses in the parameter description section.  All parameters
for a given mode must be specified.

Example 1

trnscol2 INP=A OUT=B INDEX=1 DATA=3 VALUES=(1,2) TOCOL=(5,6)

This TAE command will look for the values 1 and 2 in index column 1
of IBIS file A, and transfer the corresponding data values from data
column 3 to columns 5 and 6.  The modified file is given the name B.
Note that parameters are only checked to four characters.  This is
an example of "trnscol2's" first mode.  Note, too, that all of the
parameters specified above are required; omitting any of them will
cause an error.  Finally, unused spaces in columns 5 and 6 are 
filled with zeroes.

Example 2

	INDEXCOL    1
	DATACOL	    2
	VALUES      1 2 3
        TOCOL    4 6 8

      Col 1   Col 2    Col 4  Col 6   Col 8

	1	47	47.0	0.0	0.0
	2	29	 0.0   29.0	0.0
	3	32	 0.0	0.0    32.0
	1	27	27.0	0.0	0.0
	2	62 	 0.0   62.0	0.0
	3	66	 0.0	0.0    66.0

Example 3	

trnscol2 INP=B OUT=C FROMCOL=(5,6) DATACOL=7 NCOL=7

This command will cause "trnscol2" to operate in its second mode, 
taking data from columns 5 and 6 of IBIS-file B and putting the
data in column 7 as illustrated in the next example.  Note that
all of the parameters specified are required, and that mixing any
of these (with the exception of DATACOL) with any of the parameters 
of the first mode will generate an error.  Finally, if NCOL is 
less than DATACOL, DATACOL columns will be processed.

Example 4

	FROMCOL	1 2 3
	DATACOL	6
	NCOL	6

Input file    Col 1   Col 2   Col 3   Col 4   Col 5   Col 6
		1	2	3	0	0	0
		4	5	6	0	0	0
		7	8	9	0	0	0
Output file   Col 1   Col 2   Col 3   Col 4   Col 5   Col 6
		1	2	3	0	0	1
		1	2	3	0	0	2	
		1	2	3	0	0	3
		4	5	6	0	0	4
		4	5	6	0	0	5
		4	5	6	0	0	6
		7	8	9	0	0	7
		7	8	9	0	0	8
		7	8	9	0	0	9

Note that all of the columns of the output file, up to the column
MAX( DATACOL, NCOL) are "stretched" to correspond to the new data 
column.


Restrictions:

The program has been rewritten in C with dynamic allocation, there
is no limit on IBIS file length, except virtual memory.  Only a few
columns are held at a time, so million record files should be easy.

The old program seems to produce real columns in the output file no
matter what the input was, so I kept that bad feature for now.  The
program should mimic the input formats.  SO FOR NOW, DON'T APPLY 
THIS PROGRAM TO AN IBIS FILE WITH ALPHABETIC COLUMNS.  The program 
should also be able to operate on alpha columns (datacol, tocol, etc).

WRITTEN BY:  A.L. Zobrist (first mode)     1 December 1976 
	     B. Gokhman  (second mode)     9 October 1980
             L. Bynum (written for VICAR2) 30 April 1985   
REVISION:  
	8-94 - Meredith Cox (CRI) - Made portable for UNIX

REWRITTEN:   A. Zobrist                    16 June 2002

REVISION:
  Fri Dec 28 2007 wlb switched to USES_ANSI_C AND LIB_CARTO; misc cleanup
  2022-07-27 B. Crocco afids to opensource
  
COGNIZANT PROGRAMMER:  A. Zobrist