The information in this and succeeding chapters is intended for use by sites upgrading from ObjectStore Release 5.x to Release 5.1. If you are upgrading from an earlier release than ObjectStore Release 5, read the ObjectStore C++ Interface Release Notes supporting that upgrade for pertinent information.
This chapter provides general information about the release. Specific distributions of ObjectStore Release 5.1 for various platforms can be found in the README.txt file in the ObjectStore root directory. Solaris SPARC and Windows are supported for the release of ObjectStore Release 5.1.
Be sure to read all of the ObjectStore C++ Interface Release Notes before beginning the installation.
Component Schema for DLL Use
This feature allows for incremental loading and unloading of schema at run time. This functionality enables building applications that consist of component DLLs and their associated schemas. Component schema functionality is described in the ObjectStore Advanced C++ API User Guide and ObjectStore C++ API Reference. X/Open's XA Transaction Processing Standard Is Supported
In Release 5.1, ObjectStore clients and Servers can support X/Open's transaction processing standard (known as XA). The implementation of this interface is layered on top of the existing ObjectStore client library. An ObjectStore client can now act as a Resource Manager (RM). For more information, see Support for the XA Standard for Transaction Processing.
Address Space Reset
This feature allows applications to release address space that was assigned during the execution of a transaction. The existing ObjectStore entry point objectstore::release_address_space() is extended so that it can now work within a transaction. There is also a mechanism for keeping certain address space assigned. This mechanism is built using pvars and a new facility implemented with the os_retain_address class.
Reduced Address Space Consumption in Queries
In earlier releases of ObjectStore, queries on very large collections could terminate because address space ran out. In this release, the ObjectStore query facility includes two new memory modes that automatically release address space and allow you to create queries that will never run out of address space.
Dynamic Extents
Dynamic extents are a mechanism for treating all objects of a particular type in a segment or database as a collection. The new class os_dynamic_extent is used for this.
String Conversion for Asian Language String Encodings
A new facility for converting Asian language string encodings is available in this release. See os_str_conv for details. See also Conversion Between Asian Language String Encodings.
Bit Vector-Assisted Relocation
An optimization to relocation in ObjectStore Release 5.1 is the use of a bit vector to assist in the relocation of pages (in or out) that have already been relocated in once, and are still in the cache. osgc Utility Capabilities
The ObjectStore garbage collection utility, implemented to support the Java interface to ObjectStore, can now be used with ObjectStore C++ with some restrictions. The ObjectStore persistent garbage collector (GC) collects unreferenced objects and ObjectStore collections in an ObjectStore database and frees space associated with these objects. osgc Release 4 databases
osgc is supported only on databases initiated in Release 5 or later. Databases upgraded from previous releases are not supported, and using osgc on them can corrupt them.
Databases containing schema information about template instantiations (including information about ObjectStore templated collection types) inadvertently contain unreferenced objects that osgc will remove. This is safe and will not affect correct operation.
Documentation Enhancements
The ObjectStore Release 5.1 documentation is enhanced in content and form. The improvements are listed in the paragraphs that follow. Clarification of Functionality
There is new documentation for previously existing ObjectStore features. The following paragraphs provide cross-references to the new information in other books in the ObjectStore Release 5.1 documentation set. Collections documentation Improvements
Significant updates and clarification of the collections discussions in ObjectStore Collections C++ API Reference appear in the ObjectStore Release 5.1 documentation. os_rDictionary
Added information about os_rDictionary is available in the ObjectStore Collections C++ API Reference. See os_rDictionary for details.
Checkpoint/refresh
There is new information about how transactions work with checkpoint/refresh in the ObjectStore Advanced C++ API User Guide. See Checkpoint: Committing and Continuing a Transaction for details.
Additions to the
os_mop::current, os_mop::find_name, and os_mop::reset Previously undocumented, these are now included in the ObjectStore C++ API Reference.
os_mop class Installing the On-Line Documentation
To install the ObjectStore full-text-searchable documentation, unpack the documentation distribution by doing one of the following: For root installation
If ObjectStore has been installed as root, $OS_ROOTDIR is write protected. Therefore, you must complete the following steps.
# chmod +w $OS_ROOTDIR # cd $OS_ROOTDIR/.. # uncompress -c /cdrom/packages/ostore/doc_sol2.tar.Z | tar xvf - # chmod -w $OS_ROOTDIR
# cd $OS_ROOTDIR/.. uncompress -c /cdrom/packages/ostore/doc_sol2.tar.Z | tar xf -
When you run the ossearch command the first time, you will be asked whether to install it. After it installs, and on future invocations of ossearch, it will launch the configured browser on the root of the documentation tree.
On Windows platforms, you can invoke the searchable documentation from the ObjectStore Win32 group with the ObjectStore Documentation icon. In either case, your browser appears with a top index displayed. Select the documentation or bookshelf you want as usual.
You can search the entire ObjectStore Release 5.1 documentation set from the top-level bookshelf search button for each interface (for example, 5.1.0.0.0/ostore/doc/index.htm). Once you have selected a book, you can search the rest of its documentation set by selecting the search button in the navigation bar above the book text frame.
Search by entering a word or series of words separated by commas in the query box and pressing the Return key. If you are uncertain about how to enter a query, you can refer to an on-line search query guide by clicking on the string to learn additional query methods that appears in the search form.
static void objectstore::retain_persistent_addresses();
static void objectstore::release_persistent_addresses();
static void objectstore::get_retain_persistent_addresses();
static void objectstore::set_retain_persistent_addresses(
os_boolean value);
static void objectstore::reset_persistent_addresses();
static void objectstore::release_persistent_addresses(
os_boolean force);
These new functions are introduced to make explicit the distinction between disabling the retain behavior (done by calling objectstore::set_retain_persistent_addresses() with the value argument false) and deassigning address space (done by calling objectstore::reset_persistent_addresses()).
As with top-level transaction boundaries, when objectstore::retain_persistent_addresses is not in use, releasing address space during a transaction requires that the application drop pointers to persistent memory locations that are released.
static void objectstore::retain_persistent_addresses();
static void objectstore::release_persistent_addresses();
static void objectstore::get_retain_persistent_addresses();
static void objectstore::set_retain_persistent_addresses(
os_boolean value);
static void objectstore::reset_persistent_addresses();
A new argument, os_boolean force, has been added to objectstore::release_persistent_addresses()
static void objectstore::release_persistent_addresses(
os_boolean force);
These new functions are introduced to make explicit the distinction between disabling the retain behavior (done by calling objectstore::set_retain_persistent_addresses() with the value argument false) and deassigning address space (done by calling objectstore::reset_persistent_addresses()).
Calling objectstore::retain_persistent_addresses() is equivalent to calling objectstore::set_retain_persistent_addresses(true) or to calling objectstore::set_retain_persistent_addresses(false) and objectstore::reset_persistent_addresses().
objectstore::get_address_space_generation_number()
Address Space Generation Number
os_unsigned_int32 get_address_space_generation_number()This function returns an unsigned integer that is incremented by the client whenever it releases any address space. Its primary purpose is to support pointer caching, such as that used by ObjectStore collections in several circumstances. A transient cache of persistent pointers should be considered invalid whenever the value of objectstore::get_address_space_generation_number() increases. The objectstore::get_address_space_generation_number() function simply returns the value read from a variable, and so is fast enough to be called whenever a pointer cache is examined.
See os_retain_address in ObjectStore C++ API Reference for further information.
Use of pvars with os_retain_address
Instances of os_pvar are treated specially by the address release operation when called within a transaction. Any such os_pvars that are active when address space is released act like instances of os_retain_address - the persistent address that they refer to continues to be assigned. However, unlike os_retain_address, active os_pvars do not hold address space across transaction boundaries when objectstore::retain_persistent_addresses() is not operating. objectstore::set_retain_address() and objectstore::get_retain_counter()
The static functions objectstore::set_retain_address() and objectstore::get_retain_counter() can be used to retain and release individual address ranges. Each address range maintains a retain_counter that is initially 0. The function signatures are
static void objectstore::set_retain_address(
void *address, os_boolean value = true);
static os_unsigned_int32 objectstore::get_retain_count(
void *address);
Calls to objectstore::set_retain_address() with value = true on any address in the range will increment the counter. Calls to objectstore::set_retain_address() with value = false on any address in the range will decrement the counter (if it is greater than 0). Calling objectstore::get_retain_count on any address in a range returns the current value of the counter for that range.Whenever a range has a retain count greater than zero, that range will not be released by any release operations (except a force release operation).
However, there are certain address-space-consuming features that would benefit from having the ability to release address space in a manner that is transparent to the application. The primary example of such a feature is a collections query. During a query, address space might be consumed in large quantities. A new class, os_address_space_marker, provides the ability for a query to release the extra address space it consumed that is not required by the application outside the query. This allows queries that detect the address space full condition (err_address_space_full) and use this scheme to release the address space they have consumed and continue, to examine more objects than could fit into address space at any one time.
See os_address_space_marker in the ObjectStore C++ API Reference for a description of this class.
Interactions Between Different Address-Space Mechanisms
The different APIs for controlling address space can be ordered by the specificity (least to most) of the target address space, as follows:
objectstore::retain_persistent_addresses()
objectstore::release_persistent_addresses()
objectstore::reset_persistent_addresses()
objectstore::set_retain_persistent_addresses()
os_address_space_marker class
os_retain_address
os_pvar
objectstore::set_retain_address
For cases where several address space mechanisms are in place, the rule is that the more specific calls take precedence. The only exception is the force form of objectstore::release_persistent_addresses(), which causes all the mechanisms in effect at the time of the call to release. For calls at the same level of specificity, the retains take precedence over releases.
static os_ptr_val objectstore::get_unassigned_address_space();Returns the total amount of address space that is still available for assignment. The value returned is always a multiple of 64 KB.
static os_ptr_val objectstore::
get_largest_contiguous_unassigned_address_space();
Returns the size of the largest contiguous region of address space that is still available for assignment. The returned value is always a multiple of 64 KB.
Customizing Address Space Usage in Collections
ObjectStore provides the following two classes for use in customizing address space usage with collections. os_reference_cursor Class
Creates a transient reference-based list (os_packed_rlist) from any type of collection that can be iterated over using the member functions.
class os_reference_cursor {
public:
// This is the public reference based API to this class
os_reference * first();
os_reference * last();
os_reference * next();
os_reference * previous();
os_reference * retrieve();
os_int32 more() const;
os_int32 null() const { return !more(); };
// Versions of functions that automatically check for
// err_address_space_full
void * retrieve(os_address_space_marker &);
void * first(os_address_space_marker &);
void * last(os_address_space_marker &);
void * next(os_address_space_marker &);
void * previous(os_address_space_marker &);
// construction
os_reference_cursor(os_collection *, os_unsigned_int32 flags =
0);
// Destruction
~os_reference_cursor();
class os_cursor_holder
{
public:
// The public interface to os_cursor holder
os_cursor_holder(os_cursor * cursor);
os_cursor_holder(os_dictionary_cursor * cursor);
os_cursor_holder();
~os_cursor_holder();
void remember();
void remember(os_cursor * cursor);
void remember(os_dictionary_cursor * cursor);
void restore();
void init();
};
A component schema, also referrred to here as a DLL schema, is a self-contained schema associated with a DLL. It plays the same role for the DLL as an application schema plays for an application. Like a DLL, and unlike an application schema, a DLL schema can be loaded and unloaded dynamically at run time. Unlike the application schema, multiple DLL schemas can be in effect at the same time in a single program. The file name extension .adb is used for both application schemas and DLL schemas. DLL schemas are generated by ossg just as application schemas are.
For further information, see
In the ObjectStore C++ API Reference, see the new classes os_DLL_finder, os_DLL_schema_info, os_schema_handle, os_schema_info, and additions to the classes objectstore and os_database.
Support for the XA Standard for Transaction Processing
ObjectStore supports X/Open's transaction processing standard (known as XA). For further information see Support for the XA Standard for Transaction Processing in the ObjectStore C++ API User Guide.
os_dynamic_extent Class
Derived from os_Collection, an instance of this class can be used to create an extended collection of all objects of a particular type, regardless of which segments the objects reside in. All objects are retrieved in an arbitrary order that is stable across traversals of the segments, as long as no objects are created or deleted from the segment, and no reorganization is performed (using schema evolution or compaction).
Conversion Between Asian Language String Encodings
There are many standards for encoding Asian characters. In Japan, for example, five encodings are in broad use: JIS, SJIS, EUC,
Unicode, and UTF-8.
Updated: 04/15/98 15:15:40