Visual Basic Concepts

Persisting a Component's Data

Most components have properties; in most cases you'll want to establish default values for those properties in the Initialize event of the class. Those default values are frozen when you compile the component, so how do you allow a developer to change the default values to meet their own special conditions? Classes have a special property, Persistable, that allow you to store a component's values between instances.

Suppose that you had an ActiveX DLL that calculates loans, with an InterestRate property used in the calculations. You could initialize the InterestRate to some arbitrary value, but since interest rates periodically go up or down, the InterestRate property would need to be modified each time the component is run. With class persistence, you can store the InterestRate value and modify it only when the interest rate changes. Each time your component is run it can retrieve the InterestRate from storage, so the component will always provide the latest rate.

While ActiveX controls have always been able to persist their data; persistence for ActiveX components is slightly different. A control stores property settings inside it's .cls file, but a component can't do that. Instead, it uses a PropertyBag object that can be saved just about anywhere – in a file, a database, a cell in a spreadsheet, or even in the registry.

For More Information*   To learn more about persisting ActiveX controls, see "Saving the Properties of a Control," in "Building an ActiveX Control"*.

Setting Up Class Persistence

In order to be persistable, a class must meet two conditions: it must be public and creatable. If you think about, this makes sense – after all, persistence wouldn't be useful in a private component. If a class meets both conditions, the Persistable property appears in the Properties window.

By default, the Persistable property is set to 0 (NotPersistable). By changing this value to 1 (Persistable), three new events are added to the class: ReadProperties, WriteProperties, and InitProperties. As you might guess, these events are use to read, write, and initialize the class's properties.

Persisting a Property

You can mark a property as persistable by implementing the PropertyChanged method in a Property Let or Property Set procedure, as in the following example:

Private mInterestRate As Single
Public Property Let InterestRate(newRate As Single)
   mInterestRate = newRate
   PropertyChanged "InterestRate"
End Sub

Calling the PropertyChanged method marks the InterestRate property as dirty. The WriteProperties event will fire when the class is terminated if any property in the class has called PropertyChanged.

The ReadProperties, WriteProperties and InitProperties Events

The WriteProperties event procedure is used when a class is terminating to write the current property values to a private storage known as a PropertyBag object. The following code is used to save a property to the built-in PropertyBag:

Private Sub Class_WriteProperties(PropBag As PropertyBag)
   PropBag.WriteProperty "InterestRate", mInterestRate, conDefaultRate
End Sub

The Property Bag's WriteProperty method in the above code takes three arguments: the name of the property to save ("InterestRate"), the value to save (mInterestRate), and a default value (DefaultRate). If the new value matches the constant conDefaultRate, the WriteProperty method doesn't have to write out the value.

The ReadProperties event is fired when a class is initialized – but only if the PropertyBag has something in it. If the PropertyBag is empty, the InitProperties event will be fired instead. Code in the ReadProperties and InitProperties events is used to set the initial property values:

Private Sub Class_ReadProperties(PropBag As PropertyBag)
   mInterestRate = PropBag.ReadProperty("InterestRate", conDefaultRate)
End Sub
Private Sub Class_InitProperties ()
   mInterestRate = conDefaultRate
End Sub

Note that the constant conDefaultRate is used in both procedures to provide a default value. By using a constant to define the default values you eliminate the risk of accidentally defining different default values in different procedures.

When you first create an instance of the Loan class using the New keyword, the InitProperties event will be fired; once the class has been persisted and is then recreated, the ReadProperties event will be fired instead.

Using the PropertyBag Object to Persist an Object

In order to persist an ActiveX component, you need to create an instance of a PropertyBag object. This may seem redundant — after all, the class already has it's own PropertyBag. Why can't you just use that? Simple. When the object goes away, so does its PropertyBag. It only exists in memory; for persistence you need to store a copy of the object somewhere so you can retrieve it later.

Think of a PropertyBag as a sack that you can fill up with stuff and stash away somewhere for safe keeping. Where you stash it is entirely up to you. The following form code demonstrates how you can persist an object to a text file:

Private pb As PropertyBag      ' Declare a PropertyBag object.
Private LoanObject As Loan      ' Declare a Loan object.

Private Sub Form_Unload(Cancel As Integer)
   Dim varTemp as Variant

   ' Instantiate the PropertyBag object.
   Set pb = New PropertyBag
   ' Save the object to the PropertyBag using WriteProperty.
   pb.WriteProperty "MyLoanObject", LoanObject
   ' Assign the Contents of the PropertyBag to a Variant.
   varTemp = pb.Contents
   ' Save to a text file.
   Open "C:\Loandata.txt" For Binary As #1
   Put #1, , varTemp
   Close #1
End Sub

The Contents property of the PropertyBag object contains the Loan object stored as an array of bytes. In order to save it to a text file, you first must convert it to a data type that a text file understands — in this case, a Variant.

Depersisting An Object

Once the object is contained inside a text file (or any other type of storage), it can easily be transported to another location. Imagine that our Loan object contains not only the InterestRate, but also property values to represent all of the fields in a loan application. You could take the Loandata.txt file and send it to the central office for approval. The code for a form that would reuse the Loan object would look something like this:

Private pb As PropertyBag      ' Declare a PropertyBag object.
Private LoanObject As Loan      ' Declare a Loan object.

Private Sub Form_Load()
   Dim varTemp As Variant
   Dim byteArr() as Byte

   ' Instantiate the PropertyBag object.
   Set pb = New PropertyBag
   ' Read the file contents into a Variant.
   Open "C:\Loandata.txt" For Binary As #1
   Get #1, , varTemp
   Close #1
   ' Assign the Variant to a Byte array.
   ByteArr = varTemp
   ' Assign to the PropertyBag Contents property.
   Pb.Contents  = ByteArr
   ' Instantiate the object from the PropertyBag
   Set LoanObject = pb.ReadProperty("MyLoanObject")
End If

You may have noticed that the object had to be assigned three times: first from the text file to a Variant, then from a Variant to a Byte array, then to the Contents property. That's because the Contents property will only accept a Byte array — if you tried to assign any other data type you would get an error.

So what's going on here? Can you actually take an object created in one place and reuse it in another, complete with its data? Well, not exactly. The original object is long gone. What you are passing in a PropertyBag is an exact copy of the object, not the object itself. This ability to "clone" an object for reuse is a powerful concept, especially when it comes to designing workflow applications.