Assembly Modeling Save and Restore

Home > User Guide > Understanding Assembly Modeling

Assembly Modeling Save and Restore

ACIS Assembly Modeling introduces a new, SAT-based, file format for persistence of assembly models called ASAT (Assembly-SAT). This new format supports the differences between assembly modeling and part modeling; specifically, the primary "top-level" object in assembly modeling, asm_model, is not an entity. Thus, this object cannot be persisted to SAT.

Note: Throughout this discussion, "SAT" is used as a generic term for both SAT (text) and SAB (binary) formats, and "ASAT" is used as a generic term for both ASAT (text) and ASAB (binary) formats.

Topics include:

ASAT Persistence Interfaces and Mechanisms
Behavior Differences between ASAT and SAT
Monolithic and Atomic Saves
ASAT Save and Restore Interface Functions
ASAT File Structure

ASAT Persistence Interfaces and Mechanisms

The interfaces and mechanisms of ASAT persistence have been designed to have as much commonality with SAT as is possible:

Part Modeling Assembly Modeling

api_save_entity_list() takes a list of primary entities to save to SAT; the SAT file contains the primary entities, all other savable entities to which they (recursively) point, and, in the case of save-with-history, the history stream containing these entities along with backup copies of all entities in the stream asmi_save_model_list() takes a list of primary models to save to ASAT; the ASAT (or ASAT and SAT, in the case of atomic save) file(s) will contain the primary models, all sub-models of the primary models, and, in the case of save-with-history, any models which could become sub-models of the saved models after a roll operation.

api_restore_entity_list() is used to restore a list of entities from a SAT file asmi_restore_model_list() is used to restore a list of models from an ASAT file.

api_save_entity_list() takes a pointer to a FILE or FileInterface object representing a file that has been opened and positioned by application code and writes a SAT segment into the file, leaving the file positioned at the end of the SAT segment. This allows customers to embed SAT data as a segment within their own save-file format. asmi_save_model_list() operates in the same way, except that it writes an ASAT segment. This allows customers to embed ASAT data as a segment within their own save-file format.

SAT can be written in text, binary, or other (by customers who define their own FileInterface objects) format. ASAT can be written in text, binary, or other (by customers who define their own FileInterface objects) format.

SAT files can save history information. ASAT files can save history information.

Table. Commonalities among Assembly and Part Modeling

Behavior Differences between ASAT and SAT

Some of the explicit differences between ASAT and SAT formats include:

Part Modeling Assembly Modeling

api_save_entity_list() saves a list of ENTITY objects. asmi_save_model_list() saves a list of asm_model objects.

An ASAT file has embedded SAT segments which are used to save the ENTITY objects and history streams contained within the models in the file.

The entities in a SAT file may only refer to other entities within the same SAT file. The ASAT format is designed to allow a model in one file to refer to a model or models in a different file or files. This is necessary to allow "atomic" save of an assembly, where each model in the assembly is saved into a different file. This mechanism supports the standard assembly modeling workflow of having a "parts catalog" set of files which are included into other assemblies. The maximum granularity of ASAT files is one file per history stream.

The ASAT format has an explicit mechanism that allows you to bind meta-data (for example, feature names) to asm_model and entity_handle objects. Each object saved to an ASAT file has an associated “sequence number” which is determined by its location within the file. As part of the atomic save process, your application is informed of sequence number information (both in the file being saved and the files containing the associated entities) for the asm_model and entity_handle objects. The intent is that this sequence number information will be used to index meta-data saved in the application segments of the application's save file. During the file restore process, the same sequence number information is presented to the application so that it can use it to restore the binding (in application code) between the meta-data and the object.
This mechanism is especially important when your application allows editing of the contents of atomic ASAT files without having the files' parent assemblies in memory. The mechanism allows you to take responsibility for indicating which objects are the "same" as those to which are being referred by the parent files, after the file has been edited. This process, in turn, allows you to use knowledge not available to ACIS, for example from a feature naming system within your application, in order to maintain the correct associations between objects in different files.

When restoring from SAT, the application performs the following steps:

Creates an application document.
Calls api_restore_entity_list() to read the entities in the part.
Registers the restored entities with the document.

An ASAT file, will generally contain the equivalent of multiple SAT files, which in turn correspond to multiple documents that need to be created (by application code) during the call to asmi_restore_model_list(). This interaction between asmi_restore_model_list() and the application code to create application documents is managed by setting a global entity manager factory object into asmi_restore_model_list() . This factory object creates new entity manager objects as needed by asmi_restore_model_list(), which in turn can create a new application document for each model in the file(s). Note that the global factory can be overridden by passing in an asm_restore_options object which points to a different factory.

When a SAT file is saved with history, it can be read back into an application in two ways:

with history: the history information saved in the file is restored to memory
without history: the history information saved in the file is ignored.

One of the properties of the SAT format is that the result of reading a SAT file without history is the same whether or not history was written to the file. That is, the history section of a SAT file does not change the structure of the non-history portion of the file. When an ASAT file is saved with history, however, the structure of the non-history portion of the file can be different from the structure of the same file saved without history; this occurs if any two of the models being saved share a history stream. When this occurs, the corresponding models created by the restore process are required to share their history streams as well. When the models are saved without history, this history sharing between restored models is not required (because information about the history structure of the models is not saved to the ASAT file in this case).

Table. Differences between Assembly and Part Modeling

Monolithic and Atomic Saves

The ASAT format allows ASAT files to refer to one another, allowing two modes in which an assembly can be saved to ASAT.

Monolithic

All models (and the entities they contain) are saved into a single file. This mode does not require metadata in order to avoid corruption of cross-model references due to editing of individual sub-models (as is possible with the Atomic mode) because all of the models are in the same file. This is the recommended mode for exporting an assembly model from your application into a file which is intended to be read by applications written by other vendors, that is, applications which cannot take advantage of your application’s meta-data.

Atomic

The models in the assembly tree are written to multiple files. This allows multiple assemblies to use the same sub-assembly without requiring that the data for the sub-assembly be replicated in each assembly’s ASAT file. For example, multiple “door” model files could share a single “doorknob” sub-assembly file. This is the recommended mode for persisting assembly models for re-use by your application (assuming that you wish to support such workflows in your application). Note that you MUST define your own file format if you wish to use atomic mode; you must never write atomic mode segments into a file with a “.ASAT” (or “.ASAB”) extension. This is because files with ASAT or ASAB file extensions are intended to be portable across ACIS-based applications.

Because customer metadata (including file and path names for finding the associated files) is an essential part of atomic-mode saves and will not be portable across vendors, such files should have extensions which are specific to the vendor. An exception to this rule exists for part models; these can be written to SAT (rather than ASAT) as part of the atomic save process. Such SAT segments may be placed in a “normal” SAT file. Atomic save and restore is considered “expert” functionality, because it requires you to implement subclasses which manage the relationships (files names and metadata) between different save files. It is recommended that you use monolithic save and restore for your initial experiments with ACIS Assembly Modeling.

Binary and Text Saves

As with SAT, ASAT can be written in both binary and text formats. It is recommended that customers use binary format (ASAB) within their production applications to reduce size and increase performance. Text format (ASAT) should be used when submitting bugs to Spatial, and can be used during debugging of your application.

ASAT Save and Restore Interface Functions

Use the following interface functions to save and restore ASAT files:

asmi_save_model_list() Used to save a list of asm_model objects (and their sub-models) in monolithic mode.

asmi_save_model_atomic() Used to save an asm_model object (and its sub-models) in atomic mode. All customers must write their own subclasses of the asm_save_file and asm_save_file_factory abstract base classes in order to use this routine, along with a subclass of asm_restore_file to read the resulting files. These subclasses must embed the atomic ASAT segments in a proprietary customer file type. A simple default implementation of these subclasses is provided with ACIS so that you can experiment with atomic save and restore during development, but this implementation must not be used by any of your production applications. This default implementation can also be used to submit bugs to Spatial, because Spatial will, in general, not have access to your subclasses.

asmi_restore_model_list() Used to restore an ASAT file. This interface function reads both atomic and monolithic files.

For an in-depth explanation for implementing atomic save and restore, refer to the section Implementing Atomic Save and Restore.

ASAT File Structure

The general structure can be seen by examining an ASAT file in a text editor. The ASAT file is comprised of three sections:

A header containing information about the contents of the file and how it was created.

A set of model segments. Each model segment corresponds to a single asm_model object; a model segment exists for each primary model and for every sub-model of the primary models. Each model segment contains information about the model, information about where the entities contained in the model can be found, and information about the handles owned by the model. Together, these model segments define the assembly tree structure (that is, the asm_model hierarchy) associated with the ASAT file.

A set of entity-data segments. Each segment saves the entities associated with a single history stream (if history is being saved) or with a single model (if history is not being saved). If multiple models share a history stream and history information has been saved, then multiple model segments are associated with a single entity-data segment; if each model has its own history stream (or if history is not being saved), then each entity-data segment is associated with a single model segment.

Part Modeling	Assembly Modeling
`api_save_entity_list()` takes a list of primary entities to save to SAT; the SAT file contains the primary entities, all other savable entities to which they (recursively) point, and, in the case of save-with-history, the history stream containing these entities along with backup copies of all entities in the stream	`asmi_save_model_list()` takes a list of primary models to save to ASAT; the ASAT (or ASAT and SAT, in the case of atomic save) file(s) will contain the primary models, all sub-models of the primary models, and, in the case of save-with-history, any models which could become sub-models of the saved models after a roll operation.
`api_restore_entity_list()` is used to restore a list of entities from a SAT file	`asmi_restore_model_list()` is used to restore a list of models from an ASAT file.
`api_save_entity_list()` takes a pointer to a FILE or FileInterface object representing a file that has been opened and positioned by application code and writes a SAT segment into the file, leaving the file positioned at the end of the SAT segment. This allows customers to embed SAT data as a segment within their own save-file format.	`asmi_save_model_list()` operates in the same way, except that it writes an ASAT segment. This allows customers to embed ASAT data as a segment within their own save-file format.
SAT can be written in text, binary, or other (by customers who define their own FileInterface objects) format.	ASAT can be written in text, binary, or other (by customers who define their own FileInterface objects) format.
SAT files can save history information.	ASAT files can save history information.

Part Modeling	Assembly Modeling
`api_save_entity_list()` saves a list of ENTITY objects.	`asmi_save_model_list()` saves a list of `asm_model` objects.
	An ASAT file has embedded SAT segments which are used to save the ENTITY objects and history streams contained within the models in the file.
The entities in a SAT file may only refer to other entities within the same SAT file.	The ASAT format is designed to allow a model in one file to refer to a model or models in a different file or files. This is necessary to allow "atomic" save of an assembly, where each model in the assembly is saved into a different file. This mechanism supports the standard assembly modeling workflow of having a "parts catalog" set of files which are included into other assemblies. The maximum granularity of ASAT files is one file per history stream.
	The ASAT format has an explicit mechanism that allows you to bind meta-data (for example, feature names) to `asm_model` and `entity_handle` objects. Each object saved to an ASAT file has an associated “sequence number” which is determined by its location within the file. As part of the atomic save process, your application is informed of sequence number information (both in the file being saved and the files containing the associated entities) for the asm_model and entity_handle objects. The intent is that this sequence number information will be used to index meta-data saved in the application segments of the application's save file. During the file restore process, the same sequence number information is presented to the application so that it can use it to restore the binding (in application code) between the meta-data and the object. This mechanism is especially important when your application allows editing of the contents of atomic ASAT files without having the files' parent assemblies in memory. The mechanism allows you to take responsibility for indicating which objects are the "same" as those to which are being referred by the parent files, after the file has been edited. This process, in turn, allows you to use knowledge not available to ACIS, for example from a feature naming system within your application, in order to maintain the correct associations between objects in different files.
When restoring from SAT, the application performs the following steps: Creates an application document. Calls `api_restore_entity_list()` to read the entities in the part. Registers the restored entities with the document.	An ASAT file, will generally contain the equivalent of multiple SAT files, which in turn correspond to multiple documents that need to be created (by application code) during the call to `asmi_restore_model_list()`. This interaction between `asmi_restore_model_list()` and the application code to create application documents is managed by setting a global entity manager factory object into `asmi_restore_model_list()` . This factory object creates new entity manager objects as needed by `asmi_restore_model_list()`, which in turn can create a new application document for each model in the file(s). Note that the global factory can be overridden by passing in an asm_restore_options object which points to a different factory.
When a SAT file is saved with history, it can be read back into an application in two ways: with history: the history information saved in the file is restored to memory without history: the history information saved in the file is ignored. One of the properties of the SAT format is that the result of reading a SAT file without history is the same whether or not history was written to the file. That is, the history section of a SAT file does not change the structure of the non-history portion of the file.	When an ASAT file is saved with history, however, the structure of the non-history portion of the file can be different from the structure of the same file saved without history; this occurs if any two of the models being saved share a history stream. When this occurs, the corresponding models created by the restore process are required to share their history streams as well. When the models are saved without history, this history sharing between restored models is not required (because information about the history structure of the models is not saved to the ASAT file in this case).

An entity data segment contains the following information:

A list of the models which are associated with this entity-data segment.
A SAT segment containing entity and history information.
Information for rebinding the entity handles owned by the associated models with entities in the SAT segment.

The primary difference between a monolithic ASAT file and an atomic ASAT file is that every model segment in a monolithic file is associated with an entity-data segment in the same file. In an atomic file, however, some of the models are associated with entity-data segments in a different file or files.

Related topics:

Assembly Modeling Overview
Assembly Modeling vs Part Modeling
Basic Concepts in Assembly Modeling
Assembly Modeling Tutorial
Properties in Assembly Modeling
Standard Workflows in Assembly Modeling
Assembly Modeling Limitations

[Top]

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

`asmi_save_model_list()`	Used to save a list of `asm_model` objects (and their sub-models) in monolithic mode.
`asmi_save_model_atomic()`	Used to save an `asm_model` object (and its sub-models) in atomic mode. All customers must write their own subclasses of the asm_save_file and asm_save_file_factory abstract base classes in order to use this routine, along with a subclass of asm_restore_file to read the resulting files. These subclasses must embed the atomic ASAT segments in a proprietary customer file type. A simple default implementation of these subclasses is provided with ACIS so that you can experiment with atomic save and restore during development, but this implementation must not be used by any of your production applications. This default implementation can also be used to submit bugs to Spatial, because Spatial will, in general, not have access to your subclasses.
`asmi_restore_model_list()`	Used to restore an ASAT file. This interface function reads both atomic and monolithic files.