Assembly Modeling Macros and Notification Mechanisms

Home > User Guide > Implementing ACIS Assembly Modeling in Applications

Assembly Modeling Macros and Notification Mechanisms

An application which supports assembly modeling will typically have two modes of operation: part modeling mode and assembly modeling mode. One of the concepts associated with part modeling mode is a "modeling context", that is, the history stream, units, tolerance values, for example, associated with a particular part or parts. In general, each document within the application will be associated with a particular modeling context, because each document will generally have its own history stream and might have different units, tolerances, etc. This means that every asm_model object within an assembly modeling hierarchy is associated with the modeling context belonging to the application document bound to the model's entity manager.

Topics include:

Modeling Contexts
Notification Mechanisms
Assembly Modeling Macros

Modeling Contexts

Part mode operations (that is, API functions) can be thought of as operations on the application document, and so are typically performed within that document's modeling context (for example, with the document's history stream active). Assembly mode operations (that is, asmi functions), on the other hand, are operations on the assembly modeling tree and therefore are not associated with a particular modeling context. In other words, (API) operations on an ENTITY (which resides within a particular history stream) must be performed within the modeling context associated with that ENTITY's history stream. (asmi) operations on an asm_model object (which resides outside of history) need not be performed within a particular modeling context.

Notification Mechanisms

Although asmi functions are not associated with a particular modeling context, they may (as sub-operations) perform operations on entities which are in a particular context. This requires a mechanism for the asmi function to notify the application document associated with that document:

that it should make its modeling context active
what changes were made to entities in the document by assembly modeling
that the asmi function is done working within the document's modeling context.

Conversely, a document can be modified by a part mode operation without going through the assembly modeling interface (for example, by performing an extrude operation on a body in the document). This requires a mechanism for the application to notify the asm_model objects depending upon the specified document (through model references) that the contents of the document have changed.

Assembly Modeling Macros

The former requirement (for notifying a document that it should make its modeling context active) is satisfied by the macros MODEL_BEGIN and MODEL_END defined in asm_api.hxx. These macros encapsulate the following operations:

MODEL_BEGIN(asm_model* model)

Pushes model onto a model nesting stack.
Requests activation of the document by calling nested_activate_vf() on model's entity manager.
Defines a "result" outcome object.
Opens an ACIS EXCEPTION block.
Places the model's entity manager pointer value into a convenience variable named "mgr".

MODEL_END(asm_event_type event_type)

Closes the ACIS EXCEPTION block, populating "result" with the error code of any error that was thrown.
Notifies the model's document of changes by passing "event_type" and "result" to the entities_changed_vf() method of the model's entity manager.
Pops the model nesting stack.
Requests re-activation of the previously active document by passing the top of the model nesting stack (that is, the previous model) to the nested_deactivate_vf() method of the model's entity manager.
For any event type other than ASM_NO_CHANGE, notifies assembly models which reference "model" that "model" has been changed. This is done by passing "event_type" to the contents_changed method of "model".

When activating a document in order to perform ACIS direct interface (rather than API) operations, client code should instead use the corresponding macros API_MODEL_BEGIN/ API_MODEL_END, which replace the EXCEPTION block with an API macro block. Note that the notifications mentioned above do not take place when "model" is already the active model. For a discussion of the various types which can be passed to MODEL_END, refer to the section Entity Managers in Assembly Modeling.

CAUTION: It is important for you to understand that both MODEL_END and API_MODEL_END signal error states by returning a bad outcome, rather than by throwing an exception; this is the same behavior as is found in ACIS API functions. You should always check the result variable immediately after MODEL_END or API_MODEL_END for a bad outcome and resignal or handle the error.

The latter requirement (for notifying parents of a document's model that the document has been changed) is satisfied by the contents_changed method of asm_model. This results in a call to the sub_model_changed() method on the entity manager of each parent model. (Model A is a parent of Model B if B is a sub-model of A.)

The header file asm_api.hxx also defines the macros ASM_VERS_BEGIN and ASM_END. These are analogous to the API_VERS_BEGIN and API_END macros, with the exception that they open an ACIS EXCEPTION block, rather than an API block (that is, they do NOT open a new bulletin board). They are used at the beginning and end of an asmi routine to:

process requests for a preceding version of the algorithm (made through the AcisOptions object).
ensure that the asmi function satisfies a no-throw contract (through the use of an exception block).
create an outcome object which encapsulates the result of the asmi routine.

Usage

These macros are used heavily within the implementation of asmi functions, but are likely to be much less frequently used by application code. The primary requirement is that, before an operation (that is, function or method) is called on an ENTITY, the modeling context within which the ENTITY lives must be made active. In application code, this is usually accomplished simply by making the document containing the ENTITY active. When this is not possible or convenient, however (for example, if the currently active document has an open bulletin board, and so the new document must be activated in a nested manner), application code can use the MODEL_BEGIN and MODEL_END macros to activate the corresponding document, for example.
entity_handle* h; // handle for ENTITY we need to work on
// activate model’s document
MODEL_BEGIN(h->get_owning_model())  // activate h’s model
	ENTITY* h_ent = h->entity_ptr(); // get h’s entity

	// perform part mode operation that changes h’s geometry
	outcome out = api_do_something_geometric(h);
	check_outcome(out); // sys_error if bad outcome

// notify document and parents that a geometric change took place
MODEL_END(ASM_BREP_GEOM_CHANGE)
In addition to not performing operations on an ENTITY while its modeling context is inactive, Spatial also recommends that ENTITY pointers (and ENTITY_LIST objects) only be defined within the scope in which their modeling context is active. This was done in the example code above; note that “h_ent” is defined inside the MODEL_BEGIN/MODEL_END block, and so cannot be accessed outside that scope.

The reason for this recommendation is to anticipate possible future enhancements to ACIS Assembly Modeling. One possible enhancement would be to support “representation management”, where entities owned by inactive models could be deleted from memory (but stored on disk) in favor of a lighter weight representation of the model, for example a facetted representation. If your application is holding onto ENTITY pointers, rather than the corresponding entity handles, outside of the scope where their owning model is active, then it will probably be more difficult for you to activate such representation management functionality in your application if and when it becomes available.

To reiterate, operations on entities must only take place when the corresponding document is active; the MODEL_BEGIN and MODEL_END macros provide a mechanism for managing this.

Related topics:

Entity Managers in Assembly Modeling
History and Roll in Assembly Modeling
Implementing Atomic Save and Restore

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.