The sheet set API is a multiclient API. This means that multiple clients may be viewing and interacting with a given AcSmDatabase at any given time. This requires special attention as to how objects are referenced or modified in the database.
In order to make modifications to any object within the AcSmDatabase, you must lock it and then unlock it when you are finished making changes. You should only lock the database when you are ready to make changes, and you should unlock it as soon as possible. For performance reasons, you should also lock and unlock the database as few times as possible. If you need to make several modifications, lock the database, make all your changes, and then unlock it.
Because the database has multiple clients, it will be automatically reloaded from time to time as other clients make changes. When the database gets reloaded, all contained object instances are discarded and new instances are created as the database is read in.
For this reason, it is important to adhere to the following basic rule when referencing objects that reside within a sheet set database:
- Never cache direct pointers to objects within a sheet set database. If you must cache a reference to an object within a sheet set database, store the associated IAcSmObjectId instead. With an object ID, you can safely retrieve a pointer to the associated object instance; the current instance is always retrieved.
After a database is reloaded, a pointer to a database-resident object will be invalid. However, if you store the object ID instead, you can use it to safely retrieve a pointer to the current object instance.
The only exception to this rule is the database. You can store a pointer to the AcSmDatabase because the database object is not destroyed and recreated during a reload operation.
You can retrieve the object ID of any database-resident object by calling the GetObjectId method on the object. Conversely, you can get the associated object instance from an ID by calling the GetPeristentObject method. This returns a general IAcSmPersist interface pointer, which can be queried for the desired interface.
Note: DST files should only be modified using Sheet Set Manager objects.