GROUP2

From ICE Enterprises
Jump to navigation Jump to search

Creates a new file from the grouping of fields in two input files.

<OUT>   Output file
<IN1>   First input file.
<IN2>   Second input file.
<TAB1>  Table defining the mappings for a the first input file.
<TAB2>  Table defining the mappings for a the second input file.
<TYPE>  Output file type (1000,2000,3000,5000 or 6000).

Summary:
  This command interleaves data from two or more input files and outputs a
  Type 1000/2000/3000/5000/6000 file. To allow for more flexibility this
  command takes in a mapping of the records for each of the input files. This
  mapping maps the new record to the old record, using the following syntax:
    {<NEW1>=<OLD1>,<NEW2>=<OLD2>}

  This primitive will create a subrecord named <NEW1> in the output file that
  corresponds to the subrecord named <OLD1> in the input file. The subrecord
  created in the new file will have the same format as that in the old file.

  For greater flexibility it is possible to perform in-line conversions that
  will change the numeric type or change the size of an ASCII type (it will
  not convert between ASCII and numbers) using the following syntax:
    {<NEW1>=<T1>:<OLD1>,<NEW2>=<T2>:<OLD2>}

  The above syntax will make a subrecord named <NEW1> in the output file that
  is equal to the subrecord named <OLD1> in the input file after converting
  to format <T1> (where <T1> is a type format such as "SF" or "VD" or "4A").
  If the new type has more scalar values than the old one (e.g. old is "CF"
  and new is "VF") the extra values will be filled with zeros; if it has fewer
  scalars (e.g. old is "VD" and new is "SD") then any extra ones will be
  discarded. (ASCII values will be padded with spaces or truncated as needed.)

  A third syntax allows the grouping of multiple subrecords in the input file
  into a single subrecord in the new file (not available for ASCII types):
    {<NEW1>=<T1>:<OLD1a>|<OLD1b>,...}
  
  The above syntax will make a subrecord named <NEW1> where each value is
  in the output file that is equal to the grouping of the two fields in the
  input file. Note that a type specifier is required. Typical usage:
    {COMP=CF:REAL|IMAG,POS=VD:ALT|LL}

  The above example will create a subrecord "COMP" that is "CF" that has the
  two scalar values ("REAL" and "IMAG") combined (i.e. COMP=(real,imag)).
  Additionally it will create a subrecord "POS" that combines the scalar "ALT"
  and the "CF" value "LL" (i.e. POS1=(lat,lon)) and makes them a "VD" value
  (i.e. POS=(alt,lat,lon)).

  Note that it is an error for the output file to contain more records than
  the file type allows:
     Type 1000: max = 1
     Type 2000: max = <frame size>
     Type 3000: max = 26
     Type 5000: max = 14

Notes:
  - It is an error for an output name to be defined more than once.
  - If the output file is a Type 2000 file, all output fields must have the
    same format.
  - Only one input file is required. This feature can be used to convert
    between file types or convert names.
  - If the output file is a Type 3000 file, the "offset" field in the record
    definition will match the actual byte offset required (there will be no
    gaps in the data).
  - If the output file is a Type 5000 file the "units" and "type" for the
    component will default to NONE (0). Additionally the QUADWORD fields in
    the adjunct header will be set to zero (the name will be blank).
  - If the input file is a Type 1000 file its sole record will use the
    name "F1".
  - If the input file is a Type 2000 file its record will be named "F1",
    "F2", ... "Fn" (where n is the frame size). -- These names match the
    column names used by LIST.
  - If the two input files differ in size, the output file will have the
    same size as <IN1>. If <IN2> is larger, the extra values will be
    ignored; if <IN2> is smaller the missing values will be treated as if
    they were zero (blank strings for ASCII types).


Examples:
  1. The first input file is a Type 5000 file with records "FOO","BAR","BAZ";
     the second is a Type 3000 file with records "MISC". The output file
     should be a Type 3000 file that contains all of the records in the two
     files:

       nM> GROUP2 outfile 3000 in1 {FOO=FOO,BAR=BAR,BAZ=BAZ} in2 {MISC=MISC}

  2. The first input file is a Type 5000 file with records "FOO","BAR";
     the second is a Type 3000 file with records "BAR","BAZ". The output file
     should be a Type 5000 file that contains all of the records in the two
     files, except that the "BAR" in the first should be named "BAR1" and the
     "BAR" in the second should be named "BAR2":

       nM> GROUP2 outfile 5000 in1 {FOO=FOO,BAR1=BAR} in2 {BAR2=BAR,BAZ=BAZ}

  3. Convert a Type 3000 file with records "NAME","ALT","LAT","LON" to a
     Type 5000 file with records "NAME","POS" where "POS" is (alt,lat,lon):

       nM> GROUP2 outfile 5000 infile {NAME=NAME,POS=VD:ALT|LAT|LON}


  4. Use the /ORDER= switch to set the order of the records in the output
     file:

       nM> GROUP2/ORDER="FOO,BAR,BAZ" outfile 3000 in1 {BAR=BAR,FOO=FOO} &
                                                   in2 {BAZ=BAZ}

  5. Create a Type 3000 file with records "FOO","BAR","VAL" where "VAL" is
     a value that comes from a Type 1000 file.

       nM> GROUP2 outfile 3000 in1 {BAR=BAR,FOO=FOO} in2 {VAL=F1}

  6. Create a Type 3000 file with records "FOO","BAR","VAL" where "VAL" is
     a complex value that comes from a Type 2000 file that has a frame size
     of 2 where frame 1 is the real component and frame 2 is the imaginary.

       nM> GROUP2 outfile 3000 in1 {BAR=BAR,FOO=FOO} in2 {VAL=F1|F2}

  7. Join two Type 1000 files into a Type 3000 file with record names "IN1"
     and "IN2":

       nM> GROUP2 outfile 3000 in1 {IN1=F1} in2 {IN2=F2}

  8. Join a Type 1000 file with timecode and a Type 2000 file with a frame
     size of 4:

       nM> GROUP2 outfile 3000 in1 {TIME=F1} in2 {F1=F1,F2=F2,F3=F3,F4=F4}

  9. Combine three Type 1000 files one of which holds timecode ("TIME"),
     another with the real values and a third with the corresponding
     imaginary values into a Type 3000 file with fields "TIME" and "VAL"
     (where VAL=(real,imag)).

       nM> GROUP2 temp    3000 in2 {REAL=F1} in3 {IMAG=F1}
       nM> GROUP2 outfile 3000 in1 {TIME=F1} temp {VAL=CF:REAL|IMAG}

 10. Combine two Type 1000 files into a Type 2000 file:

       nM> GROUP2 outfile 2000 in1 {F1=F1} in2 {F2=F1}

 11. Split the records of a Type 2000 file (frame size is 2) into two Type
     1000 files:

       nM> GROUP2 out1 3000 infile {F1=F1}
       nM> GROUP2 out2 3000 infile {F1=F2}

 13. Split a Type 5000 file with "POS","NAME","FREQ" into three Type 1000
     files (where "POS" is converted to "VD", "NAME" to "2A" and "FREQ" to
     "SF"):

       nM> GROUP2 out1 1000 infile {F1=VD:POS}
       nM> GROUP2 out2 1000 infile {F1=2A:NAME}
       nM> GROUP2 out3 1000 infile {F1=SF:FREQ}

 14. Combine two files using mappings defined in tables:

       nM> res MAP1 {FOO="FOO"}
       nM> res MAP2 { }
       nM> res MAP2.BAR="BAR"
       nM> res MAP2.BAZ="BAZ"
       nM> GROUP2 outfile 3000 in1 ^map1 in2 ^map2

 15. Given a Type 3000 file with fields "FOO","BAR","BAZ", make a copy of
     the "FOO" field and name it "COPY":

       nM> GROUP2 outfile 3000 infile {FOO=FOO,BAR=BAR,BAZ=BAZ} &
                               infile {COPY=FOO}

Switches:
  /ORDER=list  Defines the order of subrecords in the output file for Type
               3000/5000/6000 files. If this switch is not used, the ordering
               will be arbitrary.