NAME
gather - combine n data sets into one according to 3
schemes
SYNOPSIS
gather [ [ -N[],-N[],...,-N[]ntap(i) ] [ -F[]ftap ] ] [
-Ootap ] [ -nnblk ] [ -m ] [ -T ] [ -b ] [ -B ] [ [ -Y ] [
-S ] [ -s ] [ -D2 ] [ -nsns ] [ -nene ] [ -T0tdel ] [ -rsrs
] [ -rere ] [ -R0rdel ] ] [ -o ] [ -V ] [ -? ]
DESCRIPTION
gather combines n data sets into one (n<=1000 although most
computer systems have built in limitations on the number of
connected files - this is a system resource and sometimes
can be changed). The input traces may be multiplexed
record-by-record or input records may themselves be placed
back-to-back either in separate blocks or in one super
block. Note: all input data sets must have the same
traces/record and records/line. You cannot pipe into this
program except when running inside IKP but you can pipe out.
Because of this fact if the internal record and trace selec-
tion options are used the input data must reside on disk (in
XIKP editt process can be connected to the merge*to1 inputs
to do input selection).
This is the ideal tool in XIKP to gather up parallel pro-
cessed streams, i.e. those sent out by splitr. Within fBXIKP
the gather functions for various numbers of streams are
accessed through the mergeNto1 scripts.
Using gather on the command line it is sometimes easier for
large numbers of input files to put those file names in a
file and read that file to extract the actual input file
names. One can either read file names by using multiple -N
entries or by using the file of file names option.
gather gets both its data and its parameters from command
line arguments. These arguments specify the inputs, output,
multiplexing traces and verbose printout, if desired.
Command line arguments
-N[],-N[],...,-N[] ntap(i)
Enter each input data set name or file immediately
after typing -N (up to 1000). This input file should
include the complete path name if the file resides in a
different directory. Example -N/b/vsp/dummy tells the
program to look for file 'dummy' in directory 'vsp'
stored on the 'b' disk. Optionally...
-F ftap
-O otap
Enter the output data set name or file immediately
after typing -O. This output file is not required when
piping the output to another process. The output data
set also requires the full path name (see above).
-m If present each output record is composed of traces
from each of the input records interleaved, i.e. multi-
plexed. If the input records have unequal the program
aborts. The output record trace count is equal to the
input record count. mpx = true is meant for multicom-
ponent trace pipelining or to gather up data spewed out
by the rotary trace option (1) in splitr.
-T A variation of the multiplex option -m. This will take
traces on a rotating basis from each of the input data
sets and build one long output trace for each rotation
through the input data sets, i.e. each output trace
will be made up of a trace from DSN1 with the following
sample starting the trace from the DSN2, followed by
the trace from DSN3, etc, all in one long trace. When
the rotation (through the number if input data sets) is
complete the process repeats for the next set of traces
from the input.
-b If present the input records are sequenced back-to-back
and the total output record count is n*nrec, where n is
the number of input data sets and nrec is the record
count per input data set. The number of traces/record
on all the input data sets must be the same
-n nblk
Enter the number of records per block override. This is
for gathering up data output by splitr operating in
rotary record mode. An option there allowed mode than 1
record at a time to be sent to each output stream.
Default = 1. If the default was not used in the splitr
process then that value must appear here also.
-B If present the input records are sequenced as above but
are collected into one super block. The output record
count is therefore nrec. The output number of
traces/record is the sum of each of the input
traces/record values. Each input data set may have
different traces/record values. This option basically
gathers up data spewed out by option 3 in splitr.
-S If present the input data sets are output in sequence,
i.e. all of data set1 is output followed by all of data
set2, followed by all of data set3, etc. The restric-
tion here is that all data sets must have the same
number of trace per record. This option basically
gathers up data spewed out by option 1 in splitr where
the data is partitioned into contiguous chunks each
chunk having its own line header. For this option
editt-like trace and record selection is permitted
either on the command line or in the file containing
the list of file names (see -F[] input above).
-D2 If present the input data are on D2 tape as part of a
virtual file system (tape is accessed by a robot). The
data sets must be opened as they are encountered on
tape and read through to EOF (i.e. cannot open data
sets first then go back and read each one). With this
option there is no checking to see whether the number
of traces per record is the same for each data set.
Also the number of records cannot be determined to a
very large number is put into NumRec of the output data
set.
-s If present the input data sets are output in sequence
but only the first of the input data sets has a line
header, i.e. all of data set1 is output followed by all
of data set2, followed by all of data set3, etc. The
restriction here is that all data sets must have the
same number of trace per record but the data sets don't
have to be divided on record boundaries. This is most
useful for tape input data sets. This option basically
gathers up data spewed out by option 1 in splitr where
the data is partitioned into contiguous chunks with
only the first chunk having a line header. For this
option editt-like trace and record selection is permit-
ted either on the command line or in the file contain-
ing the list of file names (see -F[] input above).
-Y If present the input data sets are assumed to have been
generated using the -Y option in umerg which outputs
identical data streams trace-by-trace in each stream:
trace1 in each stream, followed by trace2 in each
stream, .... Therefore when gathered up all trace 1's
for streams will be put together, followed by all trace
2's for the streams, .... The user will have to use an
editt to reconfigure this multiplexed data set into
contiguous back-to-back data sets. This option basi-
cally gathers up data spewed out by option 1 in splitr
where the input data is duplicated into multiple output
streams. Only global trace and record selection is
possible. These are defined by the selection command
line entries below.
-ns ns
For -S -s or -m options only: enter global starting
sequential trace number of each data set. Default = 1.
Individual data set starting trace numbers may be put
into the file containing the list of data set names on
the same line as the file name, e.g. a line might look
like: [filename] -ns5
-ne ne
For -S -s or -m options only: enter global ending
sequential trace number of each data set. Default =
last trace of each record. Individual data set ending
trace numbers may be put into the file containing the
list of data set names on the same line as the file
name, e.g. a line might look like: [filename] -ne5
-T0 tdel
For -S or -s options only: enter global sequential
trace number increment of each data set. Default = 1.
Individual data set trace increments may be put into
the file containing the list of data set names on the
same line as the file name, e.g. a line might look
like: [filename] -T02
-rs rs
For -S, -s or -m options only: enter global starting
sequential record number of each data set. Default = 1.
Individual data set starting record numbers may be put
into the file containing the list of data set names on
the same line as the file name, e.g. a line might look
like: [filename] -rs3.
-re re
For -S -s or -m options only: enter global ending
sequential record number of each data set. Default =
last record in each data set. Individual data set end-
ing record numbers may be put into the file containing
the list of data set names on the same line as the file
name, e.g. a line might look like: [filename] -re200
-R0 rdel
For -S or -s options only: enter global sequential
record number increment of each data set. Default = 1.
Individual data set record increments may be put into
the file containing the list of data set names on the
same line as the file name, e.g. a line might look
like: [filename] -R010
-o If present the original number of traces per record and
number of records will be extracted from the first data
set and written into the output data set line header.
This of course assumes the multiple input data sets
have come from a splitr run or have been created care-
fully so that when merged together this header value
makes sense. Don't worry, if you screw up here you
haven't messed the data up only the NumTrc and NumRec
line header entries and these can be fixed by doing an
in-place utop.
-V Enter the command line argument '-V' to get additional
printout.
-? Enter the command line argument '-?' to get online
help. The program terminates after the help screen is
printed.
BUGS
Currently internal record and trace selection is permitted
for the -Y, -S, -s or -m options only. For the -S and -s
options the selection can be entirely general with different
parameters for each input data set. For the -Y option only
global command line parameters will be accepted which will
be common to each input data set. For the -m option the
selection can be somewhat general but the number of records
and traces per record being fed from each input dataset but
be constant so that output records are of equal length. If
not the gather will hang. The -m consideration was for
selecting subsets of LI,DI information from post migration,
pre stack offset volumes and output gathers of this data.
In XIKP trace and record selection should be done by con-
necting editt boxes to the inputs of the merge*to1
processes.
See Also
splitr
COPYRIGHT
copyright 2001, Amoco Production Company
All Rights Reserved
an affiliate of BP America Inc.
Man(1) output converted with
man2html