_merge

#merge

###Merge one variable into another.

Syntax

result = merge ( destination,source[ ,autoincrement ] ) ;

Arguments

1. list destination

The destination variable.

2. list source

The source variable.

3. boolean autoincrement(optional)

If true, then variable names are auto-incremented V1, V2, V3.....

Return Value

list result

• merged_result : The result of the merge of source into destination.

The STATUS variable is set to $ACKNOWLEDGE

list result

• merged_result : The result of the merge of source into destination.

The STATUS variable is set to $ACKNOWLEDGE

Exceptions

• %ARGUMENT: Invalid arguments. Usage: result = merge ( destination,source[ ,autoincrement ] ) ;

• %BOUNDS: Source subscript is out of bounds in merge()

• %BOUNDS: Destination subscript is out of bounds in merge()

Description

The source values are merged with the destination values according to the following rules:

The source values are merged into the destination values in parallel.

_list d = { int a, float b, str c} ;
list s = { 1, 9.9, "hello" } ;
list m = merge ( d, s ) ;
describe m :_
**list 'm' = {
    int 'a' = {1},
    float 'b' = {9.9},
    list 'c' = {
        "hello"
    }
} ;**

If there are more source values than destination values, and if the destination is a fixed size, the extra source values are ignored.

_list d[3]  ;
list s = { 1, 9.9, "hello" ,"world"} ;
list m = merge ( d, s ) ;
describe m :_
**list 'm' = {
    int 'a' = {1},
    float 'b' = {9.9},
    list 'c' = {
        "hello"
    }
} ;**

Otherwise the extra source values are appended to the destination values.

_list d = { int a, float b, str c} ;
list s = { 1, 9.9, "hello" ,"world"} ;
list m = merge ( d, s ) ;
describe m :_
**list 'm' = {
    int 'a' = {1},
    float 'b' = {9.9},
    list 'c' = {
        "hello",
        "world"
    }
} ;**

If there are more destination values than source values, the extra destination values are unchanged.

_list d = { int a=0, float b=1.2, str c="goodbye"} ;
list s = { 1, 9.9} ;
list m = merge ( d, s ) ;
describe m :_
**list 'm' = {
    int 'a' = {1},
    float 'b' = {9.9},
    list 'c' = {
        "goodbye"
    }
} ;**

If the destination is a _vector or_list, then the source values will merge into the destination elements.

_int d[5] ;
list s = {1,2,3.1,"a",0xff}
list m = merge ( d, s ) ;
describe m ;_
**int 'm'[5] = {1,2,3,97,255} ;**

If an element of a destination list is a _literal _or a constant, then its value is replaced by the corresponding source element value.

_list d = { int a, "hello", 1 } ;
list s = {1,2,"world" } ;
m = merge ( d,s ) ;
describe m ;_
**list 'm' = {
    int 'a' = {1},
    2,
    "world"
};**

If the destination element is an referenced variable, then a new destination variable is declared and initialized with the contents of the source.

_list d = { &a, &b, &c } ;
list s = { 1, float x= 2.5, "hello" } ;
m = merge ( d,s ) ;
describe m ;_
**list 'm' = {
    ulong 'a' = {1},
    float 'b' = {2.5},
    str 'c' = {
        "hello"
    }
};**

The merge procedure works recursively on sub-variables within the source and destination.

The merge() function has an optional third argument , called auto-increment. It is useful for mapping SECS messages which are notorious for having lists within lists that vary in the array sizes. The auto-increment option creates unique variable names for the variable size SECS array lists.

For example, if the SEMI standards manual, the definition for S6F11, written in HyperScript syntax, is:

list S6F11_TEMPLATE = {
  &DATAID,
  &CEID,
  list REPORTS = {
    list REPORT = {
      &RPTID,
      list VALUES = {
        &V
      }
    }
  }
} ;

The references &DATAID, &CEID, &RPTID, and &V do not have defined data types. Furthermore, both the REPORTS list and the VALUES list can have variable array sizes, from 0 to 'n' elements.

Also, SECS messages do not have explicit labels for the contained elements, and thus they must be automatically generated. For example, when HyperScript receives a SECS message such as the S6F11 message below, the labels must be automatically generated:

list 'S6F11' = {
  ushort 'UW_0'[1] = {1},
  ushort 'UW_1'[1] = {41},
  list 'L_2' = {
    list 'L_0' = {
      ushort 'UW_0'[1] = {1},
      list 'L_1' = {
        ushort 'UW_0'[1] = {60},
        ushort 'UW_1'[1] = {60},
        list 'L_2' = {}
      }
    },
    list 'L_1' = {
      ushort 'UW_0'[1] = {2},
      list 'L_1' = {
        char 'A_0'[16] = {"1999060909040700"},
        ubyte 'UB_1'[1] = {1},
        ubyte 'UB_2'[1] = {1},
        ushort 'UW_3'[1] = {1639},
        char 'A_4'[6] = {"*JCHEW"},
        ulong 'UL_5'[1] = {0},
        char 'A_6'[6] = {"*JCHEW"}
      }
    },
    list 'L_2' = {
      ushort 'UW_0'[1] = {3},
      list 'L_1' = {
        char 'A_0'[4] = {"None"},
        ubyte 'UB_2'[1] = {0},
        ushort 'UW_3'[1] = {0}
      }
    }
  }
};

Even though ALL of the information from the SECS message is encoded in the HyperScript structure, the meaning of S6F11.L_1.L_1.A_4, for example does not have much meaning.

However, if we the merge of S6F11 into S6F11_TEMPLATE using the auto-increment option, it yields the following structure.

list 'S6F11_MESSAGE' = {
  ushort 'DATAID'[1] = {1},
  ushort 'CEID'[1] = {41},
  list 'REPORTS' = {
    list 'REPORT1' = {
      ushort 'RPTID'[1] = {1},
      list 'VALUES' = {
        ushort 'V1'[1] = {60},
        ushort 'V2'[1] = {60},
        list 'V3' = {}
      }
    },
    list 'REPORT2' = {
      ushort 'RPTID'[1] = {2},
      list 'VALUES' = {
        char 'V1'[16] = {"1999060909040700"},
        ubyte 'V2'[1] = {1},
        ubyte 'V3'[1] = {1},
        ushort 'V4'[1] = {1639},
        char 'V5'[6] = {"*JCHEW"},
        ulong 'V6'[1] = {0},
        char 'V7'[6] = {"*JCHEW"}
      }
    },
    list 'REPORT3' = {
      ushort 'RPTID'[1] = {3},
      list 'VALUES' = {
        char 'V1'[4] = {"None"},
        ubyte 'V2'[1] = {0},
        ushort 'V3'[1] = {0}
      }
    }
  }
};

Thus, S6F11.L_1.L_1.A_4 now becomes S6F11_MESSAGE.REPORT2.VALUES.V5, with a little more meaning and compliant with the SECS/GEM standards.

Examples

S6F11_TEMPLATE = {
  attr DATAID,
  &CEID,
  list REPORTS = {
    list REPORT = {
      &RPTID,
	list VALUES = {
	  &V
	}
    }
  }
} ;

list 'S6F11' = {
  ushort 'UW_0'[1] = {1},
  ushort 'UW_1'[1] = {41},
  list 'L_2' = {
    list 'L_0' = {
      ushort 'UW_0'[1] = {1},
      list 'L_1' = {
        ushort 'UW_0'[1] = {60},
        ushort 'UW_1'[1] = {60},
        list 'L_2' = {}
      }
    },
    list 'L_1' = {
      ushort 'UW_0'[1] = {2},
      list 'L_1' = {
        char 'A_0'[16] = {"1999060909040700"},
        ubyte 'UB_1'[1] = {1},
        ubyte 'UB_2'[1] = {1},
        ushort 'UW_3'[1] = {1639},
        char 'A_4'[6] = {"*JCHEW"},
        ulong 'UL_5'[1] = {0},
        char 'A_6'[6] = {"*JCHEW"}
      }
    },
    list 'L_2' = {
      ushort 'UW_0'[1] = {3},
      list 'L_1' = {
        char 'A_0'[4] = {"None"},
        ubyte 'UB_2'[1] = {0},
        ushort 'UW_3'[1] = {0}
      }
    }
  }
};

S6F11_MESSAGE = merge ( S6F11_TEMPLATE, S6F11, 1 ) ;
describe S6F11_MESSAGE ;

Related Links

map