}
AOM_delete(compare);
Figure 8-4. Compare Report Code
If you want the changes written to the BOM line Changes property, just add the BOM_compare_output_bomline argument to
the BOM_compare_output_report argument in the call to the BOM_compare_execute function.
Advanced Definition Concepts
The following are advanced definition concepts that you should understand.
Display Elements
In addition to primary and aggregate elements, BOM Compare can also support display elements. These are elements that have no impact on the actual comparison.
Display elements are extra context data that is written as part of compare output.
This is just an advanced version of the element display aliasing concept described earlier. Aliasing is limited in that it only works with property elements, and only a single alias property can be defined. Display elements can be defined with
methods, allowing non-property data to be used. You can also define as many display properties as you want.
Product Structure Management
The Element Display Aliasing section describes using bl_item_item_id as a display alias for bl_item. If you want to display the item name as well as the item ID, define a property display element for the bl_item_object_name property in the descriptor, as shown in figure 8-5:
CMP_create_prop_element(new_desc,
CMP_display_element, CMP_cache_sync, NULL,
false,
bomline_type,
"bl_item_object_name", NULL,
&new_element);
Figure 8-5. Property Display Element Definition
Note that display elements are not aggregated. Teamcenter assumes that the display element property value is constant across all BOM lines in a set. As such, the display element value is simply pulled out of the first BOM line that the compare engine finds.
Aggregate Element Uniqueness
With numeric elements, aggregation is easy: the numbers are just added together.
However, with string elements, aggregation is more difficult. The standard behavior is simply to concatenate the strings into a comma separated list, in alphabetical order. For example, A and B becomes A,B. If you aggregate A and A, it enforces uniqueness (A + A = A).
Element Ordering Modifier
Generally, string elements are sorted by simple alphabetic order. For example, aardvark comes before albatross. However, you might want to store numeric data in string attributes (for example, sequence number). In this case, alphabetic order is not correct. For example, 20 comes before 3. To correct this, use the CMP_set_prop_element_order function to set the element sort order to the CMP_order_by_length_and_value setting.
Chapter 8 Product Structure Management
Element Application Flags
The generic compare engine has no understanding of application concepts (BOM Compare is an application built on top of the generic compare engine). However, sometimes it is necessary for the application to store modifiers on the compare descriptor. This is done using the application flags. Application flags are set by the CMP_set_element_application_flag function. There are three application flags:
• BOM_compare_display_aggregate
• BOM_compare_stop_if_diff
• BOM_compare_dont_report_adds
These are defined and documented in the bom_tokens.h file.
Object Output Order
If you have multiple primary elements, the order in which you define the elements has an impact on the order in which objects are output in a report. Consider a compare where you have two primary elements: Item Id and Sequence Number.
Note that these are the primary elements for two of the standard compare modes. If you define the Item Id element before the Sequence Number element, then objects are output sorted by Item Id and then by Sequence Number within that.
Consider three BOM lines with the following attributes:
• item=widgetY, seqno=10
• item=widgetX, seqno=20
• item=widgetX, seqno=30
If you define your elements in the order (Item Id, Seq No), compare outputs the lines in the order 2, 3, 1. This order is clearly not ideal. You normally would really like the output to be in the same order in which it appears in PSE (in other words, 1, 2, then 3). To do this, simply reverse the order of element definition to be (Seq No, Item Id). However, this affects the column output order, described in the next section.
The use of sequence numbers introduces another feature. Consider this pair of BOM lines:
• item=widgetX, seqno=20
• item=widgetX, seqno=100
The order output should be 1 first and 2 second. Because sequence numbers are strings and not integers, a string compare is performed and alphabetically 100 comes before 20. To get around this, mark the sequence number element (and any others that store numbers as strings) as special with the CMP_set_prop_element_order
Product Structure Management
Column Output Order
By default, report output is generated with the columns in the same order as the elements were defined in. In the previous section we defined the Sequence Number element ahead of the Item Id element to force the object output order to match the PSE display order. The side effect of this is that the report columns are output in the (Seq No, Item Id) order. This does not match the standard PSE column display order where you expect to have the item defined in the leftmost column, followed by the sequence number. You can suppress the display of the sequence number element and define a display element against the sequence number property. However, the better alternative is to define a display order. To do so, create a tag array and populate it with the element tags in the order that you want the columns to appear.
Then pass that array into the CMP_set_element_display_order function as shown in figure 8-6.
Figure 8-6. Display Order Definition Methods
When using property-based compare elements, the system provides default behavior for comparing the property values. There are also some simple modifiers that can be applied to handle certain special cases. If none of the modifiers do what you need, you can write code that does exactly what you want and then register it against the element.
There are six method types supported by the generic compare engine:
• Compare Object
This method must compare a given object against a given compare set and return its opinion on whether that object belongs in that set. Note that this is just one primary compare element’s opinion. Other primary elements may disagree. All primary elements must say yes for the object to be allowed into the set.
• Compare Aggregate
This method must compare the left and right sides of the given compare set and return its opinion on whether the two sides are equivalent. Other aggregate elements may disagree.
• Cache
This method must update the element’s cache when the supplied object is added to the given side of the compare set.
Chapter 8 Product Structure Management
• UIF Name
This method returns the display name for this element.
• UIF Value
This method returns the display value for this element.
• Free Cache
One of the supported cache types is CMP_cache_pointer. This cache type means that the user is taking responsibility for creating and managing the cache. The generic compare engine simply maintains a void * pointer to the cache. When using this cache type, you must supply a Cache method (to create and update the cache), a UIF Value method (to return the display value for the cache), and a Free Cache method. This Free Cache method is used to release the memory allocated by the Cache method.
Nonproperty Elements
This is the logical conclusion of the use of compare methods. A non-property element is an element that is entirely driven through methods. It has no standard behavior.
This requires more effort, but allows maximum flexibility. For example, you could perform a compare using elements that live entirely outside Teamcenter. It could pull in data from a different database or from the Internet, which may take a significant amount of time. If you plan to do this, UGS highly recommends caching.
For an example of a non-property element, see the quantity elements in the
smp_user_bom_cmp.c file. While quantity is a BOM line property, Compare cannot handle it directly because of the need to cope with special concepts like as required and undefined (PSE’s default quantity, in other words, one unit).