static os_boolean abort_in_progress();Returns nonzero if an abort is in progress; returns 0 otherwise.
enum os_lock_type { os_read_lock, os_write_lock, os_no_lock } ;
static os_lock_timeout_exception *acquire_lock(
void *addr,
os_lock_type lock_type,
os_int32 milliseconds,
os_unsigned_int32 bytes_to_lock = 1
);
Attempts to acquire a lock of the type specified by lock_type (either os_read_lock or os_write_lock) on the page(s) containing the memory starting at addr and spanning bytes_to_lock bytes. If the lock is successfully acquired, 0 is returned.
Specifying a -1 value for the milliseconds arguments means that acquire_lock uses the segment's current readlock_timeout or writelock_timeout value depending on the type of lock being acquired.
If the caller wants an infinite timeout and the segment's timeout values are not -1, the caller could pass a very large value for the timeout (to be effectively infinite). It could also use one of the objectstore::set_readlock_timeout or objectstore::set_writelock_timeout entrypoints to set the default to -1 temporarily.
Specifying a 0 value for the milliseconds arguments means that the attempt to acquire the lock will not wait at all if any concurrency conflict is encountered.
After an attempt to acquire a lock, if the time specified by milliseconds elapses without the lock's becoming available, an os_lock_timeout_exception* is returned. The timeout is rounded up to the nearest whole number of seconds. The os_lock_timeout_exception contains information on the circumstances preventing lock acquisition. It is the caller's responsibility to delete the os_lock_timeout_exception object when no longer needed.
If the attempt causes err_deadlock to be signaled in the current process, the transaction is aborted regardless of the value of the specified timeout.
static os_lock_timeout_exception *acquire_lock(
os_database *db,
os_lock_type access,
os_int32 milliseconds
);
Attempts to acquire a lock of the type specified by lock_type (either os_read_lock or os_write_lock) on the database specified by db. Locking a database is equivalent to acquiring locks on all the pages (and segments) of the database. So, for example, acquiring a read lock on a database is equivalent to acquiring read locks on all the pages of the database. Acquiring a lock on a database does not preclude clients from requesting separate locks on individual pages of the database.If the lock is successfully acquired, 0 is returned.
Specifying a -1 value for the milliseconds arguments means that acquire_lock uses the segment's current readlock_timeout or writelock_timeout value depending on the type of lock being acquired.
If the caller wants an infinite timeout and the segment's timeout values are not -1, the caller could pass a very large value for the timeout (to be effectively infinite). It could also use one of the objectstore::set_readlock_timeout or objectstore::set_writelock_timeout entrypoints to set the default to -1 temporarily.
Specifying a 0 value for the milliseconds arguments means that the attempt to acquire the lock will not wait at all if any concurrency conflict is encountered.
After an attempt to acquire a lock, if the time specified by milliseconds elapses without the lock's becoming available, an os_lock_timeout_exception* is returned. The timeout is rounded up to the nearest whole number of seconds. The os_lock_timeout_exception contains information on the circumstances preventing lock acquisition. It is the caller's responsibility to delete the os_lock_timeout_exception object when it is no longer needed.
If the attempt causes err_deadlock to be signaled in the current process, the transaction is aborted regardless of the value of the specified timeout.
static os_lock_timeout_exception *acquire_lock(
os_segment *seg,
os_lock_type access,
os_int32 milliseconds
);
Attempts to acquire a lock of the type specified by lock_type (either os_read_lock or os_write_lock) on the segment specified by seg. This must be specified in a top-level transaction.Locking a segment is equivalent to acquiring locks on all the pages of the segment. So, for example, acquiring a read lock on a segment is equivalent to acquiring read locks on all the pages of the segment. Acquiring a lock on a segment does not preclude that A client that has acquired a lock on a segment can also request separate locks on individual pages of the segment.
If the lock is successfully acquired, 0 is returned.
Specifying a -1 value for the milliseconds arguments means that acquire_lock uses the segment's current readlock_timeout or writelock_timeout value depending on the type of lock being acquired.
If the caller wants an infinite timeout and the segment's timeout values are not -1, the caller could pass a very large value for the timeout (to be effectively infinite). It could also use one of the objectstore::set_readlock_timeout or objectstore::set_writelock_timeout entry points to set the default to -1 temporarily.
Specifying a 0 value for the milliseconds arguments means that the attempt to acquire the lock will not wait at all if any concurrency conflict is encountered.
After an attempt to acquire a lock, if the time specified by milliseconds elapses without the lock's becoming available, an os_lock_timeout_exception* is returned. The timeout is rounded up to the nearest whole number of seconds. The os_lock_timeout_exception contains information on the circumstances preventing lock acquisition. It is the caller's responsibility to delete the os_lock_timeout_exception object when it is no longer needed.
If the attempt causes err_deadlock to be signaled in the current process, the transaction is aborted regardless of the value of the specified timeout.
typedef void* (*os_missing_dispatch_table_handler_function)
const char* dispatch_table_identifier, const char*
dispatch_table_symbol
);
static void add_missing_dispatch_table_handler(
os_missing_dispatch_table_handler_function
);
Registers the specified os_missing_dispatch_table_handler_function. During inbound relocation of a given page, if an object's vtbl slot is not satisfied by any known vtbls, the handler gets called with a string denoting a path to the vtbl slot and a string denoting the platform-dependent linker symbol associated with the vtbl identifier if known.For example, given
class A { virtual vf1(); };
class B { virtual vf2(); };
class C : public A, public B { virtual vf3(); };
ObjectStore calls the user's handler function with the string "C@B" if it cannot satisfy the virtual function table slot for the base class subobject B in class C. The dispatch_table_symbol is the compiler-specific linker symbol that ObjectStore associates with the dispatch table, or null if the vtbl identifier has no entry in the application schema source file linked in to the application. The dispatch_table_symbol is provided to allow an application to load a library dynamically and look up the symbol. It is also useful for generating a missing vtbl.
static void *change_array_length(
void *array,
os_unsigned_int32 new_length
);
Reallocates the specified persistent array to have the specified number of elements. Returns the address of the reallocated array. The reallocation might or might not be in place. If the value returned is different from the argument, the argument storage has been deleted and is no longer valid. change_array_length is similar to the C function realloc, but it works for persistent objects only. This function does not execute any constructors or destructors; it simply changes the amount of persistent storage available for the array. In future releases, the behavior of this function might change with regard to when in-place reallocation is performed.
static void compact(
os_char_p *dbs_to_be_compacted,
os_pathname_and_segment_number_p
*segments_to_be_compacted = 0,
os_char_p *dbs_referring_to_compacted_ones = 0,
os_pathname_and_segment_number_p
*segments_referring_to_compacted_ones = 0
);
Compacts the data in the specified databases and segments, and reorganizes any collections that reference compacted objects. Programs using this function must link with liboscmp.a.dbs_to_be_compacted is a null-terminated array of pointers to os_char_p strings identifying the set of databases to be compacted.
os_pathname_and_segment_number_p is a null-terminated array of pointers to pathname_and_segment_number objects identifying the segments to be compacted.
dbs_referring_to_compacted_ones is a null-terminated array of pointers to os_char_p strings identifying the set of databases containing pointers (or references) to the databases or segments being compacted.
segments_referring_to_compacted_ones is a null-terminated array of pointers to os_pathname_and_segment_number_p objects identifying the segments containing pointers (or references) to the databases being compacted.
Either the first or second argument, but not both, can be null; the second argument defaults to null. The set of segments to be compacted is the union of all the data segments in all databases specified by the first argument, plus those segments specified in the optional second argument.
The third and fourth arguments are optional, and if supplied are sets of database pathnames and segment objects containing references to objects in the databases and segments to be compacted. If they are not supplied the compactor assumes that there are no other pointers or references to the segments being compacted.
It is the caller's responsibility to delete the storage associated with the arguments when the function returns.
Compaction-specific invalid arguments will result in the exception err_os_compaction's being signaled.
The objectstore::compact() function must be invoked outside any ObjectStore transaction. It is the caller's responsibility to delete the storage associated with the arguments to objectstore::compact() upon its return.
If you want to run compaction in a separate process, the application can start up another process that calls the function.
The compactor compacts all C and C++ persistent data, including ObjectStore collections, indexes, and bound queries, and correctly relocates pointers and all forms of ObjectStore references to compacted data. ObjectStore os_reference_local references are relocated, assuming that they are relative to the database containing them. The compactor respects ObjectStore clusters, in that compaction will ensure that objects allocated in a particular cluster remain in the cluster, although the cluster itself might move as a result of compaction.
This function operates under the following restrictions:
The ObjectStore rawfs, on the other hand, stores all databases in a single region, either one or more host files or a raw partition. When you are using the raw file system, any space freed by the compaction operation can be reused by any segment in any database stored in the raw file system.
static void discriminant_swap_bytes(
char *address, char *result, os_int32 n_bytes
);
When you are accessing, from within a discriminant function, databases created by clients with a different byte ordering, access to a data member whose value occupies more than a single byte must be mediated by objectstore::discriminant_swap_bytes(). This function performs byte swapping that ObjectStore normally performs automatically. Use of this function is only required within discriminant functions. The address argument is the address of the member whose access is being mediated by this function. The n_bytes argument is the number of bytes to swap; possible values are 2, 4, and 8. The result argument points to memory allocated by the user to hold the correctly byte-swapped result; the allocated space should contain n_bytes bytes.
static os_boolean embedded_server_available();
Functions that report on embedded Servers and on network Servers are mutually exclusive. That is, objectstore::embedded_server_available and objectstore::network_servers_available cannot both return true in the same application.
static void enable_damaged_dope_repair(os_boolean);
Damaged dope repair repairs compiler dope damage by regenerating compiler dope in all cached user data pages of affected databases.
You can query whether dope damage repair is enabled or disabled by calling the function objectstore::is_damaged_dope_repair_enabled().
If dope repair is not enabled, dope damage while loading a DLL schema throws an err_transient_dope_damaged exception.
If dope damage is enabled, dope damage while loading a DLL schema causes ObjectStore to examine each cached user (that is, nonschema) data page, of each segment that contains any transient dope, of each affected database. If the page is currently accessible, ObjectStore immediately regenerates its transient dope (through relocation), otherwise ObjectStore marks the page and its transient dope is regenerated the next time the page is touched.
Note that an object can suffer dope damage when the implementation of its class changes, even if the object is never used by the program. This is because ObjectStore brings entire pages of databases into memory at a time. If an object is on the same page as another object that is being used, then the first object is also being used as far as dope damage is concerned.
When the combined program schema is rebuilt because a DLL schema has been unloaded, compiler dope in cached persistent objects always needs to be repaired (assuming that there could have been compiler dope pointing to a DLL that was unloaded). This repair takes place regardless of the setting of objectstore::enable_damaged_dope_repair_enabled(). The repair procedure is the same as described previously.
static void enable_DLL_schema(os_boolean);Enables or disables the component schema feature. The default is true for Windows and Solaris platforms.
Use objectstore::is_DLL_schema_enabled to query whether DLL schema support is enabled.
static os_schema_handle* find_DLL_schema(
const char* DLL_identifier,
os_boolean load_if_not_loaded,
os_boolean error_if_not_found
);
Returns a pointer to the DLL schema handle for the DLL identified by the first argument in the following cases:
Note that objectstore::load_DLL throws the exception err_DLL_not_loaded if the DLL cannot be found or loaded or the DLL_identifier cannot be understood and error_if_not_found is true.
If the DLL schema is still not found, and if error_if_not_found is true, this function throws an err_schema_not_found exception, otherwise returns a null pointer. Note that if load_if_not_loaded and error_if_not_found are both true, the exception thrown is err_DLL_not_loaded.
os_unsigned_int32 get_address_space_generation_number()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.
static void get_all_servers(
os_int32 max_servers,
os_server_p *servers,
os_int32& n_servers
);
Provides access to instances of os_server that represent all the ObjectStore Servers known to the current process. The os_server_p* is an array of pointers to os_server objects. This array must be allocated by the user. The function objectstore::get_n_servers() can be used to determine how large an array to allocate. max_servers is specified by the user, and is the maximum number of elements the array is to have. n_servers refers to the actual number of elements in the array.
static const char *get_application_schema_pathname();Returns the pathname of the application schema database.
static void get_as_intervals(
os_as_interval_p *persist,
os_int32& n_persist_intervals,
os_as_interval_p *other,
os_int32& n_other_intervals
);
This function tells the caller all the ranges of virtual address space that ObjectStore is using, other than ordinary code, text, and heap space. It is primarily intended for users who are trying to integrate ObjectStore and other complex subsystems into the same application. The class os_as_interval has the following public data members:
char *start; os_unsigned_int32 size;The ranges are returned in two sets. The first set of ranges are those used for mapping in persistent objects; the second set is any other ranges of address space that ObjectStore uses.
static void get_auto_open_mode(
auto_open_mode_enum &mode,
os_fetch_policy &fp,
os_int32 &bytes);
Returns the value of the current settings for process-specific values for os_auto_open_mode and os_fetch_policy, and the number of bytes used by the fetch policy.See also objectstore::set_auto_open_mode() and os_database::set_fetch_policy().
objectstore::get_autoload_DLLs_function()
static os_autoload_DLLs_function get_autoload_DLLs_function();
static char *get_cache_file();
It is the caller's responsibility to deallocate the returned string when it is no longer needed.
static os_unsigned_int32 get_cache_size();Returns the current size in bytes of the client cache.
static os_boolean get_check_illegal_pointers();Returns nonzero (that is, true) if the current process enables default_check_illegal_pointers mode for newly created databases; returns 0 (that is, false) otherwise. See objectstore::set_check_illegal_pointers().
objectstore::get_incremental_schema_installation()
static os_boolean get_incremental_schema_installation();Returns nonzero (that is, true) if incremental schema installation is currently enabled; returns 0 (that is, false) if batch schema installation is enabled. See objectstore::set_incremental_schema_installation().
objectstore::get_locator_file()
static char* get_locator_file() const;Returns a string representing the locator file. If the first character of the string is a white-space character or #, the string is the contents of the file rather than a file name.
The caller should delete the returned value.
static os_int32 get_lock_status(void *address);Returns one of the following enumerators: os_read_lock, os_write_lock, os_no_lock, indicating the current lock status of the data at the specified address.
static char *get_log_file();
It is the caller's responsibility to deallocate the returned string when it is no longer needed.
static os_int32 get_n_servers();Returns the number of ObjectStore Servers to which the current process is connected.
static os_boolean get_null_illegal_pointers();Returns nonzero (that is, true) if the current process enables default_null_illegal_pointers mode for newly created databases; returns 0 (that is, false) otherwise. See objectstore::set_null_illegal_pointers().
objectstore::get_object_range()
static void get_object_range(
void const *address,
void *&base_address,
os_unsigned_int32 &size
);
Tells you where a persistent object starts and how large it is. address should be a pointer to a persistent object, or into the middle of a persistent object. base_address is set to the address of the beginning of the object, and size is set to the size of the object in bytes. Arrays are considered to be one object; if address is the address of one of the array elements, base_address is set to the address of the beginning of the array. If address does not point to a persistent object, base_address and size are both set to 0.
static os_boolean get_opt_cache_lock_mode();Returns nonzero if opt_cache_lock_mode is on for the current process; returns 0 otherwise. See objectstore::set_opt_cache_lock_mode().
static os_unsigned_int32 get_page_size();Returns the page size for the architecture on which ObjectStore is running.
static void get_pointer_numbers(
const void *address,
os_unsigned_int32 &number_1,
os_unsigned_int32 &number_2,
os_unsigned_int32 &number_3
);
Provides a way for an application to generate a hash code based on object identity. Applications should not generate hash codes by casting a pointer to the object into a number, since the address of an object can change from transaction to transaction. Based on the address supplied by the caller, the function returns number_1, number_2, and number_3. Use number_1 and number_3 only; ignore number_2.
These values will always be the same for a given object, no matter what address it happens to be mapped to at a particular time. Moreover, no two objects will have the same values.
static os_int32 get_readlock_timeout();Returns the time in milliseconds for which the current process will wait to acquire a read lock. A value of -1 indicates that the process will wait forever if necessary.
static os_boolean get_retain_persistent_addresses();Returns nonzero (that is, true) if the current process is in retain_persistent_addresses mode; returns 0 otherwise. See objectstore::retain_persistent_addresses().
objectstore::get_simple_auth_ui()
static void get_simple_auth_ui(
void(*&handler)
(os_void_p, os_char const_p, os_char_p, os_int32,
os_char_p, os_int32),
void *&data
);
Retrieves the authentication handler information stored by objectstore::set_simple_auth_ui(). handler is the function that will be called to determine the user and password information needed for authentication. data is the user-supplied value that will be passed to the handler function.
static os_boolean get_thread_locking();If nonzero is returned, ObjectStore thread locking is enabled; if 0 is returned, ObjectStore thread locking is disabled. See objectstore::set_thread_locking().
objectstore::get_transient_delete_function()
static void (*)(void*) get_transient_delete_function();Returns a pointer to the transient delete function last specified by the current process. Returns 0 if there is no current transient delete function. See objectstore::set_transient_delete_function().
objectstore::get_writelock_timeout()
static os_int32 get_writelock_timeout();Returns the time in milliseconds for which the current process will wait to acquire a write lock. A value of -1 indicates that the process will wait forever if necessary.
static void hidden_write(
char *src_address,
char *dst_address,
os_unsigned_int32 len
);
src_address points to a transient address, and dst_address points to a persistent address. This function writes len bytes pointed to by src_address into the dst_address, without write-locking the object at dst_address and without marking the object as modified. This function should only be used from within an access hook (see os_database::set_access_hooks()), and it should only write to locations inside the object for which this access hook is invoked. Typically, the access hook should only use this function to write to locations in the range of addresses that are being made accessible or inaccessible. The persistent value of any location that is used as the target of an objectstore::hidden_write() should never be examined by any program.
objectstore::ignore_locator_file()
static void ignore_locator_file(os_boolean);Passing a nonzero value ensures that no locator file is associated with the application, regardless of the setting of OS_LOCATOR_FILE or calls to set_locator_file(). This function is, however, subordinate to the client environment variable OS_IGNORE_LOCATOR_FILE. Passing 0 undoes the effect of the previous call to this function.
static void initialize();Must be executed in a process before any use of ObjectStore functionality is made, with the following exceptions:
A process can execute initialize() more than once; after the first execution, calling this function has no effect.
static void initialize(os_boolean force_full_initialization);Can be used instead of the no-argument overloading of initialize(). If force_full_initialize is nonzero, all ObjectStore initialization procedures are performed immediately. If force_full_initialize is 0, this function defers some initialization until needed (for example, until a database is first opened). If force_full_initialize is 0, this function behaves just like the no-argument overloading of initialize(). Applications that integrate with third-party software might need to force full initialization.
static os_boolean is_damaged_dope_repair_enabled();Returns a boolean value indicating whether dope damage repair during DLL schema loading is enabled. The initial state is false. See objectstore::enable_damaged_dope_repair() for details.
objectstore::is_DLL_schema_enabled()
os_boolean is_DLL_schema_enabled();Returns whether the DLL schema feature is enabled. The initial state is true on most platforms including Windows and Solaris.
static os_boolean is_lock_contention();Returns nonzero if a server involved in the current transaction has experienced contention for some persistent memory that the calling application is using. Returns 0 otherwise.
This function can be used in conjunction with MVCC to help determine whether to start a new transaction in order to make available more up-to-date data. If your application has a database open for MVCC, and during the current transaction another application has write-locked a page read by your application, is_lock_contention() returns nonzero.
If this function is not called from within a transaction, err_trans is signaled.
Note that this function is advisory - it does not have to be called and its return value can be ignored without jeopardizing in any way the correctness of ObjectStore's behavior.
static os_boolean is_persistent(void const *address);Returns nonzero (true) if the specified address points to persistent memory, and returns 0 (false) otherwise. A pointer to any part of a persistently allocated object (including, for example, a pointer to a data member of such an object) is considered to point to persistent memory. Similarly, a pointer to any part of a transiently allocated object is considered to point to transient memory.
static os_DLL_handle load_DLL(
const char* DLL_identifier,
os_boolean error_if_not_found = true
);
If the DLL cannot be found or the DLL_identifier cannot be understood, and error_if_not_found is false, this function returns os_null_DLL_handle.
If the DLL cannot be found or the DLL_identifier cannot be understood and error_if_not_found is true, this function throws the exception err_DLL_not_loaded.
If currently in a transaction, aborting the transaction does not roll back load_DLL(). The effects of trying to load a DLL that is already loaded has platform-dependent effects.
A DLL can have multiple identifiers, each of which works only on a subset of platforms. The automatic DLL loading mechanism always sets error_if_not_found to false and tries all the identifiers.
An error while trying to load the DLL, other then failure to find the DLL, will throw an exception regardless of the setting of error_if_not_found. This could occur if an error occurs while executing the DLL's initialization code, for example.
objectstore::lock_segment_read
This enumerator serves as a possible argument to os_segment::set_lock_whole_segment(). A value of lock_segment_read causes pages in the segment to be read-locked when cached in response to attempted access by the client. Subsequently, upgrading to read/write locks occurs on a page-by-page basis, as needed. objectstore::lock_segment_write
This enumerator serves as a possible argument to os_segment::set_lock_whole_segment(). A value of lock_segment_write causes pages to be write-locked when cached in response to attempted read or write access by the client. In this case, the Server assumes from the start that write access to the entire segment is desired. objectstore::lookup_DLL_symbol()
static void* objectstore::lookup_DLL_symbol(
os_DLL_handle h,
const char* symbol
);
Looks up the symbolically named entry point in the DLL identified by the handle and returns its address. If the DLL does not export a symbol equal to the argument, an err_DLL_symbol_not_found exception is thrown.
static os_boolean network_servers_available();
Functions that report on embedded Servers and on network Servers are mutually exclusive. That is, objectstore::network_servers_available and objectstore::embedded_server_available cannot both return true in the same application.
static void propagate_log(const char *log_path);
An exception is raised (err_not_supported) if this entry point is called from within a full ObjectStore (networked) application.
When used, objectstore::propagate_log must be called before objectstore::initialize. Most ObjectStore/Single applications will not need to use this entry point since propagation of the application's own log file, that is, the one specified by objectstore::set_log_file, happens automatically at initialization.
static os_unsigned_int32 release_maintenance();Returns the number following the second dot (.) in the number of the release of ObjectStore in use by the current application. For example, for Release 5.0.1, this function would return 1.
static os_unsigned_int32 release_major();Returns the number preceding the first dot (.) in the number of the release of ObjectStore in use by the current application. For example, for Release 5.0, this function would return 5.
static os_unsigned_int32 release_minor();Returns the number following the first dot (.) in the number of the release of ObjectStore in use by the current application. For example, for Release 5.0.1, this function would return 0.
static const char *release_name();Returns a string naming the release of ObjectStore in use, for example, "ObjectStore 5.0".
static void release_persistent_addresses();Globally disables retaining the validity of persistent addresses across transaction boundaries. Used in conjunction with objectstore::retain_persistent_addresses().
This function is callable within top-level transactions as well as outside of a transaction.
static void retain_persistent_addresses();Globally enables retaining the validity of persistent addresses across transaction boundaries. Must be called outside any transaction. Once executed within a given process, pointers to persistent memory remain valid even after the transaction in which they were retrieved from the database. This is true until the end of the process, or until objectstore::release_persistent_addresses() is called.
static os_unsigned_int32 return_all_pages();Clears the client cache.
static os_unsigned_int32 return_memory(
void *address,
os_unsigned_int32 length,
os_boolean evict_now
);
Gives the programmer control over cache replacement. The first two arguments designate a region of persistent memory; address is the beginning of the range and length is the length of the range in bytes. The function tells ObjectStore that this region of persistent memory is unlikely to be used again in the near future. If evict_now is nonzero (true), the pages are evicted from the cache immediately. If evict_now is 0 (false), the pages are not immediately evicted, but they are given highest priority for eviction (that is, they are treated as if they are the least recently used cache pages).
static void set_always_ignore_illegal_pointers(os_boolean);By default, ObjectStore signals an exception when it detects an illegal pointer (a pointer from persistent memory to transient memory or a cross-database pointer from a segment that is not in allow_external_pointers mode). Supplying a nonzero value specifies that illegal pointers should always be ignored by ObjectStore during the current process, provided the process is not in always_null_illegal_pointers mode. This includes illegal pointers detected during database reads as well as database writes.
static void set_always_null_illegal_pointers(os_boolean);Supplying a nonzero value specifies that illegal pointers should always be set to 0 when detected by ObjectStore during the current process. This includes illegal pointers detected during database reads as well as database writes.
static void set_application_schema_pathname(const char *path);Specifies the location of the application schema database. This function must be called before objectstore::initialize().
static os_autoload_DLLs_function set_autoload_DLLs_function(
os_autoload_DLLs_function fcn
);
You can set the hook function to a function that does nothing if you need to disable automatic loading of DLLs.
The default initial value of the hook function works as follows:
enum auto_open_mode_enum
{auto_open_read_only, auto_open_mvcc, auto_open_update,
auto_open_disable};
static void set_auto_open_mode(
auto_open_mode_enum mode = auto_open_update,
os_fetch_policy fp = os_fetch_page,
os_int32 bytes = 0);
Enables auto-open mode. This mode automatically opens any databases that need to be opened due to traversal of a reference or a cross-database-pointer. Specify the mode in which to open the database with one of the following enum values:
If a database is already open, a nested open is not done on that database. If auto-open mode is disabled, the error err_database_not_open is signaled upon an attempt to do an auto open.
Warning
Exercise extra caution if you have several databases open for MVCC at once. In particular, be aware that the databases will not necessarily be consistent with each other. Unless you are very careful, this could lead to unexpected results. objectstore::set_cache_file()
static void set_cache_file(
const char *cache_path,
os_boolean pre_allocate = 1
);
If the pre_allocate argument is nonzero (the default), the cache file is explicitly filled with zeros when it is opened. (See objectstore::set_cache_size()). Preallocation slows down start-up, but protects against obscure failures of mmap at critical times if the file system runs out of space.
If the pre_allocate argument is 0 (not the default) and an out-of-disk-space condition occurs when ObjectStore is trying to use a page in the cache file, the reported error is obscure (likely to be err_internal), and the diagnostic message does not say anything about disk space. The error message is most likely to complain about problems with mmap, page protections, or possibly page locks.
The call must precede objectstore::initialize. It takes precedence over the environment variable OS_CACHE_FILE. Be aware that if the file already exists, it is overwritten.
The cache file is not removed when the application ends. Normally, users should do so in the interest of conserving disk space.
Note that cache files can be reused but cannot be shared. An attempt to start an ObjectStore/Single application with a cache file that is already being used by another ObjectStore/Single application results in an error.
static void set_cache_size(os_unsigned_int32 new_cache_size);Sets the size of the client cache in bytes. The actual size is rounded down to the nearest whole number of pages. objectstore::set_cache_size must be called before objectstore::initialize(). Affects performance only.
static void set_check_illegal_pointers(os_boolean);If the argument is 1, this directs ObjectStore to create new databases in default_check_illegal_pointers mode. It also enables check_illegal_pointers mode for each database currently retrieved by the current process. See os_segment::set_check_illegal_pointers() and os_database::set_default_check_illegal_pointers().
objectstore::set_client_name()
static void set_client_name(char *new_name);Sets the name of the program that is running. Calling objectstore::set_client_name("program_name") during program initialization makes some of the output of the ObjectStore administrative/debugging commands (such as the -d option to the Server and the ossvrstat command) easier to understand. Must be called before objectstore::initialize().
static void set_commseg_size(os_unsigned_int32 bytes);Sets the size of the commseg in bytes. The actual size is rounded to the nearest whole number of pages. The commseg is a preallocated region on each ObjectStore client. It holds data used internally by ObjectStore, including cache indexing information and data that describes databases and segments used by the client.
The space requirements for the commseg are roughly as follows:
static void set_current_schema_key(
os_unsigned_int32 key_low,
os_unsigned_int32 key_high
);
Sets or unsets the schema key of the current application. Call this function only after calling objectstore::initialize(). Otherwise, err_schema_key is signaled and ObjectStore issues an error message like the following:
<err-0025-0153> The schema key may not be set until after objectstore::initialize has been called.key_low specifies the first component of the schema key, and key_high specifies the second component. If both these arguments are 0, calling this function causes the application's schema key to be determined as for an application that has not called this function.
If an application has not called this function, its key is determined by the values of the environment variables OS_SCHEMA_KEY_HIGH and OS_SCHEMA_KEY_LOW. If both the variables are not set, the application has no current schema key.
See Chapter 7, Database Access Control, in ObjectStore C++ API User Guide.
objectstore::set_eviction_batch_size()
static void set_eviction_batch_size(os_unsigned_int32);Sets the minimum number of bytes, rounded up to the nearest whole number of pages, evicted when ObjectStore needs to make room in the client cache, assuming there are enough candidates in the eviction pool. If you specify 0, a batch size of one page is used. If you specify a batch size greater than the size of the client cache, the number of pages in the client cache is used. If this function is not called, the batch size is one percent of the cache size, rounded up to the nearest whole number of pages.
static void set_eviction_pool_size(os_unsigned_int32);Sets the number of bytes, rounded up to the nearest whole number of pages, in the pool out of which an eviction batch is taken. If this function is not called, the batch size is 2% of the cache size rounded up to the nearest whole number of pages or 10 pages, whichever is larger.
static void set_handle_transient_faults(os_boolean);
static void set_incremental_schema_installation(os_boolean);If a nonzero value (true) is supplied as argument, the current application run will perform incremental schema installation on each database it accesses, regardless of the database's mode. In addition, databases subsequently created by the current execution of the application will be in incremental mode, and the schema of the creating application will be installed incrementally. With incremental schema installation, a class is added to a database's schema only when an instance of that class is first allocated in the database. If 0 (false) is supplied as argument, databases subsequently created by the current execution of the application will be in batch mode (the default). With batch mode, whenever an application creates or opens the database, every class in the application's schema is added to the database's schema (if not already present in the database schema).
static void set_locator_file(const char *file_name);The argument file_name points to the name of the locator file to be used the next time a database is opened. If 0 is supplied, the client environment variable OS_LOCATOR_FILE is used to determine the locator file to use. A nonzero argument overrides any setting of OS_LOCATOR_FILE. If the specified file does not exist err_locator_misc is signaled. If the first character of the string pointed to by file_name is a white-space character or #, the string is assumed to be the contents of a file rather than a file name.
static void set_log_file(const char *log_path);
If the file already exists, it must be a valid Server log created by an earlier execution of an ObjectStore/Single application. In that case, all committed data in that log is propagated during ObjectStore initialization.
The log file is normally removed at program termination or when objectstore::shutdown is called. If errors occur, the log might not be removed. In that event the user should consider the log to contain unpropagated data.
static void set_mapped_communications(os_boolean);Passing 1 enables mapped communications between client and Server. Passing 0 disables it. It is enabled by default. This function overrides the environment variable OS_NO_MAPPED. See ObjectStore Management.
static void set_null_illegal_pointers(os_boolean);If the argument is 1, this directs ObjectStore to create new databases in default_null_illegal_pointers mode. It also enables null_illegal_pointers mode for each database currently retrieved by the current process. See os_segment::set_null_illegal_pointers() and os_database::set_default_null_illegal_pointers().
objectstore::set_opt_cache_lock_mode()
static void set_opt_cache_lock_mode(os_boolean);A nonzero argument turns on opt_cache_lock_mode for the current process; a 0 argument turns the mode off.
Turning on this mode will improve performance for applications that perform database writes and expect little or no contention from other processes for access to persistent memory. When this mode is on, the amount of client/server communication required to upgrade locks is reduced. Once a page 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 might increase.
opt_cache_lock_mode is ignored during read-only transactions.
Note that this function sets the mode for the current process only, and does not affect the mode for other processes.
static void set_readlock_timeout(os_int32);Sets the time in milliseconds for which the current process will wait to acquire a read lock. The time is rounded up to the nearest whole number of seconds. A value of -1 indicates that the process should wait forever if necessary. After an attempt to acquire a read lock, if the specified time elapses without the lock's becoming available, an os_lock_timeout exception is signaled. If the attempt causes a deadlock, the transaction is aborted regardless of the value of the specified timeout.
static void set_reserve_as_mode(os_boolean new_mode);See the documentation for the environment variable OS_RESERVE_AS in ObjectStore Management.
static void set_simple_auth_ui(
void(*)(os_void_p, os_char_const_p, os_char_p,
os_int32, os_char_p, os_int32),
void*
);
Registers an authentication handler function. The first argument is a handler function that will be called by ObjectStore when the application first attempts to access a Server that requires Name Password authentication (see ObjectStore Management). The function is responsible for providing user name and password information.
The second argument is a data value that will be passed to the handler function when it is called.
The handler function has the following arguments: the first argument is the void* argument that was passed to objectstore::set_simple_auth_ui(). The second argument is the name of the Server host. The third and fourth arguments are a pointer to and length of a range of memory into which your function should put the user name. The fifth and sixth arguments are the same, for the password.
If no handler function is registered, the application issues a message to stdout requesting a user name and password, when first accessing a Server requiring Name Password authentication. By registering a handler function, you can, for example, use a dialog box instead of standard input and output to obtain authentication information from an end user.
static void set_thread_locking(os_boolean);To enable ObjectStore thread locking explicitly, pass a nonzero value. To disable ObjectStore thread locking, pass 0 to this function. If you disable ObjectStore thread locking while collections thread locking is enabled, collections thread locking remains enabled. You should disable collections thread locking as well.
If your application does not use multiple threads, disable thread locking with this function and os_collection::set_thread_locking().
If your application uses multiple threads, and the synchronization coded in your application allows two threads to be within the ObjectStore run time at the same time, you need ObjectStore thread locking enabled. See also os_collection::set_thread_locking() in the ObjectStore Collections C++ API Reference and os_transaction::begin().
objectstore::set_transaction_priority()
static void set_transaction_priority(os_unsigned_int16 priority);Every client has a transaction priority. The value is an unsigned number that can range from 0 to 0xffff. The default value is 0x8000 (which is right in the middle). Note that the value 0 is special, as described below.
When two clients deadlock, the transaction priority is used as part of the decision as to which client should be the victim, that is, which one should be forced to abort, and possibly restart, its transaction.
When it makes this decision, the first thing the Server does is to compare the transaction priorities of all the participants. If they do not all have equal priority, the ones with the higher priority are not considered as deadlock victims. That is, it looks at the lowest priority number of all the participants, and any participant with a higher priority number is no longer considered as a possible victim.
If there is only one participant left, it is the victim. Otherwise, if there are several participants that all share the same lowest priority number, it chooses a victim in accordance with the Server parameter Deadlock Victim. See ObjectStore Management.
There is one important special case. If all the participants have priority zero, the Server will victimize all the participants! This is not a useful mode of operation for actually running a program, but it can be useful for debugging: you can run several clients under debuggers, have them all set their priorities to zero, and then when a deadlock happens, all of them abort, and you can see what each one of them was doing. You should never use a priority of zero unless you want this special debugging behavior.
static void set_transient_delete_function(
void (*)(os_void_p)
);
Since ObjectStore redefines the global operator delete() so that it can take control of deletion of persistent objects, applications cannot provide their own overloaded global operator delete(). However, instead of overloading ::operator delete() to arrange for application-specific transient deallocation processing, applications can register a transient delete function by passing a pointer to the function to objectstore::set_transient_delete_function(). The specified function is user defined, and should do what the application's operator delete would have done. ObjectStore continues to provide the definition of ::operator delete(). When ObjectStore's ::operator delete() is given a transient pointer, and set_transient_delete_function() has been called, it calls the specified transient delete function on the transient pointer.The initial value of the delete function is 0, meaning that ObjectStore's ::operator delete() should ignore zero pointers and call free() (the architecture's native storage-freeing function) on the pointer. You can set the value back to 0 if you want to.
static void set_writelock_timeout(os_int32);Sets the time in milliseconds for which the current process will wait to acquire a write lock. The time is rounded up to the nearest whole number of seconds. A value of -1, the default, indicates that the process should wait forever if necessary. After an attempt to acquire a write lock, if the specified time elapses without the lock's becoming available, an os_lock_timeout_exception exception is signaled. If the attempt causes a deadlock, the transaction is aborted regardless of the value of the specified timeout.
static void shutdown();Conducts an orderly shutdown of ObjectStore. In particular, all open databases are closed to facilitate propagation of committed data from the Server log to the databases.
For ObjectStore/Single, this call attempts to propagate all committed data in the log and then to remove the log. However, if errors occur, the log might not be removed. In that event the user should consider the log to contain unpropagated data.
There should not be a transaction in progress when this entry point is called.
As currently implemented, ObjectStore cannot be restarted after this entry point is called. Object Design recommends that you use objectstore::shutdown for both full ObjectStore and ObjectStore/Single applications.
static void unload_DLL(os_DLL_handle h);If h designates a loaded DLL, unload it. If h is os_null_DLL_handle, do nothing. Otherwise the results are platform dependent.
If an operating system error occurs while the DLL is being unloaded, an err_DLL_not_unloaded exception can be thrown.
static os_product_type which_product();Always returns objectstore.
Updated: 03/31/98 17:25:09