Preserving LabVIEW Class Data

LabVIEW classes define a data type. When you run a VI, many instances of the class are created, moving around on wires from controls to nodes and into indicators. LabVIEW preserves those data instances when you flatten a LabVIEW class value to a string or when you set it as the default value of a control, indicator, or block diagram constant.

When you save that data, you likely plan to unflatten the data at a later time. One issue is that edits to the LabVIEW class might change the data type of the class, making it impossible to recover the data. This is a problem in programming–the programmer changes the data definition and a complex load routine must be written to mutate old data to the new format. The programmer faces a choice of finding some way to distinguish old data from new data so that the mutation routine can be run on-the-fly or of doing a one-time pass over the data to convert it all and hope that he or she did  not miss any values along the way.

LabVIEW, as a graphical programming environment, has an advantage over other programming languages. When you edit the class, LabVIEW records the edits that you make. LabVIEW is context aware as you change inheritance, rename classes, and modify private data clusters. This allows LabVIEW to create the mutation routine for you. LabVIEW records the version number of the data as part of the flattened data, so that when LabVIEW unflattens the data, LabVIEW knows how to mutate it into the current version of the class.

Three types of relationships might exist between a pair of classes:

1. Inheritance— One class inherits from another, effectively using the other class as a starting point for its own definition.
   Terminology—Parent and Child; extended as Ancestor and Descendant
2. Containment —One class uses another as an element in its private data cluster.
   Terminology—Container and Contained
3. Ownership—One class owns another, just as project libraries (.lvlib ) can own sublibraries. This relationship is not supported in the current version of LabVIEW. Libraries can own classes, but classes cannot own other classes.
   Terminology—Owner and Owned

Note—The following discussion assumes that when you edit Alpha, all of its current ancestor classes, if any, are in memory and not broken. If you make edits to Alpha when its parent class is not in memory or is broken, LabVIEW tries to preserve as much as possible, but depending upon exactly what is broken that may not be possible.

Editing the Private Data Control of Alpha

The following are effects on Alpha itself:

• Any edit that changes the data type of the private data cluster bumps the version number of Alpha.
• Classes preserve data much better than typedefs because classes can record version numbers in the typedef data and thus know exactly how to handle the data. When editing the private data cluster, all data from previous versions of Alpha will still be unflattenable, though it will be mutated according to the following rules:
  • If you add an element to the cluster, LabVIEW adds the element to all data instances of the class type using the default value you set for that element of the cluster.
  • If you remove an element from the cluster, LabVIEW removes the element from all data instances of the class type.
  • If you right-click and select Replace or use any other method of changing the type of the control itself (such as setting the Representation on a numeric), LabVIEW preserves the data if possible. If the old type is convertible to the new type, then LabVIEW preserves the data in all data instances of the class. Otherwise, LabVIEW sets the the element to the default value of the element in the cluster. This is important—deleting an element from the cluster and adding a new element has a different effect on data instances than using Replace to substitute the element. Delete+Add adds the new element with default value for the element. Replace preserves the value of the previous element in the new element.
  • If you reorder elements in the cluster, LabVIEW reorders data instances accordingly.
  • If an element of the private data cluster is a typedef and you edit that typedef, LabVIEW preserves that element in data instances of the class only if the old and new types of the typedef are convertible, otherwise the value will be the default-default value of the typedef.
  • Disconnecting a control from its typedef has no effect on the data.
• Changing the default value of any elements of the private data cluster bumps the version number of Alpha. When LabVIEW unflattens data instances of previous versions of the class, cluster elements do not take on the new default value unless the entire cluster had the default value of the class when LabVIEW flattened it.

Effects on VIs with controls/indicators/constants of Alpha:

• Whether the VI was in memory or not, LabVIEW preserves all data instances of Alpha in default/operate/constant values according to the rules above.

Effects on descendants of Alpha:

• Whether the descendants were in memory or not, descendant classes do not change their version numbers. They can still unflatten all versions of their own data. LabVIEW mutates the section of data inherited from the parent according to the rules above.

Effects on containers of Alpha:

• Whether the containers were in memory or not, classes that use the edited LabVIEW class do not bump their version numbers. LabVIEW mutates the data in the Alpha element according to the rules above.

Renaming Alpha

Note—The following are different ways to rename a LabVIEW class:

1. Save the class for the first time will change the class name from its given untitled name to the file name.
2. Using Save As»Rename to change the file name.
3. Moving the class into or out of an owning project library.
4. Renaming an owning project library.
5. Renaming the .lvclass file on disk outside of LabVIEW.

The following effects are true for the first 4 rename mechanisms. The effects of renaming the .lvclass file outside of LabVIEW are described later.

Effects on Alpha itself:

• Sets the version number of Alpha to 1.0.0.0.
• Cannot unflatten any data that was flattened as the old name of the class.

Effects on VIs with controls/indicators/constants of Alpha:

• If the VI was not in memory when you renamed the class, the VI loads broken unless it can find a class of the old name. If it does find a class of the old name, LabVIEW unflattens the values according to the rules of the found class. If LabVIEW cannot unflatten the data by the found class, the LabVIEW changes the values to the default-default value of the found class and reports a load warning.
• If the VI was in memory when you renamed Alpha, LabVIEW updates all controls/indicators/constants to the new name and they retain their default/operate/constant values.

Effects on descendants of Alpha:

• Any direct child of Alpha that was not in memory when you renamed Alpha loads broken unless it can find another class of the old name.
• Any direct child of Alpha that was in memory when you renamed when Alpha bumps its version number. Such classes will still be able to unflatten all data of earlier versions without difficulty.
• Any descendant classes below the direct children do not bump their version numbers whether they were in memory or not. They will be able to unflatten data if the child of Alpha that they descend from was in memory.

Effects on containers of Alpha:

• Any class that was not in memory when you renamed Alpha loads broken unless it can find another class of the old name.
• Any class that was in memory when you renamed the member class bumps its version number. Such classes will not be able to unflatten data of earlier versions. However, all values that are in memory at the time of the rename – in default/operate/constant values of controls/indicators/constants – will be preserved.

Changing the Filename of Alpha on Disk

Effects on Alpha itself:

• When Alpha loads into memory, it will notice that the filename it now has is not the same as the filename it had when it saved. It will change its version number to 1.0.0.0 and will forget its previous names.

Effects on all other LabVIEW classes and VIs:

• They will behave as they would for any of the other rename mechanisms as if they were not in memory at the time of the rename.

Changing Alpha to Inherit from a Different Parent Class

Effects on Alpha itself:

• Bumps the version number of Alpha.
• Data from all previous versions are still loadable using the following rules:
  • If the new parent is a descendant of the old parent, then levels of hierarchy have been added. In data instances, LabVIEW preserves all existing levels of hierarchy. LabVIEW initializes the added levels of hierarchy with the default values for the new intervening classes.
  • If the new parent is an ancestor of the old parent, then LabVIEW removes levels of hierarchy. The data from those levels that are no longer used will be discarded. LabVIEW preserves all other levels.
  • If the old and new parents do not have some sort of ancestor-descendant relationship, then LabVIEW finds the common ancestor to both. LabVIEW preserves all data from the common ancestor and earlier ancestors. All data from Alpha and its descendants will be preserved. The old hierarchy levels between Alpha and the common ancestor will be discarded and the new levels between Alpha and the common ancestor will be initialized with the class’ default values. So, for example, if Alpha version 1 is
                Alpha –inherits from Parent –inherits fromGrandparent
    and in version 2 it changes its inheritance to be
                Alpha –inherits from Other –inherits fromGrandparent
    Then when unflattening data of Alpha version 1, the Alpha level data will be preserved, the Grandparent level data will be preserved. The Parent level data will be discarded and the Other level data will be initialized with Other’s default value. There is no operation in LabVIEW to replace one level of a hierarchy with another. We never attempt to preserve data from an old parent in a new parent.

Effects on VIs with controls/indicators/constants of Alpha:

• Whether the VI was in memory or not, LabVIEW preserves all data instances of Alpha in default/operate/constant values according to the rules above.

Effects on descendants of Alpha:

• Whether the descendants were in memory or not, the descendants do not bump their version numbers. Data instances will have the part of the data cluster that is inherited from Alpha modified according to the rules above.

Effects on containers of Alpha:

• Whether the containers were in memory or not, container classes does not bump their version numbers. Data instances will have the Alpha element in their cluster modified according to the rules above.

Manually Changing the Library Version Number of Alpha

Effects on Alpha itself:

• Manually changing the version number of Alpha, using the Class Properties dialog box, should not affect any data at all. The classes should be able to unflatten data of all previous versions without issue. Note that LabVIEW only allows the version of classes to be increased, never decreased. If you open the .lvclass file in a text editor and manually change the version number, the class forgets all of its mutation records and will be unable to load earlier versions of the data. This occurs because although the class version was changed, the private data control may not have the same data type as it had when the class last had the edited version. To prevent this and other odd collisions, the mutation history is simply removed when LV detects that the version number has been edited outside of LabVIEW. Data that was flattened using the edited version number will be able to unflatten only if it turns out to be compatible with Alpha’s current private data cluster type.

Effects on all VIs and all related classes:

• If Alpha is able to unflatten data, as described above, then descendants and containers will be able to unflatten as well and data in VIs will be preserved. If Alpha is not able to unflatten, then descendants and containers will not be able to unflatten, and any VI that stores values of Alpha or any related class will have those values reverted to the class’ default value.

CONCLUSION

LabVIEW currently does not provide tools for manipulating the mutation histories of LabVIEW classes, allowing you to customize the mutations between records and compenstaing for unintended mutations.

At this time the only edit that users can do directly on the mutation history is to remove the mutation history entirely. This removes the ability of the class to load any previous version of itself. This can be done by renaming the class once and then renaming it back to its original name while no other class is in memory. Another option is to open the .lvclass file in a text editor. Search for this text:

<Property Name="NI.LVClass.Geneology" Type= "Xml">< /SPAN>

From there, search for this text:

            </Property>

Delete all text between those two points (including the two found pieces of text themselves). This will wipe out the mutation history. It will be recreated the next time you load and modify the class. Once you remove the mutation history, if you attempt to unflatten data of older types, you will get a Class Version Not Supported error. Any VI that loads that was saved using old versions of data will use the default value of the class for all of its controls, indicators and constants.