Special-Purpose Objects for Data Storage and Retrieval

Using Special-Purpose Data Storage Objects

A VBO becomes permanent only when it is written to a soup entry, and its associated
binary data always resides on the same store as the entry. Thus, when creating a
VBO, it's usually best to specify that it use the same store as the soup entry into
which you'll save the VBO. If you try to put the same VBO in two different soup
entries, a duplicate VBO is created, even if both entries reside on the same store.

It is recommended that you enclose in a

try

block any code that writes VBO data.

Store memory for VBO data is not allocated when the VBO is created; rather, it is
allocated as needed to write VBO data. Thus, when writing an entry containing a
VBO back to its soup, it is possible to fail due to lack of store space for new or
changed VBO data, even though the VBO was created successfully.

Because the system manages store-backed VBO data transparently, calling a
function such as

StuffByte

on a VBO does not necessarily cause the system to

write new VBO data to the store. For similar reasons, VBOs may raise exceptions
at seemingly unusual times, as the system moves VBO data to and from store
memory as required to accommodate various objects' needs.

Finally, you may need to consider store space requirements when copying soup
entries that hold VBOs. When moving or copying a soup entry containing a VBO,
another copy of the VBO data is made by the destination soup's

Add

method

because VBO data is not shared between entries.

For a short code example that creates a VBO, saves data in it, and writes the VBO
to a soup, see the conclusion of the "Modifying VBO Data" section, immediately
following.

Modifying VBO Data

12

Recall that examining or modifying any slot in a soup entry causes the entire entry
to be read into the entry cache. When an entry containing a VBO is read into the
entry cache, the VBO data is not read into the entry cache, but made available to
the entry transparently.

Subsequently modifying the entry changes the cached data while leaving the
original soup entry untouched. The changes to the entry (and any VBOs residing in
it) are not saved until the entry is written back to the soup; for example, as the
result of an

EntryChangedXmit

call.

Because store space for VBO data is not allocated until the data is
actually written, it's recommended that you enclose VBO write
operations in exception handling code.

To undo changes to binary data associated with a VBO that resides in a cached
soup entry, call the

EntryUndoChanges

function. This function disposes of the

cached soup entry and restores references to the original, untouched soup entry; it
also undoes changes to VBO data referenced by the entry.