By scalar members, we mean members which have a single value - in other words not collections.  For each member of the object classes in your definition file, Persistate generates a property, and most often a private field to go with it.  All members must have an associated persistent class, which can be either an object class, data class or view class.  The type of the generated property will be set by the persistent class of the member.

Accessing Data Members

Accessing members with a data class is straightforward.  These translate usually into value types, though there are some exceptions, as some Persistate data classes correspond to .Net reference types such as String, Font, Image.  When Persistate retrieves an object from persistent storage, it puts the data member values into the private fields.  Subsequently, you retrieve their values using the corresponding property get accessor.  Of course, within the target class containing the property, you can access the private field directly if you wish.  The following example shows use of both the get and set accessors for the Title property of a Publication object.

if (myPublication.Title.Length == 0)
   myPublication.Title = suppliedTitle;

Accessing Scalar Object Members

Accessing scalar members with an object class is also just a simple matter of using the generated property, but in this case what happens is a bit more complicated.  Object members are also stored in a private field, but the type of this field is IReference – a Persistate interface type.  This is implemented by both Reference and Persistent. Reference holds what amounts to a database address, which can address a single persistent object within an address space comprised of all the databases in your Persistate domain. Persistent is the base class of all persistent objects.

When Persistate retrieves an object from persistent storage, any member IReference fields are filled with References.  When you access that member via the property get accessor, Persistate checks to see whether the field is still a Reference.  If so, it retrieves the addressed object from persistent storage, puts it in the field and returns it.  Obviously, this only happens the first time the member property is accessed.  Although the private field is an IReference, the property has the appropriate class, so you don’t have to do any casting.

You can see from the following example that accessing and setting object members is as simple as for data members.  On the first line below, Persistate retrieves any existing author linked to the newBook object.  If there was none, Persistate sets the private field to null, and that is what is returned.  On the second line, the code sets the new author of the book, simply by assigning it to the property, and similarly on the third line, the book's genre.  Persistate takes care of all the necessary creation and linking of database keys.

if (newBook.Author == null) 
   newBook.Author = suppliedAuthor;
newBook.Genre = The.Library.Genres[suppliedGenreName]
return newBook.Author.FullName;

An obvious question is, how do these changes get from here into persistent storage?  The answer is that it is handled by Persistate without any further intervention by the developer.  In the property set accessor code, Persistate remembers which objects are changed, and which have been attached to or removed from the persistent tree.  An the end of the current operation execution (or on demand), all changes are sent to persistent storage, under control of a transaction.

Persistate handles all the necessary assigning of primary keys, index creation and maintenance, and appropriate linkages between objects.  As the developer, all you need be concerned with is that the next time you access the newBook object and you write newBook.Author, this gives you the same object that you set into it previously.

You can see from the above that Persistate holds the Author object in the newBook field.  But any number of books can have the same author (it is an associated member), so does that mean that you can have more than one object in memory for the same persistent object.  In this case the answer is no, because the Author class is in the stable category, which uses the cache.  See The Persistate cache for more details.