Home > User Guide > Implementing ACIS Assembly Modeling in Applications
Implementing Atomic Save and Restore
There are three abstract base classes that you need to subclass in order to integrate atomic save and restore into your application. The basic strategy in the atomic save and restore process is to embed identifying information in the saved files which are then passed back to your application via a "lookup" call during the restore process. If an object corresponding to the information has already been instantiated, "lookup" (written by you) is responsible for returning a pointer to that object. If an object has not been instantiated, then "lookup" returns a NULL pointer, which causes ACIS to instantiate an object and inform your application of the new object by calling a "register" method (also written by you).
Subclasses
The subclasses and their responsibilities include: asm_save_file, asm_save_file_factory, and asm_restore_file
asm_save_file
As part of the save process, every model being saved into an atomic ASAT file is associated with an asm_save_file object. Subclasses of this class have the following responsibilities (enumerated by the names of the corresponding virtual function that you will need to override).
Responsibilities
get_file_data_vf
This function returns an asm_file_data object that contains information describing the save file. This information will be embedded in other atomic files which refer to the file, and used during the restore process to generate and lookup asm_restore_file objects. This information includes the name of the save file, an integer ID number which you can use as an index within the save file, whether the file format is text or binary, and what mode the file was saved in.
There are three such modes:
ASM_MONOLITHIC a monolithic asat file ASM_ATOMIC_ASAT an atomic asat file ASM_ATOMIC_SAT a SAT file containing the entities owned by a part model. This mode can only be returned by asm_save_files associated with part models, because SAT files cannot contain assembly information. get_additional_models_in_atomic_file_vf
This method allows you to specify additional models whose entity segments will be saved in this file. It is very important than the models' entity segments be partitioned among the save files in such a way that each model's entity segment appears in one and only one save file.
The easiest way for you to obey this rule is to save one model per atomic file. The only time this cannot be done is when you are saving with history and you have configured your application so that multiple models share a single stream; in this case, all models which share the stream must go into a single file.
open_vf
Opens the file for writing and returns a FileInterface pointer positioned at the location that you want the ASAT information to be written. One of the input parameters of this function is an asm_seq_number_mgr object. This object allows you to query for which models and entity handles are saved in the file's model segments and to query for the identifying information which will be saved to the file. This information is provided as part of "open" so that you can write your meta-data before the ASAT data is written (which means it can be read in by your application before the ASAT data during restore). Note that if this save file is of type ASM_MONOLITHIC_SAT, then you should not use this opportunity to write meta-data concerning the entities in the file; SAT has no entity handles and the ENTITY sequence numbers are not determined until after the SAT information has been written (refer to post_save_vf below).
Your implementation of this function will probably very similar to your function which opens a file in preparation for writing to SAT, with the addition of first writing your meta-data at the beginning of the file.
post_save_vf
This function is called after the ASAT data has been written (but before close_vf) and takes an asm_seq_number_mgr as an input parameter. This function allows you to write meta-data after the ASAT segment, rather than before. This routine is needed if you are writing your part models as SAT rather than as ASAT; it has information about the sequence numbers of the ENTITYs within the SAT file, because it is called after they have been written out.
If you are saving all modes as ASAT (both part and assembly), then there is no need to override this method.
close_vf
Closes the file.
asm_save_file_factory
This class is responsible for instantiating asm_save_files as needed. Its primary responsibility is encapsulated in the method get_file_vf, which, given an asm_model pointer, must return a pointer to the asm_save_file in which the model's entity segment is saved.
It also has prepare_for_save_vf and done_saving_vf methods which permit your application to do bookkeeping tasks before and after the actual save.
asm_restore_file
This class is the heart of the atomic restore process. As with atomic save, each model being restored is associated with an asm_restore_file.
Responsibilities
Acting as a Factory Object for Instatiation of Further asm_restore_files
If a model segment for which no asm_model object has been instantiated while reading a file, ACIS instantiates an asm_model object and registers it with your application by calling the register_model_vf method on the asm_restore_file object being read. The register_model_vf method is responsible for returning a pointer to the asm_restore_file object which contains that model’s entity segments. This may mean passing back a pointer to an existing asm_restore_file object (if another model has already been registered whose entities were saved to the same file) or instantiating a new asm_restore_file object.
Providing "lookup" Methods for Associating Models and Entity Handles from Different Files
Most importantly, the same asm_model or entity_handle object can and will be referred to (that is, written out) in multiple atomic files. Whenever an entity handle or model is read back in from a file, the customer application must inform ACIS whether it refers to an entity_handle or asm_model object which has already been created as a result of reading a previous file, or whether it is a “new” object that is being read for the first time. The lookup_model_vf and lookup_entity_handle_vf methods fulfill this role; they are responsible for examining the sequence number information passed in and determining if the object being referred to is the “same” as a previously registered object.
Providing "register" Methods for Cataloging Entity Handles and Model Objects
The class also provides "register" methods for cataloging entity handles and model objects which have been read in so that "lookup" can be performed.
Opening and Closing the Restore File
Includes the responsibility for opening and closing the restore file.
Notifying Customer Applications of Problems which Arise During Atomic Restore
The model_missing_from_this_file_vf method will be called by ACIS when a model’s entity segment fails to restore. This will usually happen if the file in question cannot be found (due to, for example, filename or path problems) or if the model’s entities are not actually present in the file (due to, for example, editing of the file).
Deleting Itself
Deletes itself, if necessary, when the restore is done. This is signaled by a call to done_restoring_vf.
Summary
In both atomic save and restore, you should notify ACIS of the subclasses to be used through the options object. For save, the asm_save_options object has a pointer to an asm_save_file_factory; for restore, the asm_restore_options object has a pointer to an asm_restore_file. In both cases, if a NULL pointer is passed in, the default ACIS implementation of these subclasses is used.
As stated earlier, asm_save_model_atomic should never be called in your production application with a NULL asm_save_file_factory pointer, as this would result in atomic files with an ".ASAT" extension being written.
Related topics:
Entity Managers in Assembly Modeling
Assembly Modeling Macros and Notification Mechanisms
History and Roll in Assembly Modeling[Top]
© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.