Home > User Guide > Implementing ACIS Assembly Modeling in Applications
History and Roll in Assembly Modeling
ACIS Assembly Modeling is designed to support history and roll operations on both part and assembly entities. (Refer to the section Entity Managers in Assembly Modeling for a definition of "part entities" and "assembly entities".) Assemblies, model references, and properties are implemented using subclasses of ENTITY, and thus, participate in history and roll.
Managing history streams and roll operations are "part mode" operations; they are the responsibility of the application document(s) bound to the history stream. (Refer to the section Assembly Modeling vs Part Modeling for a discussion of part mode and assembly mode.) ACIS Assembly Modeling ensures that the correct history stream is active before performing operations on entities by calling the nested_activate_vf method on the entity manager which owns the entities being acted upon.
ACIS Assembly Modeling supports independent roll of model contents; every asm_model object can have an independent history stream bound to its corresponding application document. Multiple models may also be bound to the same history stream, up to having all models share the same history stream; most customers will want to associate a unique history stream with each model.
Note: The ACIS Part Management component has a limitation that either each PART (that is, model) must own a unique stream (distributed history mode) or all PART objects must share the same, default stream. This may prevent certain ASAT files which were saved with history from being loaded into an application, such as the Scheme toolkit, which uses the acis_pm_entity_mgr.
Models may be saved to ASAT with history, analogous to how entity lists may be saved to SAT with history with one subtle difference. If an ASAT file which was written with history contains models which share a history stream, then the corresponding models must share a stream when the ASAT file is read, even if history is not restored. This is different from the behavior of SAT, where the presence of history data in a file does not affect the result of a read operation in which history restoration is turned off.
The fact that ACIS assemblies are distributed across multiple histories streams (associated with the models used by the assembly) can lead to some behaviors and limitations which are non-intuitive to developers used to working in part modeling mode:
- Assembly modeling handle objects, that is, entity handles, component handles, and component-entity handles have two states: "valid", where they refer to live entities, and "invalid", where at least one of the entities to which they refer (directly or indirectly) has been deleted. If the deleted entity(s) is brought back to life (undeleted) by a roll operation, then the invalid handle becomes valid again. The validity of a handle can be queried calling its "is_valid()" method.
- The limitations against adding more than one assembly to a particular model and against adding model references that would create a circular dependency chain also take into account assembly and model reference entities which have been deleted, but still might be resurrected by a roll operation. For example, creating an assembly in a model, noting a delta state, deleting the assembly and then trying to create another assembly will fail during the attempt to create the second assembly. This is because the original assembly could still be resurrected by rolling back to the noted delta state, and so adding a second assembly would break the "one-assembly-per-model" rule. If the customer needs to avoid this limitation, api_asm_prune_assembly_history is provided which searches the delta states of a history stream and prune any delta state which contains bulletins involving an ASM_ASSEMBLY entity using api_prune_history. If an assembly entity is found in the current state, this API will delete the contents entire history stream.
Note: Use this routine with extreme caution, as it is an irreversible; any entities or state information destroyed by a call to this routine cannot be recovered.
The primary purpose of api_prune_history is to permit customer implementations of the virtual function asm_model_entity_mgr::clean_vf() which is called during model destruction, but it can also be used to destroy backup copies of assembly modeling entities.
- When saving with history, models which are referred to only by deleted model references are also saved to ASAT. This is due to the need to have these models be present after restore in case a roll operation is performed, which resurrects one or more of the deleted model-references.
- If you want to be able to roll to a previous state of the entire assembly (rather than rolling individual models within the assembly), you must be sure to note the state of all history streams associated with all models in the assembly. The actual roll must be performed on each stream.
- Assembly modeling operations may need to perform nested API calls on different history streams. Two functions, push_default_stream() and pop_default_stream() have been provided to support changing history streams in a nested manner. Refer to push_default_stream() for more details. Most likely, these functions will be used in customer implementations of the virtual functions asm_model_entity_mgr::nested_activate_vf() and asm_model_entity_mgr::nested_deactivate_vf(), which are discussed in the section Entity Managers in Assembly Modeling.
Related topics:
Entity Managers in Assembly Modeling
Assembly Modeling Macros and Notification Mechanisms
Implementing Atomic Save and Restore[Top]
© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.