os_database

Persistent data can be accessed only if the database in which it resides is open. Databases are created, destroyed, opened, and closed with database member functions. The functions for creating, opening, and closing databases can be called either inside or outside a transaction. The function for destroying databases should be called outside a transaction.

Each database retrieved by a given process has an associated open count for that process. The member function os_database::open() increments the open count by 1, and the member function os_database::close() decrements the open count by 1. When the open count for a process increases from 0 to 1, the database becomes open for that process. A database becomes closed for a process when its open count becomes 0.

When a process terminates, any databases left open are automatically closed.

Instances of the class os_database are sometimes used to hold process local or per-process state, representing a property of the database for the current process. For example, the function os_database::is_writable() returns a value indicating whether the specified database is writable for the current process. This is per-process information since the database might be unwritable by one process (because it opened the database for read only - see os_database::open()) while it is writable by another process. As a consequence, it is sometimes preferable to think of an instance of this class as representing an association between a database and a process (the process that retrieves the pointer to it). In fact, instances of os_database are actually transient objects.

Invoking ::operator delete() on an os_database is illegal.

Some functions that perform administrative operations on databases (for example functions for changing database ownership or protection modes) are members of the class os_dbutil - see a description on page 106.

The types os_int32 and os_boolean, used throughout this manual, are each defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as an unsigned 32-bit integer type. The type os_unixtime_t is defined as unsigned long.

All ObjectStore programs must include the header file <ostore/ostore.hh>.

os_database::allow_external_pointers()

void allow_external_pointers(os_boolean set_default_only = 0);

A pointer from one database, db1, to another, db2, points to, at any given time, whichever database has a certain pathname - namely, db2's pathname at the time the pointer was stored. If db2's pathname changes (for example, as a result of performing osmv on db2), the pointer will no longer refer to data in db2. If some other database, db3, is given db2's original pathname (for example, as a result of performing osmv on db3), the pointer will refer to data in db3.

The pathname is not stored as part of the cross-database pointer (which takes the form of a regular virtual memory address), but rather as part of an os_database_reference stored in a table associated with the pointer.

It is illegal to rename a database so that a pointer that used to refer to another database now refers to the database in which the pointer itself resides.

References normally store a relative pathname; that is, if the source and destination databases have a common ancestor directory, the common directory is not stored as part of the pathname - only the part of the target database's pathname that is not shared with the source database's pathname is stored. On UNIX systems, for example, the common part of the pathname is preceded by the appropriate number of "../"s to traverse the hierarchy up from the source directory to the common ancestor directory. For example, if the source and target databases are named "/sys/appl/mydb" and "/sys/lib/lib1" respectively, the reference stores the relative pathname, "../lib/lib1".

You can override use of relative pathnames with the functions os_database::set_relative_directory() and os_database::get_relative_directory() - see the entries for these functions below.

Dereferencing a cross-database pointer causes the destination database, if not already open, to be opened for read/write. Thus, dereferencing such a pointer can result in err_database_not_found.

os_database::change_database_reference()

void change_database_reference(
      os_database_reference *old_ref, 
      os_database_reference *new_ref
);

os_database::change_database_reference starts its own transaction (outside any user transaction), and iterates over every segment in the database to find and change the reference. Be aware that there is a small risk of an address space problem if there are pvars that trigger data page use during the internal transaction that os_database::change_database_reference uses.

See also the functions os_database::allow_external_pointers() and os_database::get_database_references(), and the class os_database_reference.

os_database::change_schema_key()

void change_schema_key(
      os_unsigned_int32 old_key_low, 
      os_unsigned_int32 old_key_high,
      os_unsigned_int32 new_key_low, 
      os_unsigned_int32 new_key_high
);

<err-0025-0155> Attempt to change the schema key of database db1, but 
it is opened for read only.

err_schema_key
<err-0025-0152> The schema key of database db1 is frozen and may not 
be changed.

Error using schema keys
<err-0025-0158>Unable to change schema key of database db1.
The schema is already protected and the key provided did not match the 
old key in the schema. (err_schema_key)

new_key_low specifies the first component of the database's new schema key, and new_key_high specifies the second component. If both these arguments are 0, calling this function causes the database to have no schema key.

os_database::close()

void close();

os_database::create()

static os_database *create(
      const char *pathname, 
      os_int32 mode = 0664, 
      os_boolean if_exists_overwrite = 0,
      os_database *schema_database = 0
);

If a database with the specified pathname already exists, an err_database_exists exception is signaled, unless if_exists_overwrite is nonzero (true). If if_exists_overwrite is nonzero, any existing database with the same pathname is deleted, a new database is created with the specified mode, and the new database is opened for read/write.

If schema_database is 0, schema information is stored in the new database. The effect is the same as the result of calling create() without the schema_database argument:

      os_database::create(pathname, mode, if_exists_overwrite);

The specified schema database must be open at the time of the call to create(); if it is not, err_schema_database is signaled. If the schema database was opened for read only, ObjectStore attempts to reopen it for read/write. If this fails because of protections on the database, it remains open for read only. This prevents any update to the new database that requires schema installation.

Note that the new database's schema database can also contain regular user data (that is, data other than schema information). The schema database must store its own schema locally. If the schema for the user data in schema_database is stored remotely, err_schema_database is signaled.

For file databases, pathname is an operating system pathname. ObjectStore takes into account local NFS mount points when interpreting the pathname, so pathnames can refer to databases on foreign hosts. To refer to a database on a foreign host for which there is no local mount point, use a Server host prefix, the name of the foreign host followed by a colon (:), as in oak:/foo/bar.

For databases in ObjectStore directories, pathname consists of a rooted pathname preceded by a rawfs host prefix of the form host-name:: (for example oak::/foo/bar). The rawfs host prefix can be followed by a Server host prefix of the form host-name: (as in oak::beech:/foo/bar).

The Server host name specifies the file system on which you want the new database stored. If no Server host name is supplied, the value of the ObjectStore environment variable OS_SERVER_HOST is used.

os_database::create_root()

os_database_root *create_root(char *name);

os_database::create_segment()

os_segment *create_segment();

os_database::decache()

void decache(); 

Calling decache() on an os_database makes the os_database object, and any os_segment objects for that database, unusable. You should not refer to the os_database or os_segment objects again; doing so could lead to unpredictable results. If you want to open or look up the database again, use os_database::lookup() or the overloading of os_database::open() that takes a pathname argument.

There are some restrictions on when this function can be used. The call to os_database::decache() must be made outside a transaction. The application cannot be in retain_persistent_addresses mode. The database being decached cannot be the transient database, be currently opened by the application, or have open the database that it wants to decache. ObjectStore will raise an err_misc exception if any of these restrictions is violated.

Calling decache() on an os_database invalidates any os_reference_transient objects that refer to objects within the database. Attempting to resolve these invalidated references will have unpredictable results.

Applications should only call this routine if they probably will not refer to the database soon. There is some overhead associated with using a database for the first time that will be incurred again if the database is opened after it is decached.

os_database::destroy()

void destroy();

When a process destroys a database, this can affect other processes that have the database opened. Such a process might subsequently be unable to access some of the database's data - even if earlier in the same transaction it successfully accessed the database.

Data already cached in the process's client cache will continue to be accessible, but attempts to access other data will cause ObjectStore to signal err_database_not_found. Attempts to open the database will also provoke err_database_not_found. Note that performing os_database::lookup() on the destroyed database's pathname might succeed, since the instance of os_database representing the destroyed database might be in the process's client cache.

If you call this function from within a transaction, beware of the following:

• The effects of calling this function cannot be undone by aborting the transaction.
• On some but not all platforms, calling destroy() from within a transaction causes ObjectStore to signal the exception err_database_lock_conflict if another process is accessing the database.
• If you attempt to access data in a destroyed database in the same transaction in which it was destroyed, err_database_not_found is signaled.
• In most cases the database is actually removed from the Server at the end of the transaction, but in some cases it is removed earlier. For example, suppose that, before the transaction ends, you create a new database with the same pathname as the database on which you called destroy(). In this case, the old database is removed before the new database is created.

os_database::find_root()

os_database_root *find_root(char *name);

os_database::freeze_schema_key()

void freeze_schema_key(
      os_unsigned_int32 key_low, 
      os_unsigned_int32 key_high
);

Call this function from within an update transaction. The specified database must be opened for update, otherwise ObjectStore signals err_opened_read_only, and issues an error message like the following:

<err-0025-0156> Attempt to freeze the schema key of database db1, but 
it is opened for read only.

<err-0025-0151>The schema is protected and the key, if provided, did not 
match the one in the schema of database dba.

<err-0025-0159>Unable to freeze the schema key of database db1. The 
schema is protected and the key provided did not match the key in the 
schema.

os_database::get_all_databases()

static void get_all_databases(
      os_int32 max_to_return, 
      os_database_p *dbs, 
      os_int32& n_ret
);

os_database::get_all_roots()

void get_all_roots(
      os_int32 max_to_return, 
      os_database_root_p *roots, 
      os_int32& n_ret
);

os_database::get_all_segments()

void get_all_segments(
      os_int32 max_to_return, 
      os_segment_p *segs, 
      os_int32& n_ret
);

os_database::get_all_segments_and_permissions()

void get_all_segments_and_permissions(
      os_int32 max_to_return,
      os_segment_p* segs,
      os_segment_access_p* controls,
      os_int32 &n_returned
);

os_database::get_application_info()

void *get_application_info() const;

os_database::get_check_illegal_pointers()

os_boolean get_check_illegal_pointers() const;

os_database::get_database_references()

void get_database_references(
      os_int32 &n_refs, 
      os_database_reference_p *&array
) const;

os_database::get_default_check_illegal_pointers()

os_boolean get_default_check_illegal_pointers() const;

os_database::get_default_lock_whole_segment()

objectstore_lock_option get_default_lock_whole_segment() const;

os_database::get_default_null_illegal_pointers()

os_boolean get_default_null_illegal_pointers() const;

os_database::get_default_segment()

os_segment *get_default_segment() const;

os_database::get_default_segment_size()

os_int32 get_default_segment_size() const;

os_database::get_dirman_host_name()

char *get_dirman_host_name() const;

os_database::get_fetch_policy()

void get_fetch_policy(os_fetch_policy &policy, os_int32 &bytes);

os_database::get_file_host_name()

char *get_file_host_name() const;

os_database::get_host_name()

char *get_host_name() const;

os_database::get_id()

os_database_id *get_id() const;

os_database::get_incremental_schema_installation()

os_boolean get_incremental_schema_installation();

os_database::get_lock_whole_segment()

objectstore_lock_option get_lock_whole_segment() const;

os_database::get_n_databases()

static os_int32 get_n_databases();

os_database::get_n_roots()

os_int32 get_n_roots() const;

os_database::get_n_segments()

os_int32 get_n_segments() const;

os_database::get_opt_cache_lock_mode()

os_boolean get_opt_cache_lock_mode() const;

os_database::get_pathname()

char *get_pathname() const;

os_database::get_prms_are_in_standard_format()

os_boolean get_prms_are_in_standard_format() const;

os_int32 get_readlock_timeout() const;

os_database::get_relative_directory()

char *get_relative_directory() const;

os_database::get_required_DLL_identifiers()

const char* const* get_required_DLL_identifiers(
      os_unsigned_int32& count
);

This function can only be called within a transaction with the database open. The returned array and strings might reside in the database so they are only valid for one transaction.

os_database::get_schema_database()

os_database *get_schema_database() const;

os_database::get_sector_size()

os_unsigned_int32 get_sector_size();

os_database::get_segment()

os_segment *get_segment(os_unsigned_int32 segment_number);

os_database::get_transient_database()

static os_database *const get_transient_database();

os_database::get_writelock_timeout()

os_int32 get_writelock_timeout() const;

os_database::insert_required_DLL_identifier()

void insert_required_DLL_identifier(
      const char* DLL_identifier
);

See also os_database::insert_required_DLL_identifiers()

os_database::insert_required_DLL_identifiers()

void insert_required_DLL_identifiers
      (const char* const* DLL_identifiers, 
      os_unsigned_int32 count
);

For each identifier, checks that the identifier is not already in the set. If already present, the identifier is not copied. If the identifier isn't present in the set of required DLLs, it is copied and added to the set. This function can only be called in an update transaction with the database open for write.

os_database::insert_required_DLL_identifiers is equivalent to repeated calls to os_database::insert_required_DLL_identifier but is more efficient.

os_database::is_open()

os_boolean is_open() const;

os_database::is_open_mvcc()

os_boolean is_open_mvcc() const;

os_database::is_open_read_only()

os_boolean is_open_read_only() const;

os_database::is_writable()

os_boolean is_writable() const;

os_database::lookup()

static os_database *lookup(
      const char *pathname 
      os_int32 create_mode = 0
);

For information on database pathnames, see os_database::create().

os_database::of()

static os_database *of(void *location);

os_database::open()

void open(os_boolean read_only = 0);

static os_database *open(
      const char *pathname, 
      os_boolean read_only = 0,
      os_int32 create_mode = 0 
);

If create_mode is nonzero and no database named pathname exists, the effect is the same as calling os_database::create() with the same pathname, create_mode, and schema_database arguments. The values of create_mode - which must be octal numbers, beginning with 0 - are described in ObjectStore Management.

For information on database pathnames, see os_database::create().

static os_database *open(
      const char *pathname, 
      os_boolean read_only,
      os_int32 create_mode, 
      os_database *schema_database
);

The specified schema database must be open at the time of the call to open(); if it is not, err_schema_database is signaled. If the schema database was opened read only, ObjectStore attempts to reopen it for read/write. If this fails because of protections on the database, it remains open for read only. This prevents any update to the new database that requires schema installation.

Note that the new database's schema database can also contain regular user data (that is, data other than schema information). The schema database must store its own schema locally. If the schema for the user data in schema_database is stored remotely, err_schema_database is signaled.

os_database::open_mvcc()

void open_mvcc();

If an application has a database opened for MVCC, it never has to wait for locks to be released in order to read the database. Reading a database opened for MVCC also never causes other applications to have to wait to update the database. In addition, an application never causes a deadlock by accessing a database it has opened for MVCC.

In each transaction in which an application accesses a database opened for MVCC, the application sees what it would see if viewing a snapshot of the database taken sometime during the transaction. This snapshot has the following characteristics:

• It is internally consistent.
• It might not contain changes committed during the transaction by other processes.
• It does contain all changes committed before the transaction started.

Even though the snapshot might be out of date by the time some of the access is performed, multiversion concurrency control retains serializability, if each transaction that accesses an MVCC database accesses only that one database. Such a transaction sees a database state that would have resulted from some serial execution of all transactions, and all the transactions produce the same effects as would have been produced by the serial execution.

static os_database *open_mvcc(const char *pathname);

os_database::remove_required_DLL_identifier()

void remove_required_DLL_identifier(
      const char* DLL_identifier
);

os_database::set_access_hooks()

typedef void (*os_access_hook) (
      void *object,
      enum os_access_reason reason, 
      void *user_data,
      void *start_range, 
      void *end_range
);

void set_access_hooks
      os_char_p class_name,
      os_access_hook inbound_hook,
      os_access_hook outbound_hook,
      os_void_p user_data,
      os_access_hook *old_inbound_hook = 0,
      os_access_hook *old_outbound_hook = 0,
      os_void_p *old_user_data = 0
);

The class_name argument is the name of the class with which these hook functions should be associated.

inbound_hook is the user-supplied hook function that is called each time an instance of the specified class in the specified database becomes accessible (that is, the first time in each transaction the object is accessed, as well as each time the object is transferred into the client cache).

outbound_hook is the user-supplied hook function that is called each time an instance of the specified class in the specified database undergoes outbound relocation. This typically occurs each time the transaction ends and the object is in the client cache, and each time the object is transferred out of the client cache.

In some cases, however, an object might be transferred out of the client cache without undergoing outbound relocation (see for example OS_EVICT_IN_ABORT in ObjectStore Management), and so the outbound_hook is not called. This means that there is not necessarily a call to the outbound_hook for each call to the inbound_hook. So you must structure your application to allow for consecutive calls to the inbound hook without intervening calls to the outbound hook.

The inbound_hook and outbound_hook arguments can be null pointers in order to specify that there should be no hook. To disable both hooks, pass a null pointer for both these arguments.

user_data is a pointer to user data to be passed to the hook functions.

The previous value for the inbound_hook is returned in the location pointed to by old_inbound_hook, if old_inbound_hook is a nonnull pointer. The previous value will be 0 if no inbound_hook was enabled. Similarly, the previous values of outbound_hook and user_data are returned in the locations pointed to by old_outbound_hook and old_user_data if these are nonnull pointers.

The hook functions are called with the following arguments:

object points to the beginning of the object for which the access hook is registered.

For an inbound hook, reason is always set to os_reason_accessed. For an outbound hook, reason is os_reason_committed if the object is on a page that is being relocated out at the end of a transaction, os_reason_aborted if the page is being relocated out during a transaction abort, and os_reason_returned if the page is being relocated out at some other time, presumably to make space in the cache for other data.

user_data is set to the value of user_data that was passed to os_database::set_access_hooks().

start_range is the first address that is being made accessible during an inbound hook, or made inaccessible during an outbound hook. end_range is the first address beyond the range being made accessible or inaccessible. That is, all addresses greater than or equal to start_range and less than end_range are being made accessible or inaccessible.

Only a portion of the object might lie within start_range and end_range. The hook should only write within this address range. You should make all modifications by calling objectstore::hidden_write(). Note that the active region of the object might be writable in the context of the hook, but under no circumstances should the application modify any persistent addresses from within the hook by any other means other than by using the objectstore::hidden_write() function.

Read access is allowed to any part of the object, not just the part within the address range. You cannot safely dereference pointers outside the object, but you can pass them to objectstore::get_pointer_numbers().

Classes within unions will not have access hooks called.

os_database::set_application_info()

void set_application_info(void *info);

os_database::set_check_illegal_pointers()

void set_check_illegal_pointers(os_boolean);

os_database::set_default_check_illegal_pointers()

void set_default_check_illegal_pointers(os_boolean);

os_database::set_default_lock_whole_segment()

void set_default_lock_whole_segment(objectstore_lock_option);

os_database::set_default_null_illegal_pointers()

void set_default_null_illegal_pointers(os_boolean);

os_database::set_default_segment()

void set_default_segment(os_segment*);

os_database::set_default_segment_size()

void set_default_segment_size(os_int32);

os_database::set_fetch_policy()

enum os_fetch_policy { os_fetch_segment, os_fetch_page, os_
fetch_stream };
void set_fetch_policy(os_fetch_policy policy, os_int32 bytes);

The default fetch policy is os_fetch_page.

If an operation manipulates a substantial portion of a small segment, use the os_fetch_segment policy when performing the operation on the segment. Under this policy, ObjectStore attempts to fetch the entire segment containing the desired page in a single client/server interaction, if the segment will fit in the client cache without evicting any other data. If there is not enough space in the cache to hold the entire segment, the behavior is the same as for os_fetch_page with a fetch quantum specified by bytes.

If an operation uses a segment larger than the client cache, or does not refer to a significant portion of the segment, use the os_fetch_page policy when performing the operation on the segment. This policy causes ObjectStore to fetch a specified number of bytes at a time, rounded up to the nearest positive number of pages, beginning with the page required to resolve a given object reference. bytes specifies the fetch quantum. (Note that if you specify 0 bytes, this will be rounded up, and the unit of transfer will be a single page.)

The default value for the fetch quantum is 4096 bytes (1 page). Appropriate values might range from 4 kilobytes to 256 kilobytes or higher, depending on the size and locality of the application data structures.

For special operations that scan sequentially through very large data structures, os_fetch_stream might considerably improve performance. As with os_fetch_page, this fetch policy lets you specify the amount of data to fetch in each client/server interaction for a particular segment. But, in addition, it specifies that a double buffering policy should be used to stream data from the segment.

This means that after the first two transfers from the segment, each transfer from the segment replaces the data cached by the second-to-last transfer from that segment. This way, the last two chunks of data retrieved from the segment will generally be in the client cache at the same time. And, after the first two transfers, transfers from the segment generally will not result in eviction of data from other segments. This policy also greatly reduces the internal overhead of finding pages to evict.

When you perform allocation that extends a segment whose fetch policy is os_fetch_stream, the double buffering described above begins when allocation reaches an offset in the segment that is aligned with the fetch quantum (that is, when the offset mod the fetch quantum is 0).

For all policies, if the fetch quantum exceeds the amount of available cache space (cache size minus wired pages), transfers are performed a page at a time. In general, the fetch quantum should be less than half the size of the client cache.

Note that a fetch policy established with set_fetch_policy() (for either a segment or a database) remains in effect only until the end of the process making the function call. Moreover, set_fetch_policy() only affects transfers made by this process. Other concurrent processes can use a different fetch policy for the same segment or database.

os_database::set_incremental_schema_installation()

void set_incremental_schema_installation(os_boolean);

os_database::set_lock_whole_segment()

void set_lock_whole_segment(objectstore_lock_option);

os_database::set_new_id()

os_int32 set_new_id();

os_database::set_null_illegal_pointers()

void set_null_illegal_pointers(os_boolean);

If the argument is 1 (that is, true), it loops over every segment, including internal segments, enabling null_illegal_pointers. It also enables default_null_illegal_pointers mode for the specified database.

If the argument is 0 (that is, false), it disables null_illegal_pointers mode for every segment, and disables default_null_illegal_pointers mode for the specified database.

See os_segment::set_null_illegal_pointers() and os_database::set_default_null_illegal_pointers().

os_database::set_opt_cache_lock_mode()

void set_opt_cache_lock_mode(os_boolean);

Turning on this mode will improve performance for applications that perform writes to the specified database and expect little or no contention from other processes for access to the database. When this mode is on, the amount of client/server communication required to upgrade locks is reduced. Once a page from the database is cached on the client, the client can subsequently upgrade the page's lock from read to read/write when needed without communicating with the Server. However, the amount of client/server communication required for concurrent processes to obtain locks on pages in the database might increase.

Note that this function sets the mode for the current process only, and does not affect the mode for other processes.

os_database::set_readlock_timeout()

void set_readlock_timeout(os_int32);

os_database::set_relative_directory()

void set_relative_directory(char *dir_name);

os_database::set_schema_database()

void set_schema_database(os_database& schema_database);

If you copy the schema database with an operating system command or an ObjectStore utility, you can also use os_database::set_schema_database() to establish the copy as the schema database for this. If schema_database is not the result of copying or moving a database that has served as schema database for this, err_schema_database is signaled.

os_database::set_writelock_timeout()

void set_writelock_timeout(os_int32);

os_database::size()

os_unsigned_int32 size() const;

os_database::size_in_sectors()

os_unsigned_int32 size_in_sectors() const;

os_database::time_created()

os_unixtime_t time_created() const;

Updated: 03/31/98 17:25:09