The size of any NewtonScript object is limited by the amount of memory available in the NewtonScript heap. As a result, you cannot create binary objects larger than the amount of available NewtonScript heap space. For similar reasons, the amount of data that can be stored in a single soup entry is limited as well. (See "Saving Frames as Soup Entries" beginning on page 11-58 for details.) You can use virtual binary objects to work around these restrictions.

A virtual binary object or VBO is a special kind of object that is useful for holding binary data larger than the available space in the NewtonScript heap. VBOs can be used to store large amounts of raw binary data, such as large bitmaps, the samples of large digitized sounds, fax data, packages, or application-specific binary data. A package is actually a special kind of virtual binary object; however, a package is read-only and is created in a slightly different manner than a normal VBO.

In the following ways, VBOs are like normal NewtonScript binary objects:

The VBO is not persistent until it is written to a soup. As with any soup entry data, if a VBO in a soup entry is modified, the changes are not persistent until the cached entry frame is written back to the soup. If a soup entry containing a VBO is moved to another store, the binary data associated with the VBO is moved to that store as well. For a discussion of the soup entry cache, see "Entries" on page 11-17.

The space used by the VBO is made available for garbage collection when there are no more references to the VBO.

Binary data--including VBO data--is not shared between soup entries, even when their respective soups reside on the same store. As a result, you may need to consider space issues when moving or duplicating entries that hold VBO data.

VBOs are different from normal NewtonScript binary objects in the following ways:

VBO data does not reside in the NewtonScript heap--it resides in store memory.

Store memory for VBO data is not allocated until it is needed to write data. "Using Virtual Binary Objects" on page 12-8 discusses this important point in detail.

You cannot use a value stored in a virtual binary object as a soup index key.

VBOs can be created in compressed or uncompressed form. If the VBO is compressed, the system compresses and decompresses its associated binary data on demand. The fact that a VBO is compressed is normally transparent to your code; however, the time required to compress and uncompress VBO data may affect performance.

When passed a reference to a VBO residing on a store that is unavailable, methods that write VBO data throw exceptions rather than displaying the "Newton still needs the card" alert.