This function allows you to add to the element map with the specified identifier a number of key/element associations at once.

The function works the following way.

  1. The elements from the sourceElements enumeration are iterated.

  2. On each iteration step, the current source element is temporary set as the generator context element.

  3. The subquery specified in the keysQuery parameter is executed which produces one or several keys.

  4. If the elementsQuery subquery is present, it is executed as well, which produces the elements that are actually put in the map: each newly generated element is associated with every key generated by keysQuery subquery.

  5. If the elementsQuery subquery is absent, the current source element is put in the map associated with every key generated by keysQuery subquery.

Parameters:

elementMapId

The element map identifier

Note: When the element map with such an identifier does not exist, the generator shows the error message.

sourceElements
The enumeration of source elements to be included in the element map (or by which the actual included elements are generated; see elementsQuery parameter for more details).

That element enumeration may be produced by a certain "heavy" query, exactly the one whose repeating the entire element map is supposed to avoid.

keysQuery
The subquery to generate the hash keys associated with each element from the enumeration provided by sourceElements parameter.

The keys subquery should be created using FlexQuery function. It should generate one or many keys for the source element passed as the generator context element.

The result returned by the subquery may be one of the following:

  1. Object[] containing keys
  2. Vector containing keys
  3. any other type is treated as a single key
The null value returned by the subquery is interpreted as no keys. That means, the given source element will not be associated with any keys.
elementsQuery
If this subquery is specified, it is also executed for each iterated source element, by which it may produce one or many other elements. Every such newly produced element will be associated in the map with every key generated by the keysQuery subquery.

The object returned by the elementsQuery subquery may be on of the following:

  1. A single element
  2. An Enumeration of elements
The null value will be treated as no elements. That is, nothing will be put in the element map on the given iteration.

Returns:

The number of new key/element associations added to the element map.

See Also:

createElementMap(), prepareElementMap(), putElementByKey(), putElementByKeys(), putElementsByKey()