Maintaining reversible properties through the code files (ACS)
ACS supports the changing of the selected properties (reversible properties) in either the model or the generated code files. Examples of these reversible properties are as follows:
• Operation Body text — In Modeler this text is specified on the Body tab of an Operation's Property Pages (all Code Generator DLLs).
• Event Action Block Guard Condition text — In Modeler this text is specified on the Options tab of an Event Action Block's Property Pages (C and C++ only).
• Event Action Block Action text — In Modeler this text is specified on the Options tab of an Event Action Block's Property Pages (C and C++ only).
• Ada Declaration text — In Modeler this text is specified on the Ada Declaration tab of an Operation's Property Pages having applied the «Ada Declaration» stereotype to the Operation (Ada only).
• C# Add Accessor Body text — In Modeler this text is the tagged value of the C#Add Accessor Body tag definition (C# only).
• C# Get Accessor Body text — In Modeler this text is the tagged value of the C#Get Accessor Body tag definition (C# only).
• C# Remove Accessor Body text – In Modeler this text is the tagged value of the C#Remove Accessor Body tag definition (C# only).
• C# Set Accessor Body text – In Modeler this text is the tagged value of the C#Set Accessor Body tag definition (C# only).
• VB Declare text — In Modeler this text is the tagged value of the VB Declare tag definition, which can be applied to a Class, Data Type or Interface through the «VB Class» stereotype (VB only).
• VB GetAccessorBody text — In Modeler this text is the tagged value of the VB GetAccessorBody tag definition, which can be applied to an Attribute or Role through the «VB Property» stereotype (VB only).
• VB Imports text - In Modeler this text is the tagged value of the VB Imports tag definition, which can be applied to a Class, Data Type, Interface or Package through the «VB Unit» stereotype (VB only).
• VB SetAccessorBody text - In Modeler this text is the tagged value of the VB SetAccessorBody tag definition, which can be applied to an Attribute or Role through the «VB Property» stereotype (VB only).
This solution provides the benefit of maintaining operation bodies and other reversible properties in your code environment; however, there can be complications when working with Modeler access permissions, Repository-based CM and CM tool integration.
In this scenario, you are the only user of the model or model version, so you can enable reverse engineering and enable reverse on startup.
You make all changes to reversible properties through marked text in the code files.
In a multi-user model, enabling reverse on startup will overwrite other user’s changes to reversible properties when you start ACS.
Set up the following options in ACS:
• Generate enabled — so that changes in the model are generated.
• Reverse enabled — so that when ACS is running, changes you make to reversible properties in your code files are reverse engineered to the model.
• Reverse on Startup enabled — so that when you start ACS with the model, changes you have made to marked text in your code files while ACS was not running are reverse engineered to the model.
• Generate on Startup enabled — so that when you start ACS with a model, any changes you have made to the model are generated. In addition, forcing a generation deletes redundant code files.
While ACS is running, ACS detects any changes you make to marked text in the code files and reverse engineers those changes to the model.
While ACS is not running, you can still make changes to marked text in the code files.
When you start ACS, ACS compares reversible properties in the model with its associated marked text in the code files. If ACS detects a difference, ACS reverse engineers the marked text to the model. After reverse engineering all the changed marked text, ACS generates packages and classes that require generating because of changes in the model.
If the Generate on Startup check box is selected and you disable generation through the Enable or Disable Code Generation toolbar button, ACS clears the Generate on Startup check box. Likewise, if the Reverse on Startup check box is selected and you disable reverse engineering through the Enable or Disable Reverse Engineering toolbar button, ACS clears the Reverse on Startup check box.
• When ACS reverse engineers changed marked text to the model, you may not see that change in Modeler until you refresh the Modeler views.
• Remember that ACS reverse engineers only operation bodies, EAB guard condition text, EAB action text and Ada declaration text - do not change anything outside of the ACS markers in your code files.
• If you use an add-in that makes changes to reversible properties in the model, ACS must be running. After the add-in updates the reversible properties in the model, perform a refresh in Modeler so that the changed text is generated. If ACS is not running, on startup ACS will overwrite the reversible properties changes in the model with the now out-of-date marked text from the code files.
When ACS cannot reverse engineer a reversible property
A problem can arise if ACS cannot reverse engineer marked text changes from a code file:
• Access Permissions — If you change marked text in a code file but do not have write access permissions to its associated property in the model, ACS cannot reverse engineer the change.
• CM Tool Integration — If you change marked text in a code file and the Package that owns the associated item in the model is not checked out, ACS cannot reverse engineer the change.
If ACS cannot reverse engineer marked text changes in a code file, the ACS log records the fact. In the following example, the log shows that a change to the operation body of the MyOperation operation cannot be reverse engineered.
• Interface to Modeler - Error while calling PropertySet operation on object Operation: MyOperation [Package1.MyClass.]
Operation on Operation Package1::MyClass.MyOperation cannot be performed
OPERATION: Set Property
TYPE: TOKENTEXT
REASON: Operation Package1::MyClass.MyOperation is protected.
Reversed property committed to local cache
When ACS cannot reverse engineer changed marked text to the model, ACS reverse engineers the changed text to a cache file for the model, that is, the PRP file. While there is a change that has not been reverse engineered, ACS does not overwrite the marked text in the code file, even if the associated reversible property in the model is changed. This allows you to resolve the problem:
• If possible, make the item that owns the property in the model writable, and then force a reverse - ACS will then reverse engineer the marked text from the code file
• If you cannot make the item that owns the property in the model writable - ACS attempts to reverse engineer the marked text each time a reverse engineering operation is forced.
If you delete the SHM and PRP files associated with a model version, ACS stops attempting to reverse engineer the marked text that has not been reverse engineered, and stops protecting the marked text in the code file from being overwritten. ACS generation and reverse engineering settings then determine how the text differences are resolved.
You can determine if there are any unreversed text changes by clicking the Show Protected Properties button on the ACS/TDK Control toolbar. The ACS/TDK Pane records whether there are any unreserved changes.
Working with Access Permissions
Change marked text in the code files only if you have write access to its associated reversible property in the model.
If you change marked text in a code file but do not have write permissions to the item that owns the associated reversible property in the model, ACS cannot reverse engineer the change:
• If you can get write access permissions to the item in the model, get write access permissions, and then force a reverse from ACS.
• If you cannot get write access permissions to the item in the model, ACS will continue to attempt to reverse engineer the change.
Working with Repository-based CM
If you are maintaining reversible properties through the code files, you must disable reverse in ACS before rebasing the branch.
You must disable reverse before rebasing a branch. If you do not disable reverse in ACS before rebasing a branch, when you start ACS with the new model version, other users' updates to reversible properties will be overwritten with marked text from your code files - on reconciling the branch, the other users' updates to the reversible properties in the model will be removed from the trunk.
• When ACS is set up to work with a model version, it checks to see if there are any SHM or PRP files for the previous version of the model. If there are previous versions of the SHM and PRP files, ACS bases the new SHM and PRP files on the SHM and PRP files created for the previous version of the model - this ensures that any unreversed changes are not lost.
• If you are maintaining reversible properties in the model, you can rebase a branch with no problems.
Working with Modeler CM tool integration
Ensure that ACS is running before performing any check in, check out or get latest operations on a package:
• If you perform a check out operation in Modeler while ACS is not running, you will lose other user’s changes to reversible properties when ACS is started with the model.
• If you accidentally perform a check out operation while ACS is not running, undo the check out operation, start ACS with the model, and then repeat the check out operation.
Before changing marked text in a code file, ensure that you can change the item that owns its associated reversible property in the model, that is, you have appropriate access permissions and it is checked out.
If you accidentally change reversible properties in a code file and ACS reports that it cannot set the property in the model because the item is not checked out, ensure that ACS is running and check out the Package.
Working with code files under source code control
If you are using a CM tool only to back up your code files, always leave all the code files checked out.
If you are using Modeler replicas with code files that are under source code control, we consider it too risky to maintain reversible properties through the code files. This is because there are too many opportunities for reversible properties to become out-of-sync, which can result in lost changes. If your code files must be under source code control, maintain reversible properties in the model.
• If you using a multi-user model and want to maintain reversible properties through your code files, you must be very careful because there is a risk of other user’s changes in the model being overwritten with your out-of-date code files.
• Ensure that your model is being regularly backed up, so that you can recover lost data from the Model.
• It is very risky to enable reverse on startup when working with a multi-user model - on starting ACS, if another user has updated reversible properties that your ACS can reverse engineer, ACS will overwrite the other user’s changes with the out-of-date marked text in your code files. For the same reason, you must be very careful when forcing a reverse.
In a multi-user model, you can prevent ACS from generating other users' changes to your code files by setting up ACS to work with a specific Package - ACS will then only generate model items from that Package and its sub-Packages. ACS will only reverse engineer marked text from the code files associated with the selected Package and its sub-Packages. If you want to update your code files with other user’s changes, disable reverse(else ACS will overwrite other user’s changes from your out-of-date code files), set up ACS to work with the model, force a generation, set up ACS to work with your Package again, and then enable reverse.
If the model items you want to change are distributed across many Packages, make the code files you are working with editable, and all other code files read-only. Set up ACS to work with the model and only your changes will be generated because ACS will not be able to generate other user’s changes to your read-only code files. ACS will reverse engineer the changes you make to your editable code files. If you want to update your code files with other user’s changes, disable reverse(else ACS will overwrite other user’s changes from your out-of-date code files), make the code files you want to update editable, force a generation, make the code files you are not using read-only again, and then enable reverse.
When using the preceding methods to work with a subset of a multi-user Model, you can use Modeler access permissions to prevent other user’s from updating your Packages in Modeler, and prevent you from accidentally updating other user’s Packages.
Show Protected Properties button on the ACS/TDK Control toolbar. The ACS/TDK Pane records whether there are any unreserved changes.