C++ API Reference

C++ A P I Reference
Release 6.3
C++ A P I Reference
ObjectStore Release 6.3 for all platforms, October 2005
© 2005 Progress Software Corporation. All rights reserved.
Progress® software products are copyrighted and all rights are reserved by Progress Software Corporation. This
manual is also copyrighted and all rights are reserved. This manual may not, in whole or in part, be copied,
photocopied, translated, or reduced to any electronic medium or machine-readable form without prior consent, in
writing, from Progress Software Corporation.
The information in this manual is subject to change without notice, and Progress Software Corporation assumes
no responsibility for any errors that may appear in this document.
The references in this manual to specific platforms supported are subject to change.
A (and design), Allegrix, Allegrix (and design), Apama, Business Empowerment, DataDirect (and design),
DataDirect Connect, DataDirect Connect OLE DB, DirectAlert, EasyAsk, EdgeXtend, Empowerment Center,
eXcelon, Fathom,, IntelliStream, O (and design), ObjectStore, OpenEdge, PeerDirect, P.I.P., POSSENET, Powered
by Progress, Progress, Progress Dynamics, Progress Empowerment Center, Progress Empowerment Program,
Progress Fast Track, Progress OpenEdge, Partners in Progress, Partners en Progress, Persistence, Persistence (and
design), ProCare, Progress en Partners, Progress in Progress, Progress Profiles, Progress Results, Progress Software
Developers Network, ProtoSpeed, ProVision, SequeLink, SmartBeans, SpeedScript, Stylus Studio, Technical
Empowerment, WebSpeed, and Your Software, Our Technology-Experience the Connection are registered
trademarks of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and/or other
countries. AccelEvent, A Data Center of Your Very Own, AppsAlive, AppServer, ASPen, ASP-in-a-Box,
BusinessEdge, Cache-Forward, DataDirect, DataDirect Connect64, DataDirect Technologies, DataDirect XQuery,
DataXtend, Future Proof, ObjectCache, ObjectStore Event Engine, ObjectStore Inspector, ObjectStore Performance
Expert, POSSE, ProDataSet, Progress Business Empowerment, Progress DataXtend, Progress for Partners, Progress
ObjectStore, PSE Pro, PS Select, SectorAlliance, SmartBrowser, SmartComponent, SmartDataBrowser,
SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel,
SmartQuery, SmartViewer, SmartWindow, WebClient, and Who Makes Progress are trademarks or service marks
of Progress Software Corporation or one of its subsidiaries or affiliates in the U.S. and other countries. Java and all
Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other
countries. Any other trademarks or trade names contained herein are the property of their respective owners.
ObjectStore includes software developed by the Apache Software Foundation (http://www.apache.org/).
Copyright 2000-2003 The Apache Software Foundation. All rights reserved. The names "Ant," "Xerces," and
"Apache Software Foundation" must not be used to endorse or promote products derived from the Products
without prior written permission. Any product derived from the Products may not be called "Apache", nor may
"Apache" appear in their name, without prior written permission. For written permission, please contact
[email protected].
September 2005
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
ObjectStore Database Services . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 2
Class Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
ObjectStore classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
basic_undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
basic_undo::basic_undo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
basic_undo::get_exception() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
basic_undo::has_exception() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
basic_undo::~basic_undo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
objectstore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
objectstore::acquire_address_space(). . . . . . . . . . . . . . . . . . . . . . . . . 54
objectstore::acquire_lock() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
objectstore::add_missing_dispatch_table_handler() . . . . . . . . . . . . . . . 57
objectstore::change_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
objectstore::clear_persistent_to_transient_pointers() . . . . . . . . . . . . . . 58
objectstore::embedded_server_available() . . . . . . . . . . . . . . . . . . . . . 59
objectstore::enable_damaged_dope_repair(). . . . . . . . . . . . . . . . . . . . 59
objectstore::enable_DLL_schema(). . . . . . . . . . . . . . . . . . . . . . . . . . . 60
objectstore::export_object() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
objectstore::find_DLL_schema(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
objectstore::free_memory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
objectstore::get_address_space_generation_number() . . . . . . . . . . . . . 62
objectstore::get_all_servers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
objectstore::get_allocation_strategy() . . . . . . . . . . . . . . . . . . . . . . . . 62
objectstore::get_always_check_server_connection_at_commit() . . . . . . 63
objectstore::get_application_schema_pathname() . . . . . . . . . . . . . . . . 64
objectstore::get_as_intervals() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
objectstore::get_asmarkers_useless() . . . . . . . . . . . . . . . . . . . . . . . . 64
objectstore::get_auto_open_mode(). . . . . . . . . . . . . . . . . . . . . . . . . . 64
Release 6.3
3
Contents
objectstore::get_autoload_DLLs_function() . . . . . . . . . . . . . . . . . . . . . . 64
objectstore::get_cache_file(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
objectstore::get_cache_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
objectstore::get_client_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
objectstore::get_decache_soft_pointers_after_address_space_release() . 65
objectstore::get_default_address_space_partition_size() . . . . . . . . . . . . 65
objectstore::get_export_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
objectstore::get_fetch_policy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
objectstore::get_incremental_schema_installation(). . . . . . . . . . . . . . . . 67
objectstore::get_locator_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
objectstore::get_lock_option(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
objectstore::get_lock_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
objectstore::get_lock_timeout(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
objectstore::get_log_file(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
objectstore::get_n_servers() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
objectstore::get_null_illegal_pointers(). . . . . . . . . . . . . . . . . . . . . . . . . 69
objectstore::get_object_range() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
objectstore::get_page_size(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
objectstore::get_pointer_numbers(). . . . . . . . . . . . . . . . . . . . . . . . . . . 70
objectstore::get_propagate_on_commit() . . . . . . . . . . . . . . . . . . . . . . . 70
objectstore::get_retain_persistent_addresses() . . . . . . . . . . . . . . . . . . . 71
objectstore::get_simple_auth_ui() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
objectstore::get_suppress_invalid_hard_pointer_errors() . . . . . . . . . . . . 71
objectstore::get_transaction_max_retries() . . . . . . . . . . . . . . . . . . . . . 71
objectstore::get_transaction_priority() . . . . . . . . . . . . . . . . . . . . . . . . . 71
objectstore::get_transient_delete_function(). . . . . . . . . . . . . . . . . . . . . 72
objectstore::get_union_variant() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
objectstore::ignore_locator_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
objectstore::initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
objectstore::initialize_for_sessions() . . . . . . . . . . . . . . . . . . . . . . . . . . 73
objectstore::is_damaged_dope_repair_enabled(). . . . . . . . . . . . . . . . . . 75
objectstore::is_DLL_schema_enabled() . . . . . . . . . . . . . . . . . . . . . . . . 75
objectstore::is_multiple_session_mode() . . . . . . . . . . . . . . . . . . . . . . . 75
objectstore::is_persistent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
objectstore::is_single_session_mode() . . . . . . . . . . . . . . . . . . . . . . . . . 75
objectstore::is_unassigned_contiguous_address_space() . . . . . . . . . . . . 76
objectstore::load_DLL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
objectstore::lock_as_used. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
objectstore::lock_cluster_read. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
4
4
objectstore::lock_cluster_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
C++ A P I Reference
Contents
objectstore::lock_database_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
objectstore::lock_database_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
objectstore::lock_page_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
objectstore::lock_segment_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
objectstore::lock_segment_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
objectstore::lookup_DLL_symbol() . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
objectstore::network_servers_available() . . . . . . . . . . . . . . . . . . . . . . 79
objectstore::own_page_write. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
objectstore::propagate_log() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
objectstore::release_cleared_persistent_to_transient_pointers() . . . . . . 79
objectstore::release_maintenance() . . . . . . . . . . . . . . . . . . . . . . . . . . 80
objectstore::release_major() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
objectstore::release_minor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
objectstore::release_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
objectstore::release_persistent_addresses() . . . . . . . . . . . . . . . . . . . . 81
objectstore::reset_persistent_addresses() . . . . . . . . . . . . . . . . . . . . . . 81
objectstore::retain_persistent_addresses() . . . . . . . . . . . . . . . . . . . . . 81
objectstore::return_all_pages() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
objectstore::return_memory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
objectstore::set_allocation_strategy(). . . . . . . . . . . . . . . . . . . . . . . . . 82
objectstore::set_always_check_server_connection_at_commit() . . . . . . 82
objectstore::set_always_null_illegal_pointers() . . . . . . . . . . . . . . . . . . 83
objectstore::set_application_schema_pathname() . . . . . . . . . . . . . . . . 83
objectstore::set_asmarkers_useless(). . . . . . . . . . . . . . . . . . . . . . . . . 83
objectstore::set_autoload_DLLs_function() . . . . . . . . . . . . . . . . . . . . . 83
objectstore::set_auto_open_mode() . . . . . . . . . . . . . . . . . . . . . . . . . . 83
objectstore::set_cache_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
objectstore::set_cache_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
objectstore::set_client_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
objectstore::set_current_schema_key() . . . . . . . . . . . . . . . . . . . . . . . 86
objectstore::set_decache_soft_pointers_after_address_space_release() . 86
objectstore::set_default_address_space_partition_size() . . . . . . . . . . . 87
objectstore::set_fetch_policy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
objectstore::set_handle_transient_faults() . . . . . . . . . . . . . . . . . . . . . 88
objectstore::set_incremental_schema_installation() . . . . . . . . . . . . . . . 88
objectstore::set_locator_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
objectstore::set_lock_option() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
objectstore::set_lock_timeout() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
objectstore::set_log_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
objectstore::set_null_illegal_pointers() . . . . . . . . . . . . . . . . . . . . . . . . 90
Release 6.3
5
Contents
objectstore::set_pathname_encoding() . . . . . . . . . . . . . . . . . . . . . . . . 90
objectstore::set_persistent_to_transient_pointer(). . . . . . . . . . . . . . . . . 90
objectstore::set_propagate_on_commit() . . . . . . . . . . . . . . . . . . . . . . . 91
objectstore::set_reserve_as_mode() . . . . . . . . . . . . . . . . . . . . . . . . . . 91
objectstore::set_retain_persistent_addresses() . . . . . . . . . . . . . . . . . . . 91
objectstore::set_simple_auth_ui() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
objectstore::set_suppress_invalid_hard_pointer_errors() . . . . . . . . . . . . 92
objectstore::set_transaction_max_retries(). . . . . . . . . . . . . . . . . . . . . . 92
objectstore::set_transaction_priority() . . . . . . . . . . . . . . . . . . . . . . . . . 92
objectstore::set_transient_delete_function() . . . . . . . . . . . . . . . . . . . . . 93
objectstore::set_union_variant() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
objectstore::shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
objectstore::unload_DLL(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
objectstore::which_product() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
objectstore_exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
objectstore_exception::signal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
objectstore_exception::vsignal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
os_access_modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
os_access_modifier::create(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
os_access_modifier::get_base_member() . . . . . . . . . . . . . . . . . . . . . . . 97
os_access_modifier::set_base_member() . . . . . . . . . . . . . . . . . . . . . . . 97
os_address_space_marker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
os_address_space_marker::get_current(). . . . . . . . . . . . . . . . . . . . . . . 99
os_address_space_marker::get_level() . . . . . . . . . . . . . . . . . . . . . . . . 99
os_address_space_marker::get_next(). . . . . . . . . . . . . . . . . . . . . . . . . 99
os_address_space_marker::get_previous() . . . . . . . . . . . . . . . . . . . . . . 99
os_address_space_marker::of(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
os_address_space_marker::os_address_space_marker() . . . . . . . . . . . . 99
os_address_space_marker::release() . . . . . . . . . . . . . . . . . . . . . . . . . . 99
os_address_space_marker::retain() . . . . . . . . . . . . . . . . . . . . . . . . . . 100
os_address_space_marker::~os_address_space_marker() . . . . . . . . . . 100
os_anonymous_indirect_type . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
os_anonymous_indirect_type::create(). . . . . . . . . . . . . . . . . . . . . . . . 101
os_anonymous_indirect_type::get_target_type(). . . . . . . . . . . . . . . . . 101
os_anonymous_indirect_type::is_const() . . . . . . . . . . . . . . . . . . . . . . 101
os_anonymous_indirect_type::is_volatile() . . . . . . . . . . . . . . . . . . . . . 101
os_anonymous_indirect_type::set_is_const() . . . . . . . . . . . . . . . . . . . 101
os_anonymous_indirect_type::set_is_volatile( ) . . . . . . . . . . . . . . . . . . 101
os_app_schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
6
6
os_app_schema::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
C++ A P I Reference
Contents
os_application_schema_info . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
os_archiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
os_archiver::os_archiver(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
os_archiver::~os_archiver() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
os_archiver::add_db_to_archive() . . . . . . . . . . . . . . . . . . . . . . . . . . .104
os_archiver::change_time_interval() . . . . . . . . . . . . . . . . . . . . . . . . .104
os_archiver::get_current_archive_file_name() . . . . . . . . . . . . . . . . . . .104
os_archiver::get_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
os_archiver::remove_db_from_archive(). . . . . . . . . . . . . . . . . . . . . . .105
os_archiver::start_archiver() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
os_archiver::stop_archiver() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
os_archiver::take_a_snapshot() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
os_archiver_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
os_archiver_options::os_archiver_options(). . . . . . . . . . . . . . . . . . . . .107
os_archiver_options::~os_archiver_options() . . . . . . . . . . . . . . . . . . .107
os_archiver_options::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
os_array_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
os_array_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
os_array_type::get_element_type() . . . . . . . . . . . . . . . . . . . . . . . . . .108
os_array_type::get_number_of_elements(). . . . . . . . . . . . . . . . . . . . .108
os_array_type::set_element_type() . . . . . . . . . . . . . . . . . . . . . . . . . .108
os_array_type::set_number_of_elements() . . . . . . . . . . . . . . . . . . . . .108
os_authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
os_authentication::get_nt_registry_location() . . . . . . . . . . . . . . . . . . .109
os_authentication::set_nt_registry_location() . . . . . . . . . . . . . . . . . . .109
os_backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
os_backup::os_backup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
os_backup::~os_backup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
os_backup::get_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
os_backup::start_and_run_backup() . . . . . . . . . . . . . . . . . . . . . . . . .110
os_backup::start_backup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
os_backup::stop_backup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
os_backup_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
os_backup_options::os_backup_options() . . . . . . . . . . . . . . . . . . . . . .115
os_backup_options::~os_backup_options() . . . . . . . . . . . . . . . . . . . . .115
os_backup_options::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
os_base_class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
os_base_class::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
os_base_class::get_access() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
os_base_class::get_class() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Release 6.3
7
Contents
os_base_class::get_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
os_base_class::get_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
os_base_class::get_virtual_base_class_pointer_offset() . . . . . . . . . . . . 117
os_base_class::is_virtual() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
os_base_class::Private . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
os_base_class::Protected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
os_base_class::Public . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
os_base_class::set_access() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
os_base_class::set_class() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
os_base_class::set_offset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
os_base_class::set_virtual_base_class_no_pointer() . . . . . . . . . . . . . . 118
os_base_class::set_virtual_base_class_pointer_offset() . . . . . . . . . . . . 118
os_base_class::set_virtuals_redefined() . . . . . . . . . . . . . . . . . . . . . . . 118
os_base_class::virtual_base_class_has_pointer() . . . . . . . . . . . . . . . . 118
os_base_class::virtuals_redefined() . . . . . . . . . . . . . . . . . . . . . . . . . . 118
os_class_type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
os_class_type::Anonymous_union . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
os_class_type::Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
os_class_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
os_class_type::declares_get_os_typespec_function() . . . . . . . . . . . . . . 120
os_class_type::defines_virtual_functions() . . . . . . . . . . . . . . . . . . . . . 120
os_class_type::find_base_class() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
os_class_type::find_member_variable() . . . . . . . . . . . . . . . . . . . . . . . 120
os_class_type::get_access_of_get_os_typespec_function(). . . . . . . . . . 121
os_class_type::get_allocated_virtual_base_classes() . . . . . . . . . . . . . . 121
os_class_type::get_base_classes() . . . . . . . . . . . . . . . . . . . . . . . . . . 121
os_class_type::get_class_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
os_class_type::get_dispatch_table_pointer_offset() . . . . . . . . . . . . . . . 122
os_class_type::get_dispatch_table_pointer_offset_other_compiler() . . . 122
os_class_type::get_indirect_virtual_base_classes() . . . . . . . . . . . . . . . 122
os_class_type::get_members() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
os_class_type::get_most_derived_class() . . . . . . . . . . . . . . . . . . . . . . 123
os_class_type::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
os_class_type::get_pragmas(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
os_class_type::get_size_as_base() . . . . . . . . . . . . . . . . . . . . . . . . . . 125
os_class_type::get_source_position(). . . . . . . . . . . . . . . . . . . . . . . . . 125
os_class_type::has_constructor() . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
os_class_type::has_destructor() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
os_class_type::has_dispatch_table() . . . . . . . . . . . . . . . . . . . . . . . . . 126
8
8
os_class_type::has_dispatch_table_other_compiler() . . . . . . . . . . . . . . 126
C++ A P I Reference
Contents
os_class_type::introduces_virtual_functions() . . . . . . . . . . . . . . . . . . .126
os_class_type::is_abstract() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
os_class_type::is_forward_definition() . . . . . . . . . . . . . . . . . . . . . . . .126
os_class_type::is_persistent() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
os_class_type::is_template_class() . . . . . . . . . . . . . . . . . . . . . . . . . .126
os_class_type::operator os_instantiated_class_type&() . . . . . . . . . . . .127
os_class_type::set_access_of_get_os_typespec_function() . . . . . . . . . .127
os_class_type::set_base_classes() . . . . . . . . . . . . . . . . . . . . . . . . . . .127
os_class_type::set_class_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
os_class_type::set_declares_get_os_typespec_function() . . . . . . . . . . .127
os_class_type::set_defines_virtual_functions() . . . . . . . . . . . . . . . . . .127
os_class_type::set_dispatch_table_pointer_offset() . . . . . . . . . . . . . . .128
os_class_type::set_has_constructor() . . . . . . . . . . . . . . . . . . . . . . . . .128
os_class_type::set_has_destructor() . . . . . . . . . . . . . . . . . . . . . . . . .128
os_class_type::set_indirect_virtual_base_classes() . . . . . . . . . . . . . . .128
os_class_type::set_introduces_virtual_functions() . . . . . . . . . . . . . . . .128
os_class_type::set_is_abstract() . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
os_class_type::set_is_forward_definition() . . . . . . . . . . . . . . . . . . . . .128
os_class_type::set_is_persistent() . . . . . . . . . . . . . . . . . . . . . . . . . . .128
os_class_type::set_members() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
os_class_type::set_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
os_class_type::set_pragmas() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
os_class_type::set_source_position() . . . . . . . . . . . . . . . . . . . . . . . . .129
os_class_type::Struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
os_class_type::Union . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
os_close_database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
os_cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
os_cluster::database_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
os_cluster::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
os_cluster::get_allocation_strategy() . . . . . . . . . . . . . . . . . . . . . . . . .131
os_cluster::get_fetch_policy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
os_cluster::get_lock_option() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
os_cluster::get_null_illegal_pointers() . . . . . . . . . . . . . . . . . . . . . . . .132
os_cluster::get_number() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
os_cluster::get_transient_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . .133
os_cluster::is_deleted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
os_cluster::is_empty() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
os_cluster::is_transient_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
os_cluster::of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
os_cluster::release_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Release 6.3
9
Contents
os_cluster::retain_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
os_cluster::return_memory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
os_cluster::segment_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
os_cluster::session_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
os_cluster::set_allocation_strategy() . . . . . . . . . . . . . . . . . . . . . . . . . 135
os_cluster::set_fetch_policy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
os_cluster::set_lock_option() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
os_cluster::set_null_illegal_pointers() . . . . . . . . . . . . . . . . . . . . . . . . 136
os_cluster::set_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
os_cluster::size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
os_cluster::with() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
os_cluster_cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
os_cluster_cursor::os_cluster_cursor() . . . . . . . . . . . . . . . . . . . . . . . . 138
os_cluster_cursor::get_current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
os_cluster_cursor::next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
os_cluster_cursor::reset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
os_cluster_with . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
os_cluster_with::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
os_compact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
os_compact::augment_cluster_split_avoidance() . . . . . . . . . . . . . . . . . 141
os_compact::augment_post_compact_transformers() . . . . . . . . . . . . . 141
os_compact::compact() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
os_compact::initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
os_compact::set_address_space_release_interval() . . . . . . . . . . . . . . . 144
os_compact::set_avoid_page_boundary(). . . . . . . . . . . . . . . . . . . . . . 144
os_compact::set_explanation_level() . . . . . . . . . . . . . . . . . . . . . . . . . 144
os_compact::set_malloc_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
os_compact::set_maplet_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
os_compact::set_maximum_cluster_size() . . . . . . . . . . . . . . . . . . . . . 145
os_compact::set_maximum_memory_size() . . . . . . . . . . . . . . . . . . . . 145
os_compact::shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
os_comp_schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
os_comp_schema::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
os_database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
os_database::affiliate(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
os_database::change_affiliation() . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
os_database::change_schema_key() . . . . . . . . . . . . . . . . . . . . . . . . . 149
os_database::close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
os_database::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
10
10
os_database::create_root() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
C++ A P I Reference
Contents
os_database::create_segment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
os_database::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
os_database::find_root(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
os_database::freeze_schema_key() . . . . . . . . . . . . . . . . . . . . . . . . . .153
os_database::get_affiliated_databases() . . . . . . . . . . . . . . . . . . . . . . .154
os_database::get_affiliation_index_of() . . . . . . . . . . . . . . . . . . . . . . .154
os_database::get_all_databases() . . . . . . . . . . . . . . . . . . . . . . . . . . .154
os_database::get_all_roots() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
os_database::get_all_segments(). . . . . . . . . . . . . . . . . . . . . . . . . . . .155
os_database::get_all_segments_and_permissions() . . . . . . . . . . . . . . .155
os_database::get_allocation_strategy() . . . . . . . . . . . . . . . . . . . . . . .156
os_database::get_application_info() . . . . . . . . . . . . . . . . . . . . . . . . . .156
os_database::get_default_segment() . . . . . . . . . . . . . . . . . . . . . . . . .156
os_database::get_fetch_policy() . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
os_database::get_file_host_name() . . . . . . . . . . . . . . . . . . . . . . . . . .157
os_database::get_fragmentation() . . . . . . . . . . . . . . . . . . . . . . . . . . .157
os_database::get_host_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
os_database::get_incremental_schema_installation() . . . . . . . . . . . . . .158
os_database::get_lock_option() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
os_database::get_n_databases() . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
os_database::get_n_roots() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
os_database::get_n_segments() . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
os_database::get_new_segment_reference_policy(). . . . . . . . . . . . . . .159
os_database::get_null_illegal_pointers() . . . . . . . . . . . . . . . . . . . . . . .159
os_database::get_open_mode(). . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
os_database::get_path_to() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
os_database::get_pathname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
os_database::get_required_DLL_identifiers(). . . . . . . . . . . . . . . . . . . .160
os_database::get_schema_database() . . . . . . . . . . . . . . . . . . . . . . . .161
os_database::get_sector_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
os_database::get_segment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
os_database::get_segments() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
os_database::get_transient_database() . . . . . . . . . . . . . . . . . . . . . . .161
os_database::has_affiliation_to() . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
os_database::insert_required_DLL_identifier(). . . . . . . . . . . . . . . . . . .162
os_database::insert_required_DLL_identifiers() . . . . . . . . . . . . . . . . . .162
os_database::is_open(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .162
os_database::is_open_multi_db_mvcc() . . . . . . . . . . . . . . . . . . . . . . .162
os_database::is_open_mvcc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
os_database::is_open_read_only() . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Release 6.3
11
Contents
os_database::is_open_single_db_mvcc() . . . . . . . . . . . . . . . . . . . . . . 163
os_database::is_open_update(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
os_database::is_transient_database() . . . . . . . . . . . . . . . . . . . . . . . . 163
os_database::lookup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
os_database::of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
os_database::open() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
os_database::open_multi_db_mvcc() . . . . . . . . . . . . . . . . . . . . . . . . . 165
os_database::open_mvcc() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
os_database::release_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
os_database::retain_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
os_database::remove_required_DLL_identifier() . . . . . . . . . . . . . . . . . 167
os_database::return_memory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
os_database::session_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
os_database::set_allocation_strategy() . . . . . . . . . . . . . . . . . . . . . . . 168
os_database::set_application_info() . . . . . . . . . . . . . . . . . . . . . . . . . . 168
os_database::set_default_segment() . . . . . . . . . . . . . . . . . . . . . . . . . 168
os_database::set_fetch_policy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
os_database::set_incremental_schema_installation() . . . . . . . . . . . . . . 169
os_database::set_lock_option() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
os_database::set_new_segment_reference_policy(). . . . . . . . . . . . . . . 170
os_database::set_null_illegal_pointers() . . . . . . . . . . . . . . . . . . . . . . . 170
os_database::set_schema_database() . . . . . . . . . . . . . . . . . . . . . . . . 170
os_database::set_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
os_database::set_size_in_sectors() . . . . . . . . . . . . . . . . . . . . . . . . . . 171
os_database::size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
os_database::size_in_sectors() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
os_database::time_created(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
os_database_root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
os_database_root::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
os_database_root::find() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
os_database_root::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
os_database_root::get_typespec() . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
os_database_root::get_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
os_database_root::release_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . 173
os_database_root::retain_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . 173
os_database_root::set_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
os_database_root::~os_database_root() . . . . . . . . . . . . . . . . . . . . . . 174
os_database_schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
os_database_schema::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
12
12
os_database_schema::get_for_update() . . . . . . . . . . . . . . . . . . . . . . . 175
C++ A P I Reference
Contents
os_database_schema::install(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
os_Database_table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
os_Database_table::find_reference() . . . . . . . . . . . . . . . . . . . . . . . . .176
os_Database_table::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
os_Database_table::insert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
os_Database_table::is_ignored() . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
os_dbutil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
os_dbutil::chgrp() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
os_dbutil::chmod() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
os_dbutil::chown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
os_dbutil::close_all_connections() . . . . . . . . . . . . . . . . . . . . . . . . . . .179
os_dbutil::close_all_server_connections() . . . . . . . . . . . . . . . . . . . . . .179
os_dbutil::close_server_connection() . . . . . . . . . . . . . . . . . . . . . . . . .179
os_dbutil::cmgr_remove_file() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
os_dbutil::cmgr_shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
os_dbutil::cmgr_stat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
os_dbutil::compare_schemas() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181
os_dbutil::copy_database() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
os_dbutil::disk_free() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
os_dbutil::expand_global() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
os_dbutil::file_db_pathname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
os_dbutil::get_client_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
os_dbutil::get_sector_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
os_dbutil::hostof() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
os_dbutil::initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
os_dbutil::install_backrest_control_c_handler() . . . . . . . . . . . . . . . . . .183
os_dbutil::list_directory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
os_dbutil::make_link() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
os_dbutil::mkdir() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
os_dbutil::osdbcontrol() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
os_dbutil::ossize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
os_dbutil::osverifydb() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
os_dbutil::osverifydb_one_segment() . . . . . . . . . . . . . . . . . . . . . . . . .188
os_dbutil::rehost_all_links() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
os_dbutil::rehost_link(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
os_dbutil::remove() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
os_dbutil::rename() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
os_dbutil::rmdir(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
os_dbutil::set_application_schema_path(). . . . . . . . . . . . . . . . . . . . . .190
os_dbutil::set_client_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
Release 6.3
13
Contents
os_dbutil::split_pathname() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
os_dbutil::start_backrest_logging() . . . . . . . . . . . . . . . . . . . . . . . . . . 191
os_dbutil::stat(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
os_dbutil::stop_backrest_logging() . . . . . . . . . . . . . . . . . . . . . . . . . . 192
os_dbutil::svr_checkpoint(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
os_dbutil::svr_client_kill(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
os_dbutil::svr_debug() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
os_dbutil::svr_machine() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
os_dbutil::svr_ping() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
os_dbutil::svr_shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
os_dbutil::svr_stat() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
os_deadlock_exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
os_deadlock_exception::get_application_names() . . . . . . . . . . . . . . . . 203
os_deadlock_exception::get_fault_addr() . . . . . . . . . . . . . . . . . . . . . . 204
os_deadlock_exception::get_hostnames(). . . . . . . . . . . . . . . . . . . . . . 204
os_deadlock_exception::get_lock_type() . . . . . . . . . . . . . . . . . . . . . . 204
os_deadlock_exception::get_pids() . . . . . . . . . . . . . . . . . . . . . . . . . . 204
os_deadlock_exception::number_of_blockers() . . . . . . . . . . . . . . . . . . 204
os_DLL_finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
os_DLL_finder::equal_DLL_identifiers() . . . . . . . . . . . . . . . . . . . . . . . 205
os_DLL_finder::equal_DLL_identifiers_same_prefix() . . . . . . . . . . . . . . 205
os_DLL_finder::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
os_DLL_finder::load_DLL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
os_DLL_finder::register_() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
os_DLL_finder::unregister() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
os_DLL_schema_info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
os_DLL_schema_info::add_DLL_identifier(). . . . . . . . . . . . . . . . . . . . . 206
os_DLL_schema_info::DLL_loaded(). . . . . . . . . . . . . . . . . . . . . . . . . . 206
os_DLL_schema_info::DLL_unloaded() . . . . . . . . . . . . . . . . . . . . . . . . 207
os_Dumper_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
os_Dumper_reference::get_database() . . . . . . . . . . . . . . . . . . . . . . . 208
os_Dumper_reference::get_database_number() . . . . . . . . . . . . . . . . . 208
os_Dumper_reference::get_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . 208
os_Dumper_reference::get_segment() . . . . . . . . . . . . . . . . . . . . . . . . 208
os_Dumper_reference::get_segment_number() . . . . . . . . . . . . . . . . . 208
os_Dumper_reference::get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . 208
os_Dumper_reference::is_valid() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
os_Dumper_reference::operator void*() . . . . . . . . . . . . . . . . . . . . . . . 209
os_Dumper_reference::operator =() . . . . . . . . . . . . . . . . . . . . . . . . . 209
14
14
os_Dumper_reference::operator ==() . . . . . . . . . . . . . . . . . . . . . . . . 209
C++ A P I Reference
Contents
os_Dumper_reference::operator <(). . . . . . . . . . . . . . . . . . . . . . . . . .209
os_Dumper_reference::operator >(). . . . . . . . . . . . . . . . . . . . . . . . . .209
os_Dumper_reference::operator !=() . . . . . . . . . . . . . . . . . . . . . . . . .209
os_Dumper_reference::operator >=() . . . . . . . . . . . . . . . . . . . . . . . .210
os_Dumper_reference::operator <=() . . . . . . . . . . . . . . . . . . . . . . . .210
os_Dumper_reference::operator !() . . . . . . . . . . . . . . . . . . . . . . . . . .210
os_Dumper_reference::os_Dumper_reference(). . . . . . . . . . . . . . . . . .210
os_Dumper_reference::resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . .210
os_Dumper_specialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
os_Dumper_specialization::get_specialization_name() . . . . . . . . . . . . .211
os_Dumper_specialization::operator ()() . . . . . . . . . . . . . . . . . . . . . . .211
os_Dumper_specialization::should_use_default_constructor() . . . . . . . .212
os_dynamic_extent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
os_dynamic_extent::insert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
os_dynamic_extent::os_dynamic_extent() . . . . . . . . . . . . . . . . . . . . .213
os_dynamic_extent::~os_dynamic_extent() . . . . . . . . . . . . . . . . . . . .214
os_dynamic_extent::remove() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
os_enum_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
os_enum_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
os_enum_type::get_enumerator() . . . . . . . . . . . . . . . . . . . . . . . . . . .215
os_enum_type::get_enumerators() . . . . . . . . . . . . . . . . . . . . . . . . . .215
os_enum_type::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
os_enum_type::get_pragmas() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
os_enum_type::get_source_position() . . . . . . . . . . . . . . . . . . . . . . . .216
os_enum_type::set_enumerators() . . . . . . . . . . . . . . . . . . . . . . . . . .216
os_enum_type::set_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
os_enum_type::set_pragmas() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
os_enum_type::set_source_position() . . . . . . . . . . . . . . . . . . . . . . . .216
os_enumerator_literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
os_enumerator_literal::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
os_enumerator_literal::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . .217
os_enumerator_literal::get_value() . . . . . . . . . . . . . . . . . . . . . . . . . .217
os_enumerator_literal::set_name() . . . . . . . . . . . . . . . . . . . . . . . . . .217
os_enumerator_literal::set_value() . . . . . . . . . . . . . . . . . . . . . . . . . .217
os_evolve_subtype_fun_binding . . . . . . . . . . . . . . . . . . . . . . . . 218
os_evolve_subtype_fun_binding::os_evolve_subtype_fun_binding(). . . .218
os_export_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
os_export_id::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
os_export_id::get_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
os_export_id::is_null() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Release 6.3
15
Contents
os_export_id::operator ==() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
os_export_id_cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
os_export_id_cursor::get_current() . . . . . . . . . . . . . . . . . . . . . . . . . . 220
os_export_id_cursor::next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
os_export_id_cursor::os_export_id_cursor() . . . . . . . . . . . . . . . . . . . . 220
os_export_id_cursor::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
os_export_id_cursor::~os_export_id_cursor() . . . . . . . . . . . . . . . . . . . 221
os_failover_server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
os_failover_server::get_logical_server_hostname() . . . . . . . . . . . . . . . 222
os_failover_server::get_online_server_hostname() . . . . . . . . . . . . . . . 222
os_failover_server::get_reconnect_retry_interval() . . . . . . . . . . . . . . . 222
os_failover_server::get_reconnect_timeout() . . . . . . . . . . . . . . . . . . . 222
os_failover_server::set_reconnect_timeout_and_interval() . . . . . . . . . . 223
os_field_member_variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
os_field_member_variable::create(). . . . . . . . . . . . . . . . . . . . . . . . . . 224
os_field_member_variable::get_offset() . . . . . . . . . . . . . . . . . . . . . . . 224
os_field_member_variable::get_size() . . . . . . . . . . . . . . . . . . . . . . . . 224
os_field_member_variable::set_size() . . . . . . . . . . . . . . . . . . . . . . . . 224
os_Fixup_dumper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
os_Fixup_dumper::dump_info(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
os_Fixup_dumper::duplicate() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
os_Fixup_dumper::get_number_elements() . . . . . . . . . . . . . . . . . . . . 225
os_Fixup_dumper::get_object_to_fix() . . . . . . . . . . . . . . . . . . . . . . . . 225
os_Fixup_dumper::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
os_Fixup_dumper::~os_Fixup_dumper() . . . . . . . . . . . . . . . . . . . . . . 226
os_function_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
os_function_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
os_function_type::equal_signature() . . . . . . . . . . . . . . . . . . . . . . . . . 227
os_function_type::get_arg_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
os_function_type::get_arg_list_kind() . . . . . . . . . . . . . . . . . . . . . . . . 227
os_function_type::get_return_type() . . . . . . . . . . . . . . . . . . . . . . . . . 228
os_function_type::set_arg_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
os_function_type::set_arg_list_kind() . . . . . . . . . . . . . . . . . . . . . . . . 228
os_function_type::set_return_type() . . . . . . . . . . . . . . . . . . . . . . . . . 228
os_indirect_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
os_indirect_type::get_target_type(). . . . . . . . . . . . . . . . . . . . . . . . . . 229
os_indirect_type::set_target_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 229
os_instantiated_class_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
os_instantiated_class_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . 230
16
16
os_instantiated_class_type::get_instantiation() . . . . . . . . . . . . . . . . . . 230
C++ A P I Reference
Contents
os_instantiated_class_type::set_instantiation() . . . . . . . . . . . . . . . . . .230
os_int64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
os_int64::os_int64() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
os_int64::get_high(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
os_int64::get_low() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
os_int64::sprint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
os_integral_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
os_integral_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
os_integral_type::create_defaulted_char() . . . . . . . . . . . . . . . . . . . . .232
os_integral_type::create_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
os_integral_type::create_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
os_integral_type::create_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
os_integral_type::create_signed_char() . . . . . . . . . . . . . . . . . . . . . . .233
os_integral_type::create_unsigned_char() . . . . . . . . . . . . . . . . . . . . .233
os_integral_type::is_signed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
os_literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
os_literal::create_char() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_enum_literal() . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_pointer_literal() . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_signed_char(). . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_signed_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_signed_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_signed_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_unsigned_char() . . . . . . . . . . . . . . . . . . . . . . . . . . .234
os_literal::create_unsigned_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
os_literal::create_unsigned_long() . . . . . . . . . . . . . . . . . . . . . . . . . . .235
os_literal::create_unsigned_short() . . . . . . . . . . . . . . . . . . . . . . . . . .235
os_literal::create_wchar_t() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
os_literal::get_char_value(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
os_literal::get_enum_literal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
os_literal::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
os_literal::get_pointer_literal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
os_literal::get_signed_integral_value() . . . . . . . . . . . . . . . . . . . . . . . .236
os_literal::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
os_literal::get_unsigned_integral_value() . . . . . . . . . . . . . . . . . . . . . .236
os_literal::get_wchar_t_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
os_literal_template_actual_arg . . . . . . . . . . . . . . . . . . . . . . . . . 237
os_literal_template_actual_arg::create(). . . . . . . . . . . . . . . . . . . . . . .237
os_literal_template_actual_arg::get_literal() . . . . . . . . . . . . . . . . . . . .237
os_literal_template_actual_arg::set_literal() . . . . . . . . . . . . . . . . . . . .237
Release 6.3
17
Contents
os_lock_timeout_exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
os_lock_timeout_exception::get_application_names() . . . . . . . . . . . . . 238
os_lock_timeout_exception::get_fault_addr() . . . . . . . . . . . . . . . . . . . 238
os_lock_timeout_exception::get_hostnames(). . . . . . . . . . . . . . . . . . . 239
os_lock_timeout_exception::get_lock_type(). . . . . . . . . . . . . . . . . . . . 239
os_lock_timeout_exception::get_pids() . . . . . . . . . . . . . . . . . . . . . . . 239
os_lock_timeout_exception::number_of_blockers() . . . . . . . . . . . . . . . 239
os_member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
os_member::Access_modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
os_member::Field_variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
os_member::Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
os_member::get_access(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
os_member::get_defining_class() . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
os_member::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
os_member::is_unspecified() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
os_member::Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
os_member::operator const os_access_modifier&() . . . . . . . . . . . . . . . 241
os_member::operator const os_field_member_variable&() . . . . . . . . . . 241
os_member::operator const os_member_function&() . . . . . . . . . . . . . . 241
os_member::operator const os_member_type&() . . . . . . . . . . . . . . . . 241
os_member::operator const os_member_variable&() . . . . . . . . . . . . . . 241
os_member::operator const os_relationship_member_variable&() . . . . . 242
os_member::operator os_access_modifier&() . . . . . . . . . . . . . . . . . . . 242
os_member::operator os_field_member_variable&() . . . . . . . . . . . . . . 242
os_member::operator os_member_function&() . . . . . . . . . . . . . . . . . . 242
os_member::operator os_member_type&(). . . . . . . . . . . . . . . . . . . . . 242
os_member::operator os_member_variable&() . . . . . . . . . . . . . . . . . . 242
os_member::operator os_relationship_member_variable&() . . . . . . . . . 242
os_member::Private . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
os_member::Protected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
os_member::Public . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
os_member::Relationship . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
os_member::set_access() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
os_member::Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
os_member::Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
os_member_function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
os_member_function::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
os_member_function::get_call_linkage() . . . . . . . . . . . . . . . . . . . . . . 244
os_member_function::get_function_kind() . . . . . . . . . . . . . . . . . . . . . 244
18
18
os_member_function::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
C++ A P I Reference
Contents
os_member_function::get_source_position() . . . . . . . . . . . . . . . . . . . .245
os_member_function::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
os_member_function::is_const() . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
os_member_function::is_inline() . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
os_member_function::is_overloaded() . . . . . . . . . . . . . . . . . . . . . . . .245
os_member_function::is_pure_virtual() . . . . . . . . . . . . . . . . . . . . . . .245
os_member_function::is_static() . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
os_member_function::is_virtual() . . . . . . . . . . . . . . . . . . . . . . . . . . .246
os_member_function::is_volatile() . . . . . . . . . . . . . . . . . . . . . . . . . . .246
os_member_function::set_call_linkage() . . . . . . . . . . . . . . . . . . . . . . .246
os_member_function::set_is_const() . . . . . . . . . . . . . . . . . . . . . . . . .246
os_member_function::set_is_inline() . . . . . . . . . . . . . . . . . . . . . . . . .246
os_member_function::set_is_overloaded() . . . . . . . . . . . . . . . . . . . . .246
os_member_function::set_is_pure_virtual() . . . . . . . . . . . . . . . . . . . .246
os_member_function::set_is_static() . . . . . . . . . . . . . . . . . . . . . . . . .246
os_member_function::set_is_virtual() . . . . . . . . . . . . . . . . . . . . . . . .247
os_member_function::set_is_volatile() . . . . . . . . . . . . . . . . . . . . . . . .247
os_member_function::set_name() . . . . . . . . . . . . . . . . . . . . . . . . . . .247
os_member_function::set_source_position() . . . . . . . . . . . . . . . . . . . .247
os_member_function::set_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
os_member_namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
os_member_namespace::create() . . . . . . . . . . . . . . . . . . . . . . . . . . .248
os_member_namespace::get_namespace(). . . . . . . . . . . . . . . . . . . . .248
os_member_namespace::set_namespace() . . . . . . . . . . . . . . . . . . . . .248
os_member_type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
os_member_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
os_member_type::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
os_member_type::set_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
os_member_variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
os_member_variable::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
os_member_variable::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . .250
os_member_variable::get_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . .250
os_member_variable::get_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
os_member_variable::get_source_position() . . . . . . . . . . . . . . . . . . . .251
os_member_variable::get_storage_class() . . . . . . . . . . . . . . . . . . . . .251
os_member_variable::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
os_member_variable::is_field() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
os_member_variable::is_persistent() . . . . . . . . . . . . . . . . . . . . . . . . .251
os_member_variable::is_static() . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
os_member_variable::operator const os_field_member_variable&() . . . .252
Release 6.3
19
Contents
os_member_variable::operator const os_relationship_member_variable&()252
os_member_variable::operator os_field_member_variable&() . . . . . . . . 252
os_member_variable::operator os_relationship_member_variable&(). . . 252
os_member_variable::set_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
os_member_variable::set_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
os_member_variable::set_source_position() . . . . . . . . . . . . . . . . . . . . 252
os_member_variable::set_storage_class() . . . . . . . . . . . . . . . . . . . . . 253
os_member_variable::set_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
os_mop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
os_mop::bind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
os_mop::copy_classes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
os_mop::current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
os_mop::find_namespace(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
os_mop::find_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
os_mop::get_failure_classes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
os_mop::get_neutralized_classes() . . . . . . . . . . . . . . . . . . . . . . . . . . 255
os_mop::get_transient_schema() . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
os_mop::initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
os_mop::initialize_object_metadata(). . . . . . . . . . . . . . . . . . . . . . . . . 256
os_mop::reset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
os_named_indirect_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
os_named_indirect_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
os_named_indirect_type::get_name() . . . . . . . . . . . . . . . . . . . . . . . . 257
os_named_indirect_type::get_source_position() . . . . . . . . . . . . . . . . . 257
os_named_indirect_type::set_name() . . . . . . . . . . . . . . . . . . . . . . . . 257
os_named_indirect_type::set_source_position() . . . . . . . . . . . . . . . . . 257
os_namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
os_namespace::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
os_namespace::get_enclosing_namespace() . . . . . . . . . . . . . . . . . . . . 258
os_namespace::get_members(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
os_namespace::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
os_namespace::set_enclosing_namespace() . . . . . . . . . . . . . . . . . . . . 258
os_namespace::set_members() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
os_namespace::set_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
os_notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
os_notification::assign() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
os_notification::get_database() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
os_notification::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
os_notification::_get_fd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
20
20
os_notification::get_location() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
C++ A P I Reference
Contents
os_notification::get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261
os_notification::notify_immediate() . . . . . . . . . . . . . . . . . . . . . . . . . .261
os_notification::notify_on_commit() . . . . . . . . . . . . . . . . . . . . . . . . . .262
os_notification::os_notification() . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
os_notification::queue_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
os_notification::receive(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264
os_notification::set_queue_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
os_notification::subscribe() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
os_notification::unsubscribe() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266
os_object_cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
os_object_cursor::current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
os_object_cursor::first() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
os_object_cursor::more() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
os_object_cursor::next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
os_object_cursor::os_object_cursor() . . . . . . . . . . . . . . . . . . . . . . . . .269
os_object_cursor::release_address_space() . . . . . . . . . . . . . . . . . . . .269
os_object_cursor::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .269
os_object_cursor::set() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270
os_object_cursor::~os_object_cursor(). . . . . . . . . . . . . . . . . . . . . . . .270
os_path_to_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
os_path_to_data::add() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
os_path_to_data::bit_offset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
os_path_to_data::byte_offset(); . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
os_path_to_data::get_root() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
os_path_to_data::get_total_number_of_elements() . . . . . . . . . . . . . . .272
os_path_to_data::has_array_components() . . . . . . . . . . . . . . . . . . . .272
os_path_to_data::is_base_path () . . . . . . . . . . . . . . . . . . . . . . . . . . .272
os_path_to_data::is_member_variable_path(). . . . . . . . . . . . . . . . . . .272
os_path_to_data::local_path() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
os_path_to_data::make() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
os_path_to_data::minor_subscript(). . . . . . . . . . . . . . . . . . . . . . . . . .272
os_path_to_data::name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
os_path_to_data::outer_collocated_path() . . . . . . . . . . . . . . . . . . . . .273
os_path_to_data::outer_path() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
os_path_to_data::pop() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
os_path_to_data::to_bit_field() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
os_path_to_data::to_dope() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
os_path_to_data::to_static_member() . . . . . . . . . . . . . . . . . . . . . . . .273
os_path_to_data::to_subscript() . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
os_path_to_data::type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Release 6.3
21
Contents
os_path_to_data::unique_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
os_pathname_and_segment_number . . . . . . . . . . . . . . . . . . . . . 275
os_pathname_and_segment_number::database_pathname . . . . . . . . . 275
os_pathname_and_segment_number::os_pathname_and_segment_number()
275
os_pathname_and_segment_number::segment_number . . . . . . . . . . . 275
os_pathname_segment_cluster . . . . . . . . . . . . . . . . . . . . . . . . . 276
os_pathname_segment_cluster::database_pathname . . . . . . . . . . . . . 276
os_pathname_segment_cluster::os_pathname_segment_cluster() . . . . 276
os_pathname_segment_cluster::cluster_number . . . . . . . . . . . . . . . . . 276
os_pathname_segment_cluster::segment_number . . . . . . . . . . . . . . . 276
os_persistent_to_transient_pointer_manager. . . . . . . . . . . . . . . . 277
os_persistent_to_transient_pointer_manager::release() . . . . . . . . . . . . 277
os_Planning_action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
os_Planning_action::operator ()() . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
os_pointer_literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
os_pointer_literal::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
os_pointer_literal::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
os_pointer_literal::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
os_pointer_literal::set_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
os_pointer_literal::set_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
os_pointer_to_member_type . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
os_pointer_to_member_type::create() . . . . . . . . . . . . . . . . . . . . . . . . 280
os_pointer_to_member_type::get_target_class(). . . . . . . . . . . . . . . . . 280
os_pointer_to_member_type::set_target_class() . . . . . . . . . . . . . . . . . 280
os_pointer_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
os_pointer_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
os_pointer_type::get_target_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 281
os_pointer_type::set_target_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 281
os_pragma. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
os_pragma::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
os_pragma::get_string(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
os_pragma::is_recognized() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
os_rawfs_entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
os_rawfs_entry::get_abs_path() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
os_rawfs_entry::get_creation_time() . . . . . . . . . . . . . . . . . . . . . . . . . 283
os_rawfs_entry::get_group_name() . . . . . . . . . . . . . . . . . . . . . . . . . . 283
os_rawfs_entry::get_link_host() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
os_rawfs_entry::get_link_path() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
22
os_rawfs_entry::get_n_sectors() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
os_rawfs_entry::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
22
C++ A P I Reference
Contents
os_rawfs_entry::get_permission() . . . . . . . . . . . . . . . . . . . . . . . . . . .283
os_rawfs_entry::get_server_host(). . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::get_user_name() . . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::is_db() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::is_dir() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::is_link() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::operator =() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::os_rawfs_entry() . . . . . . . . . . . . . . . . . . . . . . . . . . .284
os_rawfs_entry::~os_rawfs_entry() . . . . . . . . . . . . . . . . . . . . . . . . . .285
os_rawfs_entry::OSU_DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
os_rawfs_entry::OSU_DIRECTORY . . . . . . . . . . . . . . . . . . . . . . . . . . .285
os_rawfs_entry::OSU_LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
os_real_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
os_real_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
os_real_type::create_double() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
os_real_type::create_float() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
os_real_type::create_long_double() . . . . . . . . . . . . . . . . . . . . . . . . . .286
os_recover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
os_recover::os_recover() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
os_recover::~os_recover() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
os_recover::get_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .287
os_recover::start_and_run_recover() . . . . . . . . . . . . . . . . . . . . . . . . .287
os_recover::start_recover() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
os_recover::stop_recover() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .288
os_recover_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
os_recover_options::os_recover_options() . . . . . . . . . . . . . . . . . . . . .292
os_recover_options::~os_recover_options() . . . . . . . . . . . . . . . . . . . .292
os_recover_options::reset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292
os_Reference<T> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
os_Reference<T>::get_os_typespec() . . . . . . . . . . . . . . . . . . . . . . . .293
os_Reference<T>::operator =(). . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
os_Reference<T>::operator !() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
os_Reference<T>::operator T*() . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
os_Reference<T>::operator –>() . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
os_Reference<T>::os_Reference() . . . . . . . . . . . . . . . . . . . . . . . . . . .294
os_Reference<T>::resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .294
os_Reference_cross_session<T> . . . . . . . . . . . . . . . . . . . . . . . . 295
os_Reference_cross_session<T>::get_os_typespec() . . . . . . . . . . . . . .295
os_Reference_cross_session<T>::operator =() . . . . . . . . . . . . . . . . . .295
Release 6.3
23
Contents
os_Reference_cross_session<T>::operator T*() . . . . . . . . . . . . . . . . . 295
os_Reference_cross_session<T>::operator –>() . . . . . . . . . . . . . . . . . 296
os_Reference_cross_session<T>::os_Reference_cross_session() . . . . . 296
os_Reference_cross_session<T>::resolve() . . . . . . . . . . . . . . . . . . . . 296
os_reference_cross_session . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
os_reference_cross_session::dump() . . . . . . . . . . . . . . . . . . . . . . . . . 298
os_reference_cross_session::get_database() . . . . . . . . . . . . . . . . . . . 298
os_reference_cross_session::load() . . . . . . . . . . . . . . . . . . . . . . . . . . 298
os_reference_cross_session::operator =() . . . . . . . . . . . . . . . . . . . . . 298
os_reference_cross_session::operator ==() . . . . . . . . . . . . . . . . . . . . 298
os_reference_cross_session::operator !() . . . . . . . . . . . . . . . . . . . . . . 298
os_reference_cross_session::operator !=() . . . . . . . . . . . . . . . . . . . . . 298
os_reference_cross_session::operator <() . . . . . . . . . . . . . . . . . . . . . 299
os_reference_cross_session::operator >() . . . . . . . . . . . . . . . . . . . . . 299
os_reference_cross_session::operator <=() . . . . . . . . . . . . . . . . . . . . 299
os_reference_cross_session::operator >=() . . . . . . . . . . . . . . . . . . . . 299
os_reference_cross_session::os_reference_cross_session() . . . . . . . . . 299
os_reference_cross_session::~os_reference_cross_session() . . . . . . . . 299
os_reference_cross_session::resolve() . . . . . . . . . . . . . . . . . . . . . . . . 300
os_reference_internal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
os_reference_internal::dump() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
os_reference_internal::get_database() . . . . . . . . . . . . . . . . . . . . . . . . 301
os_reference_internal::get_database_key() . . . . . . . . . . . . . . . . . . . . 301
os_reference_internal::hash() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
os_reference_internal::load() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
os_reference_internal::operator ==(). . . . . . . . . . . . . . . . . . . . . . . . . 302
os_reference_internal::operator !() . . . . . . . . . . . . . . . . . . . . . . . . . . 302
os_reference_internal::operator !=() . . . . . . . . . . . . . . . . . . . . . . . . . 302
os_reference_internal::operator <() . . . . . . . . . . . . . . . . . . . . . . . . . . 302
os_reference_internal::operator >() . . . . . . . . . . . . . . . . . . . . . . . . . . 303
os_reference_internal::operator <=(). . . . . . . . . . . . . . . . . . . . . . . . . 303
os_reference_internal::operator >=(). . . . . . . . . . . . . . . . . . . . . . . . . 303
os_reference_internal::~os_reference_internal() . . . . . . . . . . . . . . . . . 303
os_reference_internal::resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
os_Reference_protected<T> . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
os_Reference_protected<T>::get_os_typespec(). . . . . . . . . . . . . . . . . 304
os_Reference_protected<T>::operator =() . . . . . . . . . . . . . . . . . . . . . 304
os_Reference_protected<T>::operator T*() . . . . . . . . . . . . . . . . . . . . 305
os_Reference_protected<T>::operator –>() . . . . . . . . . . . . . . . . . . . . 305
24
24
os_Reference_protected<T>::os_Reference_protected() . . . . . . . . . . . 305
C++ A P I Reference
Contents
os_Reference_protected<T>::resolve(). . . . . . . . . . . . . . . . . . . . . . . .305
os_reference_protected_internal . . . . . . . . . . . . . . . . . . . . . . . . 306
os_reference_protected_internal::deleted() . . . . . . . . . . . . . . . . . . . . .306
os_reference_protected_internal::dump() . . . . . . . . . . . . . . . . . . . . . .306
os_reference_protected_internal::get_database() . . . . . . . . . . . . . . . .306
os_reference_protected_internal::get_database_key() . . . . . . . . . . . . .307
os_reference_protected_internal::hash(). . . . . . . . . . . . . . . . . . . . . . .307
os_reference_protected_internal::load() . . . . . . . . . . . . . . . . . . . . . . .307
os_reference_protected_internal::operator ==() . . . . . . . . . . . . . . . . .307
os_reference_protected_internal::operator !() . . . . . . . . . . . . . . . . . . .307
os_reference_protected_internal::operator !=() . . . . . . . . . . . . . . . . . .307
os_reference_protected_internal::operator <() . . . . . . . . . . . . . . . . . .308
os_reference_protected_internal::operator >() . . . . . . . . . . . . . . . . . .308
os_reference_protected_internal::operator <=() . . . . . . . . . . . . . . . . .308
os_reference_protected_internal::operator >=() . . . . . . . . . . . . . . . . .308
os_reference_protected_internal::~os_reference_protected_internal() . .308
os_reference_protected_internal::resolve() . . . . . . . . . . . . . . . . . . . . .309
os_reference_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
os_reference_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
os_relationship_member_variable . . . . . . . . . . . . . . . . . . . . . . . 311
os_relationship_member_variable::get_related_class(). . . . . . . . . . . . .311
os_relationship_member_variable::get_related_member() . . . . . . . . . .311
os_release_cluster_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
os_release_database_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . 313
os_release_root_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
os_release_segment_pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . 315
os_replicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
os_replicator::os_replicator(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
os_replicator::~os_replicator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
os_replicator::change_time_interval() . . . . . . . . . . . . . . . . . . . . . . . .316
os_replicator::get_statistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316
os_replicator::get_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
os_replicator::reset_statistics() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
os_replicator::start_replicator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
os_replicator::stop_replicator() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317
os_replicator_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
os_replicator_options::os_replicator_options(). . . . . . . . . . . . . . . . . . .320
os_replicator_options::~os_replicator_options() . . . . . . . . . . . . . . . . .320
os_replicator_options::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320
os_replicator_statistic_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
Release 6.3
25
Contents
os_replicator_statistic_info::os_replicator_statistic_info() . . . . . . . . . . . 321
os_replicator_statistic_info::~os_replicator_statistic_info(). . . . . . . . . . 322
os_replicator_statistic_info::format_and_print_statistics() . . . . . . . . . . 322
os_replicator_statistic_info::format_statistics() . . . . . . . . . . . . . . . . . . 322
os_replicator_statistic_info::get_replica_ID() . . . . . . . . . . . . . . . . . . . 322
os_restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
os_restore::os_restore() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
os_restore::~os_restore(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
os_restore::get_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
os_restore::start_and_run_restore() . . . . . . . . . . . . . . . . . . . . . . . . . 324
os_restore::start_restore() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
os_restore::stop_restore() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
os_restore_options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
os_restore_options::os_restore_options() . . . . . . . . . . . . . . . . . . . . . . 328
os_restore_options::~os_restore_options(). . . . . . . . . . . . . . . . . . . . . 328
os_restore_options::reset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
os_retain_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
os_retain_address::os_retain_address() . . . . . . . . . . . . . . . . . . . . . . . 329
os_retain_address::release() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
os_retain_address::retaining() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
os_retain_address::set_retain(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
os_schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
os_schema::find_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
os_schema::get_classes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
os_schema::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
os_schema::operator const os_app_schema&() . . . . . . . . . . . . . . . . . . 330
os_schema::operator const os_comp_schema&(). . . . . . . . . . . . . . . . . 330
os_schema::operator const os_database_schema&() . . . . . . . . . . . . . . 331
os_schema::operator os_app_schema&() . . . . . . . . . . . . . . . . . . . . . . 331
os_schema::operator os_comp_schema&() . . . . . . . . . . . . . . . . . . . . . 331
os_schema::operator os_database_schema&() . . . . . . . . . . . . . . . . . . 331
os_schema_evolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
os_schema_evolution::augment_classes_to_be_removed() . . . . . . . . . 335
os_schema_evolution::augment_cluster_split_avoidance() . . . . . . . . . . 335
os_schema_evolution::augment_dll_schema_db_names() . . . . . . . . . . 335
os_schema_evolution::augment_optional classes() . . . . . . . . . . . . . . . 336
os_schema_evolution::augment_pre_evol_transformers() . . . . . . . . . . 336
os_schema_evolution::augment_post_evol_transformers(). . . . . . . . . . 336
os_schema_evolution::evolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
26
26
os_schema_evolution::get_enclosing_object(). . . . . . . . . . . . . . . . . . . 340
C++ A P I Reference
Contents
os_schema_evolution::get_evolved_schema() . . . . . . . . . . . . . . . . . . .340
os_schema_evolution::get_evolved_schema_db_name() . . . . . . . . . . .340
os_schema_evolution::get_explanation_level() . . . . . . . . . . . . . . . . . .340
os_schema_evolution::get_path_to_member() . . . . . . . . . . . . . . . . . .340
os_schema_evolution::get_unevolved_schema() . . . . . . . . . . . . . . . . .341
os_schema_evolution::get_work_database() . . . . . . . . . . . . . . . . . . . .341
os_schema_evolution::initialize() . . . . . . . . . . . . . . . . . . . . . . . . . . . .341
os_schema_evolution::set_address_space_release_interval() . . . . . . . .341
os_schema_evolution::set_avoid_page_boundary() . . . . . . . . . . . . . . .341
os_schema_evolution::set_disable_transformer_class_checks(). . . . . . .342
os_schema_evolution::set_evolved_schema_db_name(). . . . . . . . . . . .342
os_schema_evolution::set_explanation_level() . . . . . . . . . . . . . . . . . .342
os_schema_evolution::set_malloc_size(). . . . . . . . . . . . . . . . . . . . . . .343
os_schema_evolution::set_maplet_size() . . . . . . . . . . . . . . . . . . . . . .343
os_schema_evolution::set_maximum_cluster_size() . . . . . . . . . . . . . .343
os_schema_evolution::set_maximum_memory_size() . . . . . . . . . . . . .343
os_schema_evolution::set_obsolete_index_handler() . . . . . . . . . . . . . .343
os_schema_evolution::set_obsolete_query_handler() . . . . . . . . . . . . . .343
os_schema_evolution::set_optimize_checkpoints(). . . . . . . . . . . . . . . .345
os_schema_evolution::set_pre_evolution_setup_hook() . . . . . . . . . . . .345
os_schema_evolution::set_resolve_ambiguous_void_pointers() . . . . . . .345
os_schema_evolution::set_task_list_file_name() . . . . . . . . . . . . . . . . .345
os_schema_evolution::set_untranslatable_pointer_handler(). . . . . . . . .345
os_schema_evolution::shutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . .345
os_schema_evolution::task_list() . . . . . . . . . . . . . . . . . . . . . . . . . . . .346
os_schema_handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
os_schema_handle::DLL_unloaded() . . . . . . . . . . . . . . . . . . . . . . . . .347
os_schema_handle::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347
os_schema_handle::get_all(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347
os_schema_handle::get_application_schema_handle() . . . . . . . . . . . . .348
os_schema_handle::get_DLL_identifiers() . . . . . . . . . . . . . . . . . . . . . .348
os_schema_handle::get_schema_database(). . . . . . . . . . . . . . . . . . . .348
os_schema_handle::get_schema_database_pathname() . . . . . . . . . . . .348
os_schema_handle::get_schema_info() . . . . . . . . . . . . . . . . . . . . . . .348
os_schema_handle::get_status() . . . . . . . . . . . . . . . . . . . . . . . . . . . .348
os_schema_handle::insert_required_DLL_identifiers() . . . . . . . . . . . . .349
os_schema_handle::set_schema_database_pathname() . . . . . . . . . . . .349
os_schema_handle::os_schema_handle_status . . . . . . . . . . . . . . . . . .349
os_schema_info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
os_schema_info::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350
Release 6.3
27
Contents
os_schema_info::get_DLL_identifiers() . . . . . . . . . . . . . . . . . . . . . . . . 350
os_schema_info::get_schema_database_pathname(). . . . . . . . . . . . . . 350
os_schema_info::set_schema_database_pathname() . . . . . . . . . . . . . . 350
os_schema_install_options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
os_schema_install_options::get_copy_member_functions() . . . . . . . . . 351
os_schema_install_options::os_schema_install_options() . . . . . . . . . . . 351
os_schema_install_options::set_copy_member_functions() . . . . . . . . . 351
os_segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
os_segment::create_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
os_segment::database_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
os_segment::destroy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
os_segment::get_access_control(). . . . . . . . . . . . . . . . . . . . . . . . . . . 352
os_segment::get_all_clusters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
os_segment::get_allocation_strategy(). . . . . . . . . . . . . . . . . . . . . . . . 353
os_segment::get_application_info() . . . . . . . . . . . . . . . . . . . . . . . . . . 353
os_segment::get_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
os_segment::get_clusters(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
os_segment::get_comment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
os_segment::get_default_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . 354
os_segment::get_export_ids(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
os_segment::get_fetch_policy(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
os_segment::get_lock_option() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
os_segment::get_n_clusters() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
os_segment::get_null_illegal_pointers() . . . . . . . . . . . . . . . . . . . . . . . 356
os_segment::get_number(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
os_segment::get_segment_reference_policy() . . . . . . . . . . . . . . . . . . 357
os_segment::get_transient_segment() . . . . . . . . . . . . . . . . . . . . . . . . 357
os_segment::is_deleted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
os_segment::is_empty() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
os_segment::is_transient_segment() . . . . . . . . . . . . . . . . . . . . . . . . . 357
os_segment::of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
os_segment::release_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
os_segment::resolve_export_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
os_segment::retain_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
os_segment::return_memory() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
os_segment::session_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
os_segment::set_access_control() . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
os_segment::set_allocation_strategy() . . . . . . . . . . . . . . . . . . . . . . . . 359
os_segment::set_application_info() . . . . . . . . . . . . . . . . . . . . . . . . . . 360
28
28
os_segment::set_comment(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
C++ A P I Reference
Contents
os_segment::set_default_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . .360
os_segment::set_fetch_policy() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360
os_segment::set_lock_option() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
os_segment::set_null_illegal_pointers() . . . . . . . . . . . . . . . . . . . . . . .361
os_segment::size(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .361
os_segment_access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
os_segment_access::get_default() . . . . . . . . . . . . . . . . . . . . . . . . . . .362
os_segment_access::get_primary_group() . . . . . . . . . . . . . . . . . . . . .362
os_segment_access::no_access . . . . . . . . . . . . . . . . . . . . . . . . . . . . .362
os_segment_access::operator =() . . . . . . . . . . . . . . . . . . . . . . . . . . .363
os_segment_access::os_segment_access() . . . . . . . . . . . . . . . . . . . . .363
os_segment_access::read_access . . . . . . . . . . . . . . . . . . . . . . . . . . .363
os_segment_access::read_write_access . . . . . . . . . . . . . . . . . . . . . . .363
os_segment_access::set_default() . . . . . . . . . . . . . . . . . . . . . . . . . . .364
os_segment_access::set_primary_group() . . . . . . . . . . . . . . . . . . . . .364
os_segment_access::~os_segment_access() . . . . . . . . . . . . . . . . . . . .364
os_segment_cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
os_segment_cursor::os_segment_cursor() . . . . . . . . . . . . . . . . . . . . .365
os_segment_cursor::get_current() . . . . . . . . . . . . . . . . . . . . . . . . . . .365
os_segment_cursor::next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365
os_segment_cursor::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .366
os_server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
os_server::connection_is_broken(). . . . . . . . . . . . . . . . . . . . . . . . . . .367
os_server::disconnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368
os_server::get_databases() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368
os_server::get_host_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368
os_server::get_n_databases() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .368
os_server::is_failover() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
os_server::reconnect() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
os_session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
os_session::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
os_session::force_full_initialization() . . . . . . . . . . . . . . . . . . . . . . . . .370
os_session::get_all_sessions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
os_session::get_current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .370
os_session::get_n_sessions() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
os_session::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
os_session::get_thread_absorption() . . . . . . . . . . . . . . . . . . . . . . . . .371
os_session::of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
os_session::operator delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .371
os_session::set_current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .372
Release 6.3
29
Contents
os_session::set_thread_absorption() . . . . . . . . . . . . . . . . . . . . . . . . . 372
os_session::unuse_DLL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
os_session::use_DLL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
os_soft_pointer32_base. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
os_soft_pointer32_base::decache() . . . . . . . . . . . . . . . . . . . . . . . . . . 373
os_soft_pointer32_base::dump() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
os_soft_pointer32_base::get_database() . . . . . . . . . . . . . . . . . . . . . . 374
os_soft_pointer32_base::get_database_key() . . . . . . . . . . . . . . . . . . . 374
os_soft_pointer32_base::get_open_database() . . . . . . . . . . . . . . . . . . 374
os_soft_pointer32_base::hash() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
os_soft_pointer32_base::load() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
os_soft_pointer32_base::operator ==() . . . . . . . . . . . . . . . . . . . . . . . 375
os_soft_pointer32_base::operator !() . . . . . . . . . . . . . . . . . . . . . . . . . 375
os_soft_pointer32_base::operator !=(). . . . . . . . . . . . . . . . . . . . . . . . 375
os_soft_pointer32_base::operator <() . . . . . . . . . . . . . . . . . . . . . . . . 375
os_soft_pointer32_base::operator >() . . . . . . . . . . . . . . . . . . . . . . . . 375
os_soft_pointer32_base::operator <=() . . . . . . . . . . . . . . . . . . . . . . . 376
os_soft_pointer32_base::operator >=() . . . . . . . . . . . . . . . . . . . . . . . 376
os_soft_pointer32_base::~os_soft_pointer32_base() . . . . . . . . . . . . . . 376
os_soft_pointer32_base::resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
os_soft_pointer64_base. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
os_soft_pointer64_base::decache() . . . . . . . . . . . . . . . . . . . . . . . . . . 377
os_soft_pointer64_base::dump() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
os_soft_pointer64_base::get_database() . . . . . . . . . . . . . . . . . . . . . . 378
os_soft_pointer64_base::get_database_key() . . . . . . . . . . . . . . . . . . . 378
os_soft_pointer64_base::get_open_database() . . . . . . . . . . . . . . . . . . 378
os_soft_pointer64_base::hash() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
os_soft_pointer64_base::load() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
os_soft_pointer64_base::operator ==() . . . . . . . . . . . . . . . . . . . . . . . 379
os_soft_pointer64_base::operator !() . . . . . . . . . . . . . . . . . . . . . . . . . 379
os_soft_pointer64_base::operator !=(). . . . . . . . . . . . . . . . . . . . . . . . 379
os_soft_pointer64_base::operator <() . . . . . . . . . . . . . . . . . . . . . . . . 379
os_soft_pointer64_base::operator >() . . . . . . . . . . . . . . . . . . . . . . . . 379
os_soft_pointer64_base::operator <=() . . . . . . . . . . . . . . . . . . . . . . . 380
os_soft_pointer64_base::operator >=() . . . . . . . . . . . . . . . . . . . . . . . 380
os_soft_pointer64_base::~os_soft_pointer64_base() . . . . . . . . . . . . . . 380
os_soft_pointer64_base::resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
os_soft_pointer32<T>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
os_soft_pointer32<T>::operator =() . . . . . . . . . . . . . . . . . . . . . . . . . 382
30
30
os_soft_pointer32<T>::operator T*(). . . . . . . . . . . . . . . . . . . . . . . . . 382
C++ A P I Reference
Contents
os_soft_pointer32<T>::operator –>() . . . . . . . . . . . . . . . . . . . . . . . .382
os_soft_pointer32<T>::os_soft_pointer32() . . . . . . . . . . . . . . . . . . . .382
os_soft_pointer32<T>::resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
os_soft_pointer64<T> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
os_soft_pointer64<T>::operator =() . . . . . . . . . . . . . . . . . . . . . . . . .385
os_soft_pointer64<T>::operator T*() . . . . . . . . . . . . . . . . . . . . . . . . .385
os_soft_pointer64<T>::operator –>() . . . . . . . . . . . . . . . . . . . . . . . .385
os_soft_pointer64<T>::os_soft_pointer64() . . . . . . . . . . . . . . . . . . . .385
os_soft_pointer64<T>::resolve() . . . . . . . . . . . . . . . . . . . . . . . . . . . .386
os_soft_pointer32<void> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
os_soft_pointer64<void> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
os_soft_pointer32<char> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
os_soft_pointer64<char> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
os_str_conv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
os_str_conv::change_mapping() . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
os_str_conv::convert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .391
os_str_conv::get_converted_size(). . . . . . . . . . . . . . . . . . . . . . . . . . .392
os_str_conv::os_str_conv() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .393
os_string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
os_string::compare() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
os_string::compare_nocase(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
os_string::is_null() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
os_string::operator const char*() . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
os_string::operator =() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .394
os_string::os_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
os_string::~os_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
os_subscription . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
os_subscription::assign() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396
os_subscription::get_database() . . . . . . . . . . . . . . . . . . . . . . . . . . . .397
os_subscription::operator=() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397
os_subscription::os_subscription() . . . . . . . . . . . . . . . . . . . . . . . . . . .398
os_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
os_template::Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399
os_template::get_args() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399
os_template::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399
os_template::is_unspecified() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .399
os_template::operator const os_type_template&() . . . . . . . . . . . . . . . .399
os_template::operator os_type_template&() . . . . . . . . . . . . . . . . . . . .400
os_template::set_args() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400
os_template::Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .400
Release 6.3
31
Contents
os_template_actual_arg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
os_template_actual_arg::get_kind(). . . . . . . . . . . . . . . . . . . . . . . . . . 401
os_template_actual_arg::operator const os_literal_template_actual_arg&()401
os_template_actual_arg::operator const os_type_template_actual_arg&()401
os_template_actual_arg::operator os_literal_template_actual_arg&() . . 401
os_template_actual_arg::operator os_type_template_actual_arg&() . . . 402
os_template_formal_arg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
os_template_formal_arg::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . 403
os_template_formal_arg::get_name() . . . . . . . . . . . . . . . . . . . . . . . . 403
os_template_formal_arg::operator const os_template_type_formal&(). . 403
os_template_formal_arg::operator const os_template_value_formal&() . 403
os_template_formal_arg::operator os_template_type_formal&() . . . . . . 403
os_template_formal_arg::operator os_template_value_formal&() . . . . . 403
os_template_formal_arg::set_name() . . . . . . . . . . . . . . . . . . . . . . . . 404
os_template_instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
os_template_instantiation::create() . . . . . . . . . . . . . . . . . . . . . . . . . . 405
os_template_instantiation::get_args() . . . . . . . . . . . . . . . . . . . . . . . . 405
os_template_instantiation::get_template() . . . . . . . . . . . . . . . . . . . . . 405
os_template_instantiation::set_args() . . . . . . . . . . . . . . . . . . . . . . . . 405
os_template_instantiation::set_template() . . . . . . . . . . . . . . . . . . . . . 406
os_template_type_formal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
os_template_type_formal::create() . . . . . . . . . . . . . . . . . . . . . . . . . . 407
os_template_value_formal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
os_template_value_formal::create() . . . . . . . . . . . . . . . . . . . . . . . . . 408
os_template_value_formal::get_type(). . . . . . . . . . . . . . . . . . . . . . . . 408
os_template_value_formal::set_type() . . . . . . . . . . . . . . . . . . . . . . . . 408
os_transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
os_transaction::abort(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
os_transaction::abort_top_level() . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
os_transaction::begin() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
os_transaction::checkpoint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
os_transaction::commit() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
os_transaction::get_current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
os_transaction::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
os_transaction::get_parent(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
os_transaction::get_scope() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
os_transaction::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
os_transaction::is_aborted() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
os_transaction::is_committed() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
32
32
os_transaction::is_lock_contention() . . . . . . . . . . . . . . . . . . . . . . . . . 412
C++ A P I Reference
Contents
os_transaction::is_prepared() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .412
os_transaction::prepare_to_commit() . . . . . . . . . . . . . . . . . . . . . . . . .412
os_transaction::read_only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
os_transaction::session_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
os_transaction::set_name(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
os_transaction::top_level() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .413
os_transaction::update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .414
os_transaction_hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
os_transaction_hook::after_begin . . . . . . . . . . . . . . . . . . . . . . . . . . .415
os_transaction_hook::after_checkpoint . . . . . . . . . . . . . . . . . . . . . . . .415
os_transaction_hook::after_commit . . . . . . . . . . . . . . . . . . . . . . . . . .415
os_transaction_hook::before_abort . . . . . . . . . . . . . . . . . . . . . . . . . .415
os_transaction_hook::before_checkpoint. . . . . . . . . . . . . . . . . . . . . . .415
os_transaction_hook::before_commit . . . . . . . . . . . . . . . . . . . . . . . . .416
os_transaction_hook::before_retry . . . . . . . . . . . . . . . . . . . . . . . . . . .416
os_transaction_hook::deregister_hook() . . . . . . . . . . . . . . . . . . . . . . .416
os_transaction_hook::register_hook(). . . . . . . . . . . . . . . . . . . . . . . . .416
os_transformer_binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
os_transformer_binding::os_transformer_binding() . . . . . . . . . . . . . . .417
os_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
os_type::Anonymous_indirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::Char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::Double. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::Enum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::Float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .418
os_type::get_alignment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
os_type::get_enclosing_class() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
os_type::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
os_type::get_kind_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::get_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::get_string() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::Instantiated_class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::is_class_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::is_const(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::is_indirect_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
os_type::is_integral_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .420
Release 6.3
33
Contents
os_type::is_pointer_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
os_type::is_real_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
os_type::is_unspecified() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
os_type::is_volatile() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
os_type::Long_double . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
os_type::Named_indirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
os_type::operator const os_anonymous_indirect_type&() . . . . . . . . . . . 421
os_type::operator const os_array_type&() . . . . . . . . . . . . . . . . . . . . . 422
os_type::operator const os_class_type&(). . . . . . . . . . . . . . . . . . . . . . 422
os_type::operator const os_enum_type&() . . . . . . . . . . . . . . . . . . . . . 422
os_type::operator const os_function_type&() . . . . . . . . . . . . . . . . . . . 422
os_type::operator const os_instantiated_class_type&() . . . . . . . . . . . . 422
os_type::operator const os_integral_type&(). . . . . . . . . . . . . . . . . . . . 422
os_type::operator const os_named_indirect_type&() . . . . . . . . . . . . . . 422
os_type::operator const os_pointer_to_member_type&() . . . . . . . . . . . 422
os_type::operator const os_pointer_type&() . . . . . . . . . . . . . . . . . . . . 423
os_type::operator const os_real_type&() . . . . . . . . . . . . . . . . . . . . . . 423
os_type::operator const os_reference_type&() . . . . . . . . . . . . . . . . . . 423
os_type::operator const os_type_type&() . . . . . . . . . . . . . . . . . . . . . . 423
os_type::operator const os_void_type&() . . . . . . . . . . . . . . . . . . . . . . 423
os_type::operator os_anonymous_indirect_type&() . . . . . . . . . . . . . . . 423
os_type::operator os_array_type&() . . . . . . . . . . . . . . . . . . . . . . . . . 423
os_type::operator os_class_type&() . . . . . . . . . . . . . . . . . . . . . . . . . . 423
os_type::operator os_enum_type&() . . . . . . . . . . . . . . . . . . . . . . . . . 424
os_type::operator os_function_type&() . . . . . . . . . . . . . . . . . . . . . . . 424
os_type::operator os_instantiated_class_type&(). . . . . . . . . . . . . . . . . 424
os_type::operator os_integral_type&() . . . . . . . . . . . . . . . . . . . . . . . . 424
os_type::operator os_named_indirect_type&() . . . . . . . . . . . . . . . . . . 424
os_type::operator os_pointer_to_member_type&() . . . . . . . . . . . . . . . 424
os_type::operator os_pointer_type&() . . . . . . . . . . . . . . . . . . . . . . . . 424
os_type::operator os_real_type&() . . . . . . . . . . . . . . . . . . . . . . . . . . 424
os_type::operator os_reference_type&(). . . . . . . . . . . . . . . . . . . . . . . 425
os_type::operator os_type_type&() . . . . . . . . . . . . . . . . . . . . . . . . . . 425
os_type::operator os_void_type&() . . . . . . . . . . . . . . . . . . . . . . . . . . 425
os_type::Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
os_type::Pointer_to_member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
os_type::Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
os_type::set_alignment() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
os_type::set_size() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
34
34
os_type::Signed_char. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
C++ A P I Reference
Contents
os_type::Signed_long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .426
os_type::Signed_short . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .426
os_type::strip_indirect_types() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .426
os_type::Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
os_type::type_at() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
os_type::type_containing() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
os_type::Undefined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
os_type::Unsigned_char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
os_type::Unsigned_integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .427
os_type::Unsigned_long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428
os_type::Unsigned_short. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428
os_type::Void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .428
os_Type_fixup_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
os_Type_fixup_info::fixup_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .429
os_Type_fixup_info::os_Type_fixup_info() . . . . . . . . . . . . . . . . . . . . .429
os_Type_fixup_loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
os_Type_fixup_loader::fixup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .430
os_Type_fixup_loader::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .430
os_Type_fixup_loader::load() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .431
os_Type_fixup_loader::operator ()(). . . . . . . . . . . . . . . . . . . . . . . . . .431
os_Type_info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
os_Type_info::data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .432
os_Type_info::get_original_location() . . . . . . . . . . . . . . . . . . . . . . . . .432
os_Type_info::get_replacing_database() . . . . . . . . . . . . . . . . . . . . . . .432
os_Type_info::get_replacing_location(). . . . . . . . . . . . . . . . . . . . . . . .432
os_Type_info::get_replacing_segment() . . . . . . . . . . . . . . . . . . . . . . .432
os_Type_info::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433
os_Type_info::os_Type_info() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .433
os_Type_info::set_replacing_location() . . . . . . . . . . . . . . . . . . . . . . . .433
os_Type_loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434
os_Type_loader::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .434
os_Type_loader::fixup() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .434
os_Type_loader::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .434
os_Type_loader::load() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435
os_Type_loader::operator ()() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .435
os_type_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
os_type_template::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436
os_type_template::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436
os_type_template::set_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .436
os_type_template_actual_arg . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Release 6.3
35
Contents
os_type_template_actual_arg::create() . . . . . . . . . . . . . . . . . . . . . . . 437
os_type_template_actual_arg::get_type() . . . . . . . . . . . . . . . . . . . . . 437
os_type_template_actual_arg::set_type(). . . . . . . . . . . . . . . . . . . . . . 437
os_type_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
os_typed_pointer_void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
os_typed_pointer_void::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 439
os_typed_pointer_void::operator void*() . . . . . . . . . . . . . . . . . . . . . . 439
os_typespec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
os_typespec::get_char() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
os_typespec::get_double() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
os_typespec::get_float() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
os_typespec::get_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
os_typespec::get_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
os_typespec::get_long_double() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
os_typespec::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
os_typespec::get_os_int16() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
os_typespec::get_os_int32() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
os_typespec::get_os_int64() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
os_typespec::get_os_signed_int8() . . . . . . . . . . . . . . . . . . . . . . . . . . 442
os_typespec::get_os_unsigned_int8() . . . . . . . . . . . . . . . . . . . . . . . . 442
os_typespec::get_os_unsigned_int16() . . . . . . . . . . . . . . . . . . . . . . . 442
os_typespec::get_os_unsigned_int32() . . . . . . . . . . . . . . . . . . . . . . . 442
os_typespec::get_os_unsigned_int64() . . . . . . . . . . . . . . . . . . . . . . . 442
os_typespec::get_pointer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
os_typespec::get_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
os_typespec::get_signed_char() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
os_typespec::get_signed_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
os_typespec::get_signed_long() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
os_typespec::get_signed_short() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
os_typespec::get_unsigned_char() . . . . . . . . . . . . . . . . . . . . . . . . . . 444
os_typespec::get_unsigned_int() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
os_typespec::get_unsigned_long(). . . . . . . . . . . . . . . . . . . . . . . . . . . 444
os_typespec::get_unsigned_short() . . . . . . . . . . . . . . . . . . . . . . . . . . 444
os_typespec::operator ==() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
os_typespec::os_typespec() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
os_unsigned_int64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
os_unsigned_int64::os_unsigned_int64() . . . . . . . . . . . . . . . . . . . . . . 446
os_unsigned_int64::get_high() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
os_unsigned_int64::get_low() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
36
36
os_unsigned_int64::sprint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
C++ A P I Reference
Contents
os_untranslatable_pointer_handler . . . . . . . . . . . . . . . . . . . . . . 448
os_untranslatable_pointer_handler::clone(). . . . . . . . . . . . . . . . . . . . .448
os_untranslatable_pointer_handler::get_exception() . . . . . . . . . . . . . .448
os_untranslatable_pointer_handler::get_explanation() . . . . . . . . . . . . .448
os_untranslatable_pointer_handler::get_source_cluster() . . . . . . . . . . .448
os_untranslatable_pointer_handler::get_source_offset() . . . . . . . . . . . .448
os_untranslatable_pointer_handler::get_source_path() . . . . . . . . . . . .448
os_untranslatable_pointer_handler::get_target_cluster() . . . . . . . . . . .448
os_untranslatable_pointer_handler::get_target_exported() . . . . . . . . . .449
os_untranslatable_pointer_handler::get_target_export_id() . . . . . . . . .449
os_untranslatable_pointer_handler::get_final_offset() . . . . . . . . . . . . .449
os_untranslatable_pointer_handler::get_target_offset() . . . . . . . . . . . .449
os_untranslatable_pointer_handler::get_target_path() . . . . . . . . . . . . .449
os_untranslatable_pointer_handler::get_target_segment() . . . . . . . . . .449
os_untranslatable_pointer_handler::handle_xxx() . . . . . . . . . . . . . . . .450
os_untranslatable_pointer_handler::is_PTOM() . . . . . . . . . . . . . . . . . .450
os_untranslatable_pointer_handler::set_final_offset() . . . . . . . . . . . . .450
os_void_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
os_void_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451
os_with_mapped . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452
os_with_mapped::os_with_mapped() . . . . . . . . . . . . . . . . . . . . . . . . .452
os_with_mapped::~os_with_mapped() . . . . . . . . . . . . . . . . . . . . . . . .452
tix_context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
tix_exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
tix_exception::ancestor_of() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .454
tix_exception::get_os_deadlock_exception() . . . . . . . . . . . . . . . . . . . .454
tix_exception::get_os_lock_timeout_exception() . . . . . . . . . . . . . . . . .454
tix_exception::release_pointer(). . . . . . . . . . . . . . . . . . . . . . . . . . . . .454
tix_exception::set_unhandled_exception_hook() . . . . . . . . . . . . . . . . .455
tix_handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
tix_handler::get_current() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
tix_handler::get_exception() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
tix_handler::get_report() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
tix_handler::get_report0(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
tix_handler::get_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .456
Chapter 3
System-Supplied Global Functions . . . . . . . . . . . . . . . 457
Global C++ Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
::operator delete(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
void ::operator delete(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .458
::operator new() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
Release 6.3
37
Contents
::os_fetch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
::os_fetch_address() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
::os_store() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Chapter 4
System-Supplied Macros. . . . . . . . . . . . . . . . . . . . . . 469
ObjectStore Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
DECLARE_EXCEPTION(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
DEFINE_EXCEPTION() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
OS_BEGIN_TXN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
OS_BEGIN_TXN_NAMED() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
OS_END_FAULT_HANDLER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
OS_END_TXN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
OS_ESTABLISH_FAULT_HANDLER . . . . . . . . . . . . . . . . . . . . . . . 481
OS_MARK_SCHEMA_TYPE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
OS_MARK_SCHEMA_TYPESPEC() . . . . . . . . . . . . . . . . . . . . . . . . 483
OS_REFERENCE_NOCLASS() . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
OS_REFERENCE_PROTECTED_NOCLASS() . . . . . . . . . . . . . . . . . . 485
OS_REPORT_DLL_LOAD_AND_UNLOAD() . . . . . . . . . . . . . . . . . . 486
OS_SCHEMA_DLL_ID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
OS_SCHEMA_INFO_NAME() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
os_soft_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
OS_SOFT_POINTER32_NOCLASS() . . . . . . . . . . . . . . . . . . . . . . . 490
OS_SOFT_POINTER64_NOCLASS() . . . . . . . . . . . . . . . . . . . . . . . 491
TIX_END_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
TIX_EXCEPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
TIX_HANDLE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
TIX_HANDLE_IF() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
Chapter 5
Predefined TIX Exceptions. . . . . . . . . . . . . . . . . . . . . 499
Parent Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
General ObjectStore Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . 501
Schema Evolution Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 508
Metaobject Protocol Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . 509
Database Copy Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
RPC Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Component Schema Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . 512
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
38
38
C++ A P I Reference
Preface
Purpose
The C++ A P I Reference provides a reference to the core C++ programming interface
to ObjectStore. It is supplemented by the C++ Collections Guide and Reference, which
describes the programming interface for using ObjectStore collections, queries, and
indexes.
Audience
This book assumes the reader is experienced with C++.
Scope
Information in this book assumes that ObjectStore is installed and configured. This
book supports ObjectStore Release 6.3.
How This Book Is Organized
This book is organized as follows:
• Chapter 1, Introduction, on page 43, describes the ObjectStore database services.
• Chapter 2, Class Library, on page 47, describes the system-supplied C++ classes,
whose members and enumerators provide an interface to database features. The
classes are listed alphabetically by class name. Within the entry for each class, the
class’s members, as well as enumerators defined within the class’s scope, are
listed alphabetically.
• Chapter 3, System-Supplied Global Functions, on page 457, describes the systemsupplied interface functions that are not members of any class but are global C++
functions; for example, ::operator new().
• Chapter 4, System-Supplied Macros, on page 469, describes ObjectStore macros,
which provides such services as exception handling and transaction processing.
• Chapter 5, Predefined TIX Exceptions, on page 499, lists and describes exceptions
that ObjectStore signals to indicate error conditions.
Notation Conventions
This document uses the following conventions
Convention
Meaning
Courier
Courier font indicates code, syntax, file names, API names,
system output, and the like.
Bold Courier
Bold Courier font is used to emphasize particular code,
such as user input.
Italic Courier
Release 6.3
Italic Courier font indicates the name of an argument or
variable for which you must supply a value.
39
Preface
Convention
Meaning
Sans serif
Sans serif typeface indicates the names of user interface
elements such as dialog boxes, buttons, and fields.
Italic serif
In text, italic serif typeface indicates the first use of an
important term.
[]
Brackets enclose optional arguments.
{ }* or { }+
When braces are followed by an asterisk (*), the items
enclosed by the braces can be repeated 0 or more times; if
followed by a plus sign (+), one or more times.
{ a |b | c}
Braces enclose two or more items. You can specify only one of
the enclosed items. Vertical bars represent OR separators. For
example, you can specify a or b or c.
...
Three consecutive periods can indicate either that material
not relevant to the example has been omitted or that the
previous item can be repeated.
Example Programs
The example programs listed in Chapter 4 of this manual are available online in the
following directories:
• $OS_ROOTDIR/examples/doc_demos (UNIX)
• %OS_ROOTDIR%\examples\doc_demos (Windows)
The doc_demos directory consists of subdirectories corresponding to chapters in the
documentation that contain example programs. For example, the subdirectory ref4
contains the programs that appear in Chapter 4 of this manual. Each subdirectory
contains
• Source files for the example programs
• A README.TXT file
• A makefile for building the program
• A doall script (in Windows, doall.bat batch file) that automates building and
running the program
The doc_demos directory also contains a README.TXT file that explains how the
subdirectories are organized.
Note
The example programs are not intended as models of the most effective way to write
an ObjectStore application. Rather, their purpose is simply to illustrate features of
the ObjectStore API that are described in the manual.
Progress Software Real Time Division on the World Wide Web
The Progress Software Real Time Division Web site (www.progress.com/realtime)
provides a variety of useful information about products, news and events, special
programs, support, and training opportunities.
40
C++ A P I Reference
Preface
Technical
Support
To obtain information about purchasing technical support, contact your local sales
office listed at www.progress.com/realtime/techsupport/contact, or in North
America call 1-781-280-4833. When you purchase technical support, the following
services are available to you:
• You can send questions to [email protected]. Remember to
include your serial number in the subject of the electronic mail message.
• You can call the Technical Support organization to get help resolving problems. If
you are in North America, call 1-781-280-4005. If you are outside North America,
refer to the Technical Support Web site at
www.progress.com/realtime/techsupport/contact.
• You can file a report or question with Technical Support by going to
www.progress.com/realtime/techsupport/techsupport_direct.
• You can access the Technical Support Web site, which includes
- A template for submitting a support request. This helps you provide the
necessary details, which speeds response time.
- Solution Knowledge Base that you can browse and query.
- Online documentation for all products.
- White papers and short articles about using Real Time Division products.
- Sample code and examples.
- The latest versions of products, service packs, and publicly available patches
that you can download.
- Access to a support matrix that lists platform configurations supported by this
release.
- Support policies.
- Local phone numbers and hours when support personnel can be reached.
Education
Services
To learn about standard course offerings and custom workshops, use the Real Time
Division education services site (www.progress.com/realtime/services).
If you are in North America, you can call 1-800-477-6473 x4452 to register for classes.
If you are outside North America, refer to the Technical Support Web site. For
information on current course offerings or pricing, send e-mail to
[email protected].
Searchable
Documents
In addition to the online documentation that is included with your software
distribution, the full set of product documentation is available on the Technical
Support Web site at www.progress.com/realtime/techsupport/documentation.
The site provides documentation for the most recent release and the previous
supported release. Service Pack README files are also included to provide
historical context for specific issues. Be sure to check this site for new information or
documentation clarifications posted between releases.
Your Comments
Release 6.3
41
Preface
Real Time Division product development welcomes your comments about its
documentation. Send any product feedback to [email protected].
To expedite your documentation feedback, begin the subject with Doc:. For example:
Subject: Doc: Incorrect message on page 76 of reference manual
42
C++ A P I Reference
Chapter 1
Introduction
This document describes the application programming interface (API) to the
functionality provided by the ObjectStore object-oriented database management
system. ObjectStore seamlessly integrates the C and C++ programming language
with the database services required by complex, data-intensive applications. These
services include support for the following:
• Persistence
Provision of a central repository for information that persists beyond the lifetime
of the process that recorded it
• Query processing
Support for associative data retrieval, such as lookup by name or ID number
• Integrity control
Services that maintain data consistency based on specified database constraints
• Access control
Services that protect data against unauthorized access
• Concurrency control
Services that allow shared, concurrent data access
• Fault tolerance
Services that protect data consistency and prevent data corruption even in the
event of system crashes or network failures
• Dynamic schema access
Services that allow the programmatic manipulation of database schema
information
• Schema evolution
Services that support schema change and automatic modification of database
objects to conform to new schemas
• Data compaction
Services that support data reorganization to eliminate fragmentation
Release 6.3
43
ObjectStore Database Services
ObjectStore Database Services
This section summarizes the functionality of ObjectStore database services.
Persistence
ObjectStore provides direct, transparent access to persistent data from within C++
programs. No explicit database reads or writes are required, and persistence is
entirely orthogonal to type. This means that the same type can have both persistent
and nonpersistent instances, and the same function can take either persistent or
nonpersistent arguments. Moreover, the instances of any built-in C++ type can be
designated as persistent.
Persistent allocation and deallocation are performed with the ObjectStore override
of ::operator new() and ::operator delete().
Clusters and Segments
A cluster is the basic physical unit of allocation in a database. A segment is a group of
one or more clusters. Both are variable-sized and can be used as the unit of transfer
to and from the database. In general, you should allocate storage for data from the
same cluster, especially if the data are frequently accessed together. Allocating from
the same segment can be useful, however, when you want the data to share the same
access controls, which can be set only at the segment level. ObjectStore overloads
::operator new() to allow data clustering at the database, segment, or cluster level.
Entry-Point Objects
ObjectStore enables you to name an object that you want to use as a database entry
point. You can also look up this object by its name and then use it as a starting point
for navigating through the database by following pointers contained in data
structure fields, just as you would do in a non-ObjectStore C++ program. Pointer
dereferencing causes transparent database retrievals when needed.
Note
You can also access data within an ObjectStore database by using query processing.
For information about query processing and the collections facility, see the C++
Collections Guide and Reference.
Integrity Control
Many design applications create and manipulate large amounts of complex
persistent data. Frequently, this data is jointly accessed by a set of cooperative
applications, each of which carries the data through some well-defined
transformation. Because the data is shared, and because it is more permanent and
more valuable than any particular run of an application, maintaining the data’s
integrity becomes a major concern and requires special database support.
In addition to the integrity control provided by compile-time type checking,
ObjectStore provides several facilities for dealing with some of the most common
integrity maintenance problems.
Problems and
solutions
44
One integrity control problem concerns pairs of data members that are used to model
binary relationships. A binary relationship, such as the part/subpart relationship,
Chapter 1: Introduction
for example, can be modeled by a pair of data members: parent_part and child_part.
Modeling the relationships with both of these data members has the advantage of
allowing navigation both up and down the parts hierarchy. However, the data
members must be kept in a consistent state with respect to one another: one object is
the parent of another if and only if the other is a child of the first. This integrity
constraint can be enforced by declaring the two data members as inverses of one
another. ObjectStore automatically implements the constraint as an update
dependency.
Another integrity control problem concerns illegal pointers. ObjectStore can
dynamically detect pointers from persistent to transient memory, as well as crossdatabase pointers from segments specified by the user to disallow such pointers.
ObjectStore’s schema evolution facility can also detect pointers to deleted objects and
incorrectly typed pointers.
Access Control
ObjectStore provides two general approaches to database access control. With one
approach, you can set read and write permissions for various categories of users at
various granularities. With the other approach, you can require that applications
supply a key to access a particular database. ObjectStore also supports server
authentication services.
Transactions and Concurrency Control
The concurrency control scheme employed by ObjectStore is based on transactions
with two-phase locking. Locking is automatic and completely transparent to the
user. The act of reading (or writing) an object causes a read (or write) lock to be
acquired for the object, thus eliminating the need to insert special locking commands
into the application code. Locking information is cached on both client and
ObjectStore server, minimizing the need for network communication when the same
process performs consecutive transactions on the same data.
ObjectStore also supports multiversion concurrency control (MVCC), which allows
nonblocking database reads. This form of concurrency control is implemented using
a technique of delaying propagation of data from the server log.
Fault Tolerance
ObjectStore’s fault tolerance is based on transactions and logging. Fault tolerance
endows transactions with a number of important properties. Either all of a
transaction’s changes to persistent memory are made successfully, or none at all are
made. If a failure occurs in the middle of a transaction, none of its database updates
is made. In addition, a transaction is not considered to have completed successfully
until all its changes are recorded safely on stable storage. After a transaction
commits, failures such as server crashes or network failures cannot erase the
transaction’s changes.
Dynamic Schema Access
ObjectStore’s metaobject protocol (MOP) supports access to ObjectStore schema
information, stored in the form of objects that represent C++ types. These objects are
actually instances of ObjectStore metatypes, so called because they are types whose
Release 6.3
45
ObjectStore Database Services
instances represent types. Schema information is also represented with the help of
various auxiliary classes that are not in the metatype hierarchy, such as classes
whose instances represent data members and member functions. The metaobject
protocol supports run-time read access to ObjectStore schemas, as well as dynamic
type creation and schema modification.
Schema Evolution
The term schema evolution refers to the changes undergone by a database’s schema
during the course of the database’s existence, especially changes that could require
changing the representation of objects already stored in the database.
Without the schema evolution facility, you can change a database schema only by
adding new classes to it. Redefinition of a class already contained in the schema,
except in ways that do not affect the layout that the class defines for its instances, is
not allowed. (Adding a nonstatic data member, for example, changes instance
layout, but adding a nonvirtual member function does not.)
The schema evolution facility, however, allows arbitrary redefinition of the classes
in a database’s schema, even if instances of the redefined classes already exist.
Invoking schema evolution directs ObjectStore to modify a database’s schema and
change the representation of any existing instances in the database to conform to the
new class definitions. If desired, these representation changes can be directed by
user-supplied routines.
Data Compaction
ObjectStore databases consist of clusters containing persistent data. As persistent
objects are allocated and deallocated in a cluster, internal fragmentation in the
segment can increase because of the presence of holes produced by deallocation. The
ObjectStore allocation algorithms recycle deleted storage when objects are allocated,
but there might nevertheless be a need to compact persistent data by squeezing out
the deleted space. Such compaction frees persistent storage space so that it can be
used by other clusters.
46
Chapter 2
Class Library
This chapter describes the system-supplied C++ classes whose members and
enumerators provide an interface to database features. All classes are listed
alphabetically by class name. Within the entry for each class, the class’s members, as
well as enumerators defined within the class’s scope, are listed alphabetically.
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. For information about support for 64-bit integers,
see os_int64 on page 231 and os_unsigned_int64 on page 446.
On Sun, you can use EUC or SJIS encoding for strings passed to char* formal
parameters.
Some functions in the ObjectStore API return an array or a character string. Unless
the return value of such a function is declared const, the array or string is allocated
from the heap and should be deleted to prevent a memory leak.
ObjectStore classes
The following list includes all the ObjectStore API classes available for you to use in
developing your ObjectStore applications.
Release 6.3
basic_undo
52
objectstore
54
objectstore_exception
96
os_access_modifier
97
os_address_space_marker
98
os_anonymous_indirect_type
101
os_app_schema
102
os_application_schema_info
103
os_archiver
104
os_archiver_options
106
os_array_type
108
os_authentication
109
os_backup
110
47
ObjectStore classes
48
os_backup_options
112
os_base_class
116
os_class_type
119
os_close_database
130
os_cluster
131
os_cluster_cursor
138
os_cluster_with
140
os_compact
141
os_comp_schema
147
os_database
148
os_database_root
172
os_database_schema
175
os_Database_table
176
os_dbutil
178
os_deadlock_exception
203
os_DLL_finder
205
os_DLL_schema_info
206
os_Dumper_reference
208
os_Dumper_specialization
211
os_dynamic_extent
213
os_enum_type
215
os_enumerator_literal
217
os_evolve_subtype_fun_binding
218
os_export_id
219
os_export_id_cursor
220
os_failover_server
222
os_field_member_variable
224
os_Fixup_dumper
225
os_function_type
227
os_indirect_type
229
os_instantiated_class_type
230
os_int64
231
os_integral_type
232
os_literal
234
os_literal_template_actual_arg
237
os_lock_timeout_exception
238
os_member
240
os_member_function
244
os_member_namespace
248
C++ A P I Reference
Chapter 2: Class Library
Release 6.3
os_member_type
249
os_member_variable
250
os_mop
254
os_named_indirect_type
257
os_namespace
258
os_notification
260
os_object_cursor
268
os_path_to_data
271
os_pathname_and_segment_number
275
os_pathname_segment_cluster
276
os_persistent_to_transient_pointer_manager
277
os_Planning_action
278
os_pointer_literal
279
os_pointer_to_member_type
280
os_pointer_type
281
os_pragma
282
os_rawfs_entry
283
os_real_type
286
os_recover
287
os_recover_options
289
os_Reference<T>
293
os_Reference_cross_session<T>
295
os_reference_cross_session
297
os_reference_internal
301
os_Reference_protected<T>
304
os_reference_protected_internal
306
os_reference_type
310
os_relationship_member_variable
311
os_release_cluster_pointer
312
os_release_database_pointer
313
os_release_root_pointer
314
os_release_segment_pointer
315
os_replicator
316
os_replicator_options
318
os_replicator_statistic_info
321
os_restore
323
os_restore_options
325
os_retain_address
329
os_schema
330
49
ObjectStore classes
50
os_schema_evolution
332
os_schema_handle
347
os_schema_info
350
os_schema_install_options
351
os_segment
352
os_segment_access
362
os_segment_cursor
365
os_server
367
os_session
370
os_soft_pointer32_base
373
os_soft_pointer64_base
377
os_soft_pointer32<T>
381
os_soft_pointer64<T>
384
os_soft_pointer32<void>
387
os_soft_pointer64<void>
388
os_soft_pointer32<char>
389
os_soft_pointer64<char>
390
os_str_conv
391
os_string
394
os_subscription
396
os_template
399
os_template_actual_arg
401
os_template_formal_arg
403
os_template_instantiation
405
os_template_type_formal
407
os_template_value_formal
408
os_transaction
409
os_transaction_hook
415
os_transformer_binding
417
os_type
418
os_Type_fixup_info
429
os_Type_fixup_loader
430
os_Type_info
432
os_Type_loader
434
os_type_template
436
os_type_template_actual_arg
437
os_type_type
438
os_typed_pointer_void
439
os_typed_pointer_void
439
C++ A P I Reference
Chapter 2: Class Library
Release 6.3
os_unsigned_int64
446
os_untranslatable_pointer_handler
448
os_void_type
451
os_with_mapped
452
tix_context
453
tix_exception
454
tix_handler
456
51
basic_undo
basic_undo
In C++, the destructor for an automatic object is run whenever a stack frame
containing it is unwound. When a C++ exception is signaled and control is
transferred to a handler in an enclosing scope, the intervening stack frames are
unwound. When a TIX exception is signaled and control is transferred to a handler
in an enclosing scope, the intervening stack frames are unwound on certain
platforms but not on others.
On platforms that do not support native exceptions, the intervening stack frames are
not unwound. When an exception occurs, the run-time system on such platforms
does not automatically call any destructors you might have coded to restore class
instances to a known state.
If your application runs on such platforms, you can derive a class from basic_undo
to partially simulate the unwinding of the intervening stack frames. ObjectStore runs
the destructors for instances of basic_undo contained in those stack frames when
the unwinding is simulated.
The destructors for these derived classes are virtual and can perform any desired
undo processing. You must create an instance of the derived class in the desired
scope before an exception can be raised. Note that this object must be stack allocated,
not heap allocated. The object’s destructor is invoked whenever the signaling of an
exception transfers control out of or through its stack frame. (Of course, the
destructors are invoked when the program exits normally.)
A class derived from basic_undo must have a virtual destructor if and only if further
classes are derived from it.
basic_undo::basic_undo()
basic_undo();
Constructs a new instance of basic_undo.
basic_undo::get_exception()
protected: tix_exception* get_exception() const;
Returns a pointer to the exception currently being signaled. If no exception is being
signaled, returns 0 (false). See also basic_undo::has_exception() on page 52.
basic_undo::has_exception()
protected: os_boolean has_exception() const;
Returns nonzero (true) if an exception is being signaled; otherwise, returns 0 (false).
To learn which exception is being signaled, see basic_undo::get_exception() on
page 52. However, in cases where you do not need to know which exception is being
signaled, has_exception() is faster than get_exception().
52
C++ A P I Reference
Chapter 2: Class Library
basic_undo::~basic_undo()
virtual ~basic_undo();
This destructor is invoked whenever a frame is unwound by tix_
exception::signal(). Overloadings of it defined by derived classes can perform
undo processing. This function is also invoked in the normal way upon block exit.
Release 6.3
53
objectstore
objectstore
This class provides static members related to persistence, performance tuning, and
performance monitoring.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
objectstore::acquire_address_space()
static os_boolean acquire_address_space(
os_ptr_val size
);
For multisession applications. Sets the address space partition size of the current
session. The size is specified in bytes and must be a multiple of 64 KB.
Call this function before initialization of the current session. See os_
session::force_full_initialization() on page 370. If you call this function
subsequent to initializing the current session, the call has no effect.
os_ptr_val is a 32-bit unsigned integer on platforms whose pointers are 32 bits, and
it is a 64-bit unsigned integer on platforms whose pointers are 64 bits.
size is the size in bytes of the partition.
When the session is initialized, err_address_space_full is signaled if the session’s
address space partition is too small or if the partition size is too large to fit in any
portion of free space in the process-wide persistent storage region.
err_misc is signaled if called after the current session has been initialized.
err_misc is signaled if size is not a multiple of 64 KB.
err_no_session is signaled if there is no current session.
objectstore::acquire_lock()
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, acquire_lock() returns 0.
If you specify –1 for the milliseconds argument, acquire_lock() uses the
segment’s current lock timeout value.
54
C++ A P I Reference
Chapter 2: Class Library
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 objectstore::set_lock_timeout() to set the default to –1
temporarily.
Specifying a 0 value for the milliseconds argument means that the attempt to
acquire the lock does 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 session, the
transaction is aborted, regardless of the value of the specified timeout.
Overloadings
The following overloadings for acquire_lock() are supported:
static os_lock_timeout_exception* acquire_lock(
os_database* db,
os_lock_type lock_type,
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.
If you specify –1 for the milliseconds argument, acquire_lock() uses the
segment’s current lock timeout value.
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 objectstore::set_lock_timeout() to set the default to –1
temporarily.
Specifying a 0 value for the milliseconds argument means that the attempt to
acquire the lock does 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 session, the
transaction is aborted, regardless of the value of the specified timeout.
Release 6.3
55
objectstore
static os_lock_timeout_exception* acquire_lock(
os_segment* seg,
os_lock_type lock_type,
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 toplevel 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 clients from requesting separate locks on individual pages of the database.
If the lock is successfully acquired, acquire_lock() returns 0.
If you specify –1 for the milliseconds argument, acquire_lock() uses the
segment’s current lock timeout value.
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 objectstore::set_lock_timeout() to set the default to –1
temporarily.
Specifying a 0 value for the milliseconds argument means that the attempt to
acquire the lock does 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 session, the
transaction is aborted, regardless of the value of the specified timeout.
static os_lock_timeout_exception* acquire_lock(
os_cluster* clstr,
os_lock_type lock_type,
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 cluster specified by clstr. This must be specified in a toplevel transaction.
Locking a cluster is equivalent to acquiring locks on all the pages of the cluster. For
example, acquiring a read lock on a cluster is equivalent to acquiring read locks on
all the pages of the cluster. Acquiring a lock on a cluster does not preclude a client
that has acquired a lock on a cluster from also requesting separate locks on
individual pages of the cluster.
If the lock is successfully acquired, acquire_lock() returns 0.
56
C++ A P I Reference
Chapter 2: Class Library
Specifying a –1 value for the milliseconds argument means that acquire_lock()
uses the cluster’s current lock timeout value.
If the caller wants an infinite timeout and the cluster'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 objectstore::set_lock_timeout() to set the default to –1 temporarily.
Specifying a 0 value for the milliseconds argument means that the attempt to
acquire the lock does 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 session, the
transaction is aborted regardless of the value of the specified timeout.
objectstore::add_missing_dispatch_table_handler()
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 virtual-function table (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 argument 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 into the application. The
dispatch_table_symbol argument 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.
Release 6.3
57
objectstore
objectstore::change_type()
static void objectstore::change_type(
void* address, os_typespec* typespec)
Changes the type of the persistent object at address to the type defined by typespec.
You must invoke this function in an update transaction.
The new type must be
• The same size and alignment as the object's old type
• A class that is derived directly or indirectly from the old type
If you violate these restrictions, ObjectStore signals err_misc.
The object whose type you are changing can be a singleton object or an array. If it is
an array, ObjectStore changes the type of each element to the type specified by
typespec.
If the new class defines any virtual functions, they do not become available until the
page containing the virtual function table pointer is removed from the cache and refetched. This does not affect the usual use of this API for schema evolution, where
the real definition of the new class is not installed until a later step. That is, the
process calling objectstore::change_type() is using only an intermediate
definition of the new class.
For an example of the use of this function, see Advanced C++ A P I User Guide,
Advanced Schema Evolution, Instance Reclassification.
objectstore::clear_persistent_to_transient_pointers()
static os_int32 clear_persistent_to_transient_pointers(
os_int32 max = -1
);
This is an optional user-callable function that tells ObjectStore to clear the specified
persistent pointers to transient objects immediately. It returns a count of the number
of pointers cleared in the session.
Pointers in the specified entity will be cleared in no particular order. The function can
also specify a maximum number of pointers to be cleared. This can be useful if this
function is being called in order to free some transient storage. If you do not specify
a maximum, all persistent pointers to transient objects in the specified entity will be
cleared by ObjectStore before control returns to the application. This function must
be called from within a transaction, but that transaction need not be an update
transaction.
If this function is never called by the application, persistent pointers to transient
objects will be cleared, but only when ObjectStore deems it necessary.
Overloadings
The following overloadings are supported:
static os_int32 clear_persistent_to_transient_pointers(
os_database* db,
os_int32 max = -1
);
58
C++ A P I Reference
Chapter 2: Class Library
static os_int32 clear_persistent_to_transient_pointers(
os_segment* seg,
os_int32 max = -1
);
static os_int32 clear_persistent_to_transient_pointers(
os_cluster* clstr,
os_int32 max = -1
);
The application can specify a specific os_database, os_segment, or os_cluster, in
which case only persistent pointers to transient objects in that entity will be cleared.
The default is to clear any pointers in the session.
For information about using this function to manage persistent pointers to transient
objects, Persistent Pointers to Transient Objects in Chapter 1 of the Advanced C++
A P I User Guide.
objectstore::embedded_server_available()
static os_boolean embedded_server_available();
For use with ObjectStore/Single applications. Returns nonzero (true) if the
ObjectStore / Single version of libos is available in the application; returns 0 (false)
otherwise.
Functions that report on embedded ObjectStore servers and on network servers are
mutually exclusive. That is, objectstore::embedded_server_available() and
objectstore::network_servers_available() cannot both return nonzero in the
same application.
objectstore::enable_damaged_dope_repair()
static void enable_damaged_dope_repair(os_boolean);
Enables or disables automatic repair of incorrect compiler dope for an object while
ObjectStore is loading a component schema. The default is false.
The objectstore::enable_damaged_dope_repair() function 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 incurred while ObjectStore is loading a
component schema signals an err_transient_dope_damaged exception.
If dope damage is enabled, dope damage while loading a component 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.
Release 6.3
59
objectstore
Compiler dope
Compiler dope is additional information added to the run-time layout of an object by
the compiler, in addition to the nonstatic data members of the object. The correct
compiler dope for an object can change as a result of loading or unloading a
component schema, for example, because the compiler dope can point to a virtual
function implementation contained in a DLL that is being loaded or unloaded.
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 component 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.
objectstore::enable_DLL_schema()
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() on page 75 to query whether
component schema support is enabled.
objectstore::export_object()
static os_export_id export_object(const void* export_address);
Exports the persistent top-level object at or containing the location pointed to by
export_address, if it is not already exported. Returns the export ID of the specified
top-level object.
The database containing the specified object must be opened. If the specified toplevel object is not already exported, the database containing it must be opened for
update and the current transaction must be an update transaction. If the object is
already exported, calling this function is a read-only operation.
If you retrieve an export ID in a transaction that is later aborted, do not use the export
ID after the abort. ObjectStore might reuse the export ID in a subsequent transaction.
The export_address argument is not required to point to the beginning of any
object.
err_invalid_export_id is signaled if you dereference a cross-segment pointer to
an exported object that has been deleted.
err_database_not_open or err_database_not_found is signaled if you retrieve a
cross-segment pointer (or resolve a cross-segment soft pointer) to an exported object
60
C++ A P I Reference
Chapter 2: Class Library
in a database that is not open and cannot be autoopened (see objectstore::set_
auto_open_mode() on page 83).
err_transient_pointer is signaled if export_address is not within the current
application’s persistent storage region.
err_wrong_session is signaled if export_address is within the current
application’s persistent storage region but not within the current session’s address
space partition.
err_not_assigned is signaled if export_address is in the address space partition
for the current session but is not currently a valid address (for example, because it
was retrieved in a prior transaction).
err_no_such_object is signaled if export_address refers to unallocated persistent
storage.
err_export_schema_segment is signaled if export_address points to an object in
the system segment of a database.
objectstore::find_DLL_schema()
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 component schema handle for the DLL identified by the first
argument in the following cases:
• The component schema is loaded and not queued for unload.
• The component schema is already queued for loading.
Otherwise, if load_if_not_loaded is true (nonzero), calls objectstore::load_
DLL() with the first and third arguments. If objectstore::load_DLL() returns a
value other than os_null_DLL_handle, this function looks for the component
schema again.
Note that objectstore::load_DLL() signals the exception err_DLL_not_loaded if
the DLL cannot be found or loaded, or if DLL_identifier cannot be understood and
error_if_not_found is true.
If the component schema is still not found, and if error_if_not_found is true, this
function signals an err_schema_not_found exception; otherwise, it returns a null
pointer. Note that if load_if_not_loaded and error_if_not_found are both true,
the exception signaled is err_DLL_not_loaded.
objectstore::free_memory()
static void free_memory(void* memory_to_free);
Releases persistent storage to which memory_to_free points. This function performs
the same operation as ObjectStore’s global ::operator delete() when it is used to
Release 6.3
61
objectstore
delete persistent storage. If you want to implement your own global delete function,
you must define it to include a call to free_memory() for deleting persistent storage.
The following example is a minimal implementation of a user-defined global
delete:
void operator delete(void* p) {
if (objectstore::is_persistent(p))
objectstore::free_memory(p);
else
// your own transient delete operation
};
For information about registering your own transient delete function, see
objectstore::set_transient_delete_function() on page 93. For information
about ObjectStore’s global delete function, see ::operator delete() on page 458.
objectstore::get_address_space_generation_number()
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.
objectstore::get_all_servers()
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 session. 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 the size array to
allocate.
The max_servers argument is specified by the user and is the maximum number of
elements the array is to have. The n_servers argument refers to the actual number
of elements in the array.
objectstore::get_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
static os_allocation_strategy get_allocation_strategy();
62
C++ A P I Reference
Chapter 2: Class Library
Returns an os_allocation_strategy enumerator that specifies the current strategy
for all databases when ObjectStore allocates storage for an object in a cluster. The
following enumerators can be returned by this function:
• os_allocation_strategy_least_space
• os_allocation_strategy_least_wait
The following sections describe their meaning. For information about specifying the
allocation strategy in all databases, see objectstore::set_allocation_
strategy() on page 82.
os_allocation_strategy_least_space
A value of os_allocation_strategy_least_space causes ObjectStore to use the
following strategy when it is looking for storage to allocate in a cluster:
1 Look for unlocked pages in the cluster with enough room. If a suitable contiguous
range of pages is found, allocate from them.
2 Otherwise, look for locked pages in the cluster with enough room. If a suitable
contiguous range of pages is found, allocate from them after the locks are released.
3 Otherwise, grow the cluster.
Locked pages refers to pages locked by other clients, and unlocked pages refers to pages
not locked by other clients. Neither term implies what lock the current client has on
the page. Also, it is assumed that pages you have write owned (and therefore are not
locked by others) have been checked for free space first.
os_allocation_strategy_least_wait
A value of os_allocation_strategy_least_wait causes ObjectStore to use the
following strategy when it is looking for storage to allocate in a cluster:
1 Look for unlocked pages in the cluster with enough room. If a suitable contiguous
range of pages is found, allocate from them.
2 Otherwise, grow the cluster.
Unlocked pages refers to pages not locked by other clients. The term does not imply
what lock the current client has on the page. Also, it is assumed that pages you have
write owned (and therefore are not locked by others) have been checked for free
space first.
objectstore::get_always_check_server_connection_at_commit()
os_boolean get_always_check_server_connection_at_commit();
Returns nonzero (true) if the application is specified to check for a valid server
connection before committing a read-only transaction. Returns 0 (false) if the
application will not conduct this check. The default is false.
The value is set by the objectstore::set_always_check_server_connection_
at_commit() function. For more information, see objectstore::set_always_
check_server_connection_at_commit() on page 82.
Release 6.3
63
objectstore
objectstore::get_application_schema_pathname()
static const char* get_application_schema_pathname( );
Returns the path name of the application schema database.
objectstore::get_as_intervals()
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
);
Returns all the ranges of virtual address space that ObjectStore is using, other than
ordinary code, text, and heap space. This function is intended primarily for users
who are trying to integrate ObjectStore and other complex subsystems into the same
application.
The ranges are returned in two arrays of os_as_interval objects. The class os_as_
interval has the following public data members:
char* start;
os_unsigned_int32 size;
persist and other are pointers that the caller passes to get_as_intervals().
When the function returns, persist points to the array of ranges used for mapping
persistent objects, and other points to any other ranges of address space that
ObjectStore uses.
It is the caller’s responsibility to use delete [] to free the memory allocated by get_
as_intervals() for the arrays that persist and other point to.
objectstore::get_asmarkers_useless()
static os_boolean get_asmarkers_useless();
Returns true (nonzero) if address-space markers have been disabled; otherwise,
returns false (0). Address-space markers can be enabled or disabled by calling
objectstore::set_asmarkers_useless() or by setting the OS_ASMARKERS_
USELESS environment variable. For more information, see objectstore::set_
asmarkers_useless() on page 83 and OS_ASMARKERS_USELESS in Managing
ObjectStore. Address-space markers are enabled by default.
objectstore::get_auto_open_mode()
static void get_auto_open_mode(auto_open_mode_enum& mode);
Returns the current setting for the autoopen mode in mode. For information about the
different values mode can have, see objectstore::set_auto_open_mode() on
page 83. For information about retrieving the fetch policy of all databases, see
objectstore::get_fetch_policy() on page 66.
objectstore::get_autoload_DLLs_function()
static os_autoload_DLLs_function get_autoload_DLLs_function();
64
C++ A P I Reference
Chapter 2: Class Library
Gets the hook function that is called when a database is put in use and its required
DLL set is not empty.
objectstore::get_cache_file()
static char* get_cache_file();
For use with ObjectStore/Single applications. Returns the name of a cache file
previously set with objectstore::set_cache_file(); returns 0 if no cache file was
specified.
On Windows platforms, shared memory is used instead of a cache file, so get_
cache_file() always returns 0.
It is the caller’s responsibility to deallocate the returned string when it is no longer
needed.
objectstore::get_cache_size()
static os_unsigned_int32 get_cache_size( );
Returns the current size in bytes of the client cache.
objectstore::get_client_name()
static const char* get_client_name();
Returns the string that was set by objectstore::set_client_name(). If set_
client_name() was not called, get_client_name() returns either the name of the
executable as set by the operating system or the string "Global Session".
For more information, see objectstore::set_client_name() on page 85.
objectstore::get_decache_soft_pointers_after_address_space_
release()
static os_boolean
get_decache_soft_pointers_after_address_space_release();
Returns nonzero (true) if soft-pointer decaching is in effect; returns 0 (false)
otherwise.
For information about enabling soft-pointer decaching, see objectstore::set_
decache_soft_pointers_after_address_space_release() on page 86. For more
information about soft-pointer decaching, see Soft-Pointer Decaching in Chapter 1 of
the Advanced C++ A P I User Guide.
objectstore::get_default_address_space_partition_size()
static os_ptr_val get_default_address_space_partition_size();
Returns the default partition size, in bytes, last specified by
objectstore::initialize_for_sessions() on page 73 or objectstore::set_
default_address_space_partition_size() on page 87. The default partition size
is the amount of address space assigned to newly created sessions.
Release 6.3
65
objectstore
If objectstore:: initialize() has been called and objectstore::initialize_
for_sessions() has not, the size of the process-wide persistent storage region is
returned.
objectstore::get_export_id()
static os_export_id objectstore::get_export_id(
void const* export_address
);
If export_address points to or points within a persistent object that currently has an
export ID assigned, the export ID is returned.
If export_address points to or points within a persistent top-level object that does
not currently have an export ID assigned, the null export ID (see os_export_
id::is_null() on page 219) is returned.
If export_address is not within the current application’s persistent storage region,
the null export ID is returned.
err_wrong_session is signaled if export_address is within the current
application’s persistent storage region but not within the current session’s address
space partition.
err_not_assigned is signaled if export_address is in the address space partition
for the current session but is not currently a valid address (for example, because it
was retrieved in a prior transaction).
err_no_such_object is signaled if export_address is in the current session’s
address space partition but is not contained within any currently allocated object.
objectstore::get_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
static void get_fetch_policy(
os_fetch_policy& policy,
os_int32& bytes
);
Retrieves the current fetch policy for all databases, including autoopened ones. An
enumerator of type os_fetch_policy is returned in policy, and the fetch quantum
is returned in bytes. The following enumerators can be returned by this function:
• os_fetch_cluster
• os_fetch_page
• os_fetch_stream
The following sections discuss the meaning of each enumerator and of the bytes
argument. For information about setting the fetch policy, see objectstore::set_
fetch_policy() on page 87.
66
C++ A P I Reference
Chapter 2: Class Library
os_fetch_cluster
The os_fetch_cluster enumerator is used when you are performing an operation
that manipulates a substantial portion of a small cluster. Under this policy,
ObjectStore attempts to fetch the entire cluster containing the desired page in a single
client/server interaction. When os_fetch_cluster is specified as the first argument
to any of the set_fetch_policy() functions, the bytes argument is ignored.
os_fetch_page
If an operation uses a cluster larger than the client cache or does not refer to a
significant portion of the cluster, use the os_fetch_page enumerator when you are
performing the operation on the cluster. 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. The
bytes argument specifies the fetch quantum. (Note that if you specify 0 bytes, this is
rounded up and the unit of transfer is a single page.)
os_fetch_stream
For special operations that scan sequentially through very large data structures, os_
fetch_stream might improve performance considerably. 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 cluster. In addition, it specifies that a double buffering
policy should be used to stream data from the cluster.
This means that after the first two transfers from the cluster, each transfer from the
cluster replaces the data cached by the second-to-last transfer from that cluster. This
way, the last two chunks of data retrieved from the cluster generally will be in the
client cache at the same time. And after the first two transfers, transfers from the
cluster generally will not result in eviction of data from other clusters. This policy
also greatly reduces the internal overhead of finding pages to evict.
When you perform allocation that extends a cluster whose fetch policy is os_fetch_
stream, the double buffering described previously begins when allocation reaches
an offset in the cluster that is aligned with the fetch quantum (that is, when the
modulus of the offset and the fetch quantum is 0).
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.
objectstore::get_incremental_schema_installation()
static os_boolean get_incremental_schema_installation( );
Returns nonzero (true) if incremental schema installation is currently enabled;
returns 0 (false) if batch schema installation is enabled. See objectstore::set_
incremental_schema_installation() on page 88.
objectstore::get_locator_file()
static const char* get_locator_file();
Release 6.3
67
objectstore
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.
objectstore::get_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
static objectstore_lock_option get_lock_option() const;
Returns the locking behavior currently in effect for all databases, segments, and
clusters. For information about the return value, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
• objectstore::own_page_write on page 79
For information about setting the lock option, see objectstore::set_lock_
option() on page 88.
objectstore::get_lock_status()
static os_int32 get_lock_status(void* addr);
Returns one of the following enumerators, indicating the current lock status of the
data at the specified address:
• os_read_lock
• os_write_lock
• os_no_lock
objectstore::get_lock_timeout()
static os_int32 get_lock_timeout( );
Returns the time in milliseconds for which the current session waits to acquire a lock.
A value of –1 indicates that the session waits forever if necessary. For information
68
C++ A P I Reference
Chapter 2: Class Library
about setting the timeout value, see objectstore::set_lock_timeout() on
page 89.
objectstore::get_log_file()
static char* get_log_file();
For use with ObjectStore/Single applications. Returns the name of the ObjectStore
server log file, if set with the OS_LOG_FILE environment variable or by a call to
objectstore::set_log_file(); otherwise returns the default log file name
tplog.odi.
It is the caller’s responsibility to deallocate the returned string when it is no longer
needed.
objectstore::get_n_servers()
static os_int32 get_n_servers();
Returns the number of ObjectStore servers to which the current session is connected.
objectstore::get_null_illegal_pointers()
static os_boolean get_null_illegal_pointers( );
Returns nonzero (true) if the current session enables default_null_illegal_
pointers mode for newly created databases; returns 0 (false) otherwise. See
objectstore::set_null_illegal_pointers() on page 90.
objectstore::get_object_range()
static void get_object_range(
void const* addr,
void*& base_address,
os_unsigned_int32& size
);
Indicates where a persistent object starts and how large it is. addr 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 addr is the address of one of the array
elements, base_address is set to the address of the beginning of the array. If addr
does not point to a persistent object, base_address and size are both set to 0.
Overloadings
The following overloadings of get_object_range() are also supported:
static void get_object_range(
void const* addr,
void*& header_address,
os_unsigned_int32& total_size
);
addr is a pointer to a persistent object, or into the middle of a persistent object.
header_address is set to the beginning of the object; if a header is associated with
the object, header_address points to the beginning of the header. total_size is set
to include the object itself, including any metadata (such as a header) associated with
the object.
Release 6.3
69
objectstore
static void get_object_range(
void const* addr,
void*& base_address,
os_unsigned_int32& base_size,
void*& header_address,
os_unsigned_int32& total_size
);
addr, header_address, and total_size have the same meanings as in the first
overloading. base_address is set to the start of the object itself, and base_size is set
to include only the object itself.
objectstore::get_page_size()
static os_unsigned_int32 get_page_size( );
Returns the page size for the architecture on which ObjectStore is running.
objectstore::get_pointer_numbers()
static void get_pointer_numbers(
const void* addr,
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, because the address of an object can change from transaction to transaction.
Based on the addr 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 are always the same for a given object, no matter what address the
object happens to be mapped to at a particular time. Moreover, no two objects will
have the same values.
objectstore::get_propagate_on_commit()
static os_boolean get_propagate_on_commit();
For use with ObjectStore / Single applications. The return value indicates when
ObjectStore propagates committed data from the transaction log to the affected
database. If the return value is nonzero (true), propagations occur whenever a toplevel transaction commits. This is the default.
If the return value is 0 (false), propagations occur when a database is closed and the
program ends normally. If the program ends prematurely, some of the committed
data in the log might not have been propagated to the database. This data is
propagated the next time ObjectStore is initialized or when
objectstore::propagate_log() is called, provided that the correct transaction log
exists at the time.
70
C++ A P I Reference
Chapter 2: Class Library
In client-server mode, propagation is controlled by ObjectStore server parameters,
and get_propagate_on_commit() always returns false.
For information about setting when propagations occur, see objectstore::set_
propagate_on_commit() on page 91. For additional information about the log file,
see
• objectstore::propagate_log() on page 79
• objectstore::set_log_file() on page 89
objectstore::get_retain_persistent_addresses()
static os_boolean get_retain_persistent_addresses( );
Returns nonzero (true) if the current session is in retain_persistent_addresses
mode; otherwise, returns 0 (false). See objectstore::retain_persistent_
addresses() on page 81.
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( ). The handler argument is the function that is called to
determine the user and password information needed for authentication. The data
argument is the user-supplied value that is passed to the handler function.
objectstore::get_suppress_invalid_hard_pointer_errors()
static os_boolean get_suppress_invalid_hard_pointer_errors();
Returns nonzero if suppression is enabled; returns 0 otherwise. See
objectstore::set_suppress_invalid_hard_pointer_errors() on page 92.
objectstore::get_transaction_max_retries()
static os_unsigned_int32 get_transaction_max_retries();
Returns the number of times a lexical transaction is retried automatically after being
aborted because of a deadlock. For information about setting the number of retries,
see objectstore::set_transaction_max_retries() on page 92.
For information about the macros used to set up a lexical transaction, see Chapter 4,
System-Supplied Macros, on page 469.
objectstore::get_transaction_priority()
static os_unsigned_int16 get_transaction_priority();
Returns an unsigned integer that represents the transaction priority of the client. The
ObjectStore server uses the transaction priority to decide among clients involved in
Release 6.3
71
objectstore
a deadlock. For more information, see objectstore::set_transaction_
priority() on page 92.
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 session.
Returns 0 if there is no current transient delete function. See objectstore::set_
transient_delete_function() on page 93.
objectstore::get_union_variant()
static os_unsigned_int16 get_union_variant(
void* addr,
const char* type_name
);
Returns a number that corresponds to the currently active member object of a union
in persistent memory. addr is the persistent memory address of the union, and
type_name is the name of the union type. The name of a union member object can be
either the fully qualified name (for example, "A::B::C") or the unqualified name
(for example, "C").
For information about setting the currently active member object, see
objectstore::set_union_variant() on page 94. For information about using
persistent unions, see Using Persistent Unions on page 39 of Chapter 1 of the
Advanced C++ A P I User Guide.
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.
objectstore::initialize()
static void initialize(
os_boolean force_full_initialization = 0
);
Initializes ObjectStore. If force_full_initialize is nonzero (true), all ObjectStore
initialization procedures are performed immediately. When force_full_
initialize has the default value of 0 (false), some initialization is deferred until
needed (for example, until a database is first opened). Applications that integrate
with third-party software might need to force full initialization.
This function must be called in an application that does not use multiple sessions
before any use of ObjectStore functionality is made, with the following exceptions:
• objectstore::propagate_log() (ObjectStore / Single only)
72
C++ A P I Reference
Chapter 2: Class Library
• objectstore::set_application_schema_pathname( )
• objectstore::set_cache_file() (ObjectStore / Single only)
• objectstore::set_cache_size( )
• objectstore::set_client_name( )
These functions must be called before ObjectStore initialization.
To initialize ObjectStore in an application that uses multiple sessions, see
objectstore::initialize_for_sessions() on page 73.
A session can execute initialize( ) more than once; after the first execution, calling
this function has no effect.
objectstore::initialize_for_sessions()
static void initialize_for_sessions(
os_unsigned_int32 n_expected_sessions
);
In applications that use multiple sessions, call initialize_for_sessions() instead
of objectstore::initialize(). You must call initialize_for_sessions()
before creating instances of os_session.
This function sets the application’s default partition size to the size of the processwide persistent storage region divided by n_expected_sessions (rounded up to
the nearest 64 KB). The application’s default partition size is the amount of address
space assigned to a newly created session, unless the environment variable OS_
DEFAULT_AS_PARTITION_SIZE is set.
n_expected_sessions is the number of sessions you expect to create in the current
application. This is used to determine the default partition size. When deciding how
many sessions to use, you should consider the per-session costs.
Each session has its own cache, address space partition, and commseg. To the extent
that an application’s session caches contain overlapping data sets, the application
makes less efficient use of cache space, address space, and locking resources. Be sure
you use a small enough number of sessions to allow for sufficient resources for each
one.
Calling the objectstore::initialize() function after
objectstore::initialize_for_sessions() has no effect.
If the sessions facility has already been initialized, calling this function has no effect.
err_misc is thrown if
• objectstore::initialize_for_sessions() is called after calling
objectstore::initialize().
• n_expected_sessions is 0.
• ObjectStore thread locking is not enabled.
Release 6.3
73
objectstore
Note that initializing the sessions facility is different from initializing an individual
session (also called full initialization). See os_session::force_full_
initialization() on page 370.
A number of members of objectstore serve a dual purpose:
• They set or get session defaults if called prior to objectstore::initialize_
for_sessions().
• They set or get session-specific state if called after objectstore::initialize_
for_sessions().
If called before initialize_for_sessions(), these functions set or get default
values to be used for newly created sessions. If called after initialize_for_
sessions(), they set or get state for the current session, or throw err_no_session
if there is no current session.
If there are multiple threads prior to initialization of the sessions facility, you must
synchronize their use of these functions. ObjectStore does not provide thread locking
prior to initialization (that is, prior to a call to objectstore::initialize() or
objectstore::initialize_for_sessions()).
Following are the dual-purpose set functions:
set_allocation_strategy()
set_always_null_illegal_pointers()
set_auto_load_DLLs_function()
set_auto_open_mode()
set_current_schema_key()
set_fetch_policy()
set_incremental_schema_installation()
set_suppress_invalid_hard_pointer_errors()
set_lock_option()
set_lock_timeout()
set_null_illegal_pointers()
set_simple_auth_ui()
set_suppress_invalid_hard_pointer_errors()
set_transaction_max_retries()
set_transaction_priority()
Following are the dual-purpose get functions:
get_allocation_strategy()
get_always_null_illegal_pointers()
get_autoload_DLLs_function()
get_auto_open_mode()
get_fetch_policy()
get_incremental_schema_installation()
get_lock_option()
get_lock_timeout()
get_null_illegal_pointers()
get_simple_auth_ui()
get_suppress_invalid_hard_pointer_errors()
get_transaction_max_retries()
get_transaction_priority()
The following members of objectstore always set or get process-wide state:
embedded_server_available()
get_application_server_pathname()
74
C++ A P I Reference
Chapter 2: Class Library
get_locator_file()
get_log_file()
get_page_size()
get_thread_locking()
get_transient_delete_function()
is_multiple_session_mode()
is_single_session_mode()
network_servers_available()
propagate_log()
release_maintenance()
release_major()
release_minor()
release_name()
set_client_name()
set_default_address_space_partition_size()
set_thread_locking()
set_transient_delete_function()
shutdown()
which_product()
All other objectstore members access process-specific state, or throw err_no_
session if there is no current session.
objectstore::is_damaged_dope_repair_enabled()
static os_boolean is_damaged_dope_repair_enabled();
Returns a Boolean value indicating whether dope damage repair during component
schema loading is enabled. The initial state is false. See objectstore::enable_
damaged_dope_repair() on page 59 for details.
objectstore::is_DLL_schema_enabled()
os_boolean is_DLL_schema_enabled();
Returns nonzero (true) if the component schema feature is enabled. The initial state
is true on most platforms.
objectstore::is_multiple_session_mode()
static os_boolean is_multiple_session_mode();
Returns nonzero if the sessions facility has been initialized for multisession use;
returns 0 otherwise. See objectstore::initialize_for_sessions() on page 73.
objectstore::is_persistent()
static os_boolean is_persistent(void const* addr);
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.
objectstore::is_single_session_mode()
static os_boolean is_single_session_mode();
Release 6.3
75
objectstore
Returns nonzero if the sessions facility has not been initialized for multisession use;
returns 0 otherwise.
objectstore::is_unassigned_contiguous_address_space()
static os_boolean is_unassigned_contiguous_address_space(
os_unsigned_int32 bytes
);
Returns nonzero if there is a contiguous portion of unreserved address space whose
size is the specified number of bytes. Returns 0 otherwise.
objectstore::load_DLL()
static os_DLL_handle load_DLL(
const char* DLL_identifier,
os_boolean error_if_not_found = true
);
Loads the DLL identified by DLL_identifier and returns an os_DLL_handle to it
after running its initialization function.
If the DLL cannot be found or 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 DLL_identifier cannot be understood and error_
if_not_found is true, this function signals the exception err_DLL_not_loaded.
If a transaction is currently in effect, aborting the transaction does not roll back load_
DLL(). 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 that occurs while you are trying to load the DLL (other than failure to find
the DLL) causes an exception regardless of the setting of error_if_not_found. This
condition could happen if an error occurs during the execution of the DLL’s
initialization code.
UNIX platform
note
There is a bug in most versions of UNIX that causes some such errors to look like
“DLL not found” and thus be subject to error_if_not_found.
objectstore::lock_as_used
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_as_used specifies the default behavior, which is to lock just the page
faulted on when pages are cached. The accessed page is read locked or write locked,
depending on the type of access. Prefetched pages are not locked.
76
C++ A P I Reference
Chapter 2: Class Library
objectstore::lock_cluster_read
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_cluster_read causes a cluster to be read locked when a page in the
specified entity (cluster, segment, or database) is accessed. The accessed page is read
locked or write locked depending on the type of access.
objectstore::lock_cluster_write
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_cluster_write causes a cluster to be write locked when a page in
the specified entity (cluster, segment, or database) is accessed.
objectstore::lock_database_read
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_database_read causes a database to be read locked when a page in
the specified entity (cluster, segment, or database) is accessed. The accessed page is
read locked or write locked depending on the type of access.
objectstore::lock_database_write
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_database_write causes a database to be write locked when a page
in the specified entity (cluster, segment, or database) is accessed.
Release 6.3
77
objectstore
objectstore::lock_page_write
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_page_write causes the accessed page and any prefetched pages to
be write locked regardless of whether the page is accessed for read or write.
Compare this value with the default value, objectstore::lock_as_used on
page 76.
objectstore::lock_segment_read
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_segment_read causes a segment to be read locked when a page in
the specified entity (cluster, segment, or database) is accessed. The accessed page is
read locked or write locked depending on the type of access.
objectstore::lock_segment_write
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of lock_segment_write causes a segment to be write locked when a page
in the specified entity (cluster, segment, or database) is accessed.
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 signaled.
78
C++ A P I Reference
Chapter 2: Class Library
objectstore::network_servers_available()
static os_boolean network_servers_available();
For use with ObjectStore / Single applications. Returns nonzero if the conventional,
networked version of ObjectStore’s libos is available in the application; returns 0
otherwise.
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.
objectstore::own_page_write
This enumerator is a possible argument to
• objectstore::set_lock_option() on page 88
• os_cluster::set_lock_option() on page 135
• os_database::set_lock_option() on page 169
• os_segment::set_lock_option() on page 361
A value of own_page_write enables the client to upgrade from a read lock to a write
lock without contacting the ObjectStore server, thus reducing the amount of
client/server communication when upgrading locks. The accessed page is read
locked or write locked depending on the type of access. Prefetched pages are not
locked.
objectstore::propagate_log()
static void propagate_log(const char* log_path);
For use with ObjectStore / Single applications. Causes all committed data in the
specified ObjectStore server log to be propagated to the affected databases. Unless
errors occur, the log is removed during execution of this call.
An exception is signaled (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 initializing
ObjectStore. Most ObjectStore / Single applications need not use this entry point
because propagation of the application’s own log file — that is, the one specified by
objectstore::set_log_file() — happens automatically at initialization.
For more information, see objectstore::set_log_file() on page 89.
objectstore::release_cleared_persistent_to_transient_pointers()
static
os_int32 release_cleared_persistent_to_transient_pointers(
os_int32 max = -1
);
Processes the queue of cleared persistent pointers to transient objects and returns a
count of the number of pointers processed. This function removes each (pointer,
Release 6.3
79
objectstore
mgr) pair in this queue and then executes mgr.release(pointer), invoking the
user-supplied release() function for all appropriate persistent pointers to transient
objects that have been cleared. For information about the user-supplied release()
function, see os_persistent_to_transient_pointer_manager::release() on
page 277.
The session lock is not held during the invocation of the user-supplied functions.
Users should call this function at a time when it is convenient to release transient
storage that had been allocated in connection with calls to set_persistent_to_
transient_pointer(); see objectstore::set_persistent_to_transient_
pointer() on page 90. This time is application dependent, but after ending a
transaction is a suitable time.
For information about using this function to manage persistent pointers to transient
objects, Persistent Pointers to Transient Objects in Chapter 1 of the Advanced C++
A P I User Guide.
Overloadings
The following overloadings are supported:
static os_int32 release_cleared_persistent_to_transient_pointers(
os_database* db,
os_int32 max = -1
);
static os_int32 release_cleared_persistent_to_transient_pointers(
os_segment* seg,
os_int32 max = -1
);
static os_int32 release_cleared_persistent_to_transient_pointers(
os_cluster* clstr,
os_int32 max = -1
);
objectstore::release_maintenance()
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 returns 1.
objectstore::release_major()
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 6.0, this
function returns 6.
objectstore::release_minor()
static os_unsigned_int32 release_minor( );
80
C++ A P I Reference
Chapter 2: Class Library
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 6.0, this
function returns 0.
objectstore::release_name()
static const char* release_name( );
Returns a string naming the release of ObjectStore in use. For example,
"ObjectStore 6.0".
objectstore::release_persistent_addresses()
static void release_persistent_addresses( );
Globally disables retaining the validity of persistent addresses across transaction
boundaries. This function is used in conjunction with objectstore::retain_
persistent_addresses( ).
It can be called within a top-level transaction as well as outside a transaction.
objectstore::reset_persistent_addresses()
static void reset_persistent_addresses(os_boolean force=0);
Releases all address space when called. The force argument determines if address
space retained by os_retain_address_objects is also released. The force
argument is false by default.
Set the force argument to true only in situations where the session knows it is safe
to release addresses held by os_retain_address objects.
See also objectstore::set_retain_persistent_addresses() on page 91.
objectstore::retain_persistent_addresses()
static void retain_persistent_addresses( );
Enables retaining the validity of persistent addresses across transaction boundaries.
After being executed within a given session, pointers to persistent memory remain
valid even after the transaction in which they were retrieved from the database has
executed. This is true until the end of the session or until objectstore::release_
persistent_addresses( ) is called.
objectstore::return_all_pages()
static void return_all_pages( );
Clears the client cache.
objectstore::return_memory()
void return_memory(
void* addr,
os_unsigned_int32 length,
os_boolean evict_now
);
Release 6.3
81
objectstore
Gives the programmer control over cache replacement. The first two arguments
designate a region of persistent memory; addr 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).
objectstore::set_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
static void set_allocation_strategy(os_allocation_strategy);
Sets the strategy to use when ObjectStore is looking for space to allocate for an object
in a cluster. This strategy applies to all databases, segments, and clusters unless
specifically overridden by subsequent calls to
• objectstore::set_allocation_strategy() on page 82
• os_cluster::set_allocation_strategy() on page 135
• os_database::set_allocation_strategy() on page 168
• os_segment::set_allocation_strategy() on page 359
For information about the meaning of the os_allocation_strategy enumerators
that can be used as arguments, see objectstore::get_allocation_strategy() on
page 62.
objectstore::set_always_check_server_connection_at_commit()
void set_always_check_server_connection_at_commit(
os_boolean
);
If a nonzero value is specified, the application checks for a valid server connection
before committing a read-only transaction. This function is not appropriate for
transactions with updates since those transactions always check for valid server
connections.
If called before a call to objectstore::initialize() or
objectstore::initialize_for_sessions(), set_always_check_server_
connection_at_commit() sets the value globally. If called after a call to
objectstore::initialize() or objectstore::initialize_for_sessions(),
set_always_check_server_connection_at_commit() sets the value for the
current session.
See objectstore::get_always_check_server_connection_at_commit() on
page 63 as well as the environment variable OS_ALWAYS_CHECK_SERVER_AT_COMMIT
in Managing ObjectStore.
82
C++ A P I Reference
Chapter 2: Class Library
objectstore::set_always_null_illegal_pointers()
static void set_always_null_illegal_pointers(os_boolean);
Supplying a nonzero value specifies that illegal pointers should always be set to 0
(null) when they are detected by ObjectStore during the current session. This
includes illegal pointers detected during database reads as well as database writes.
objectstore::set_application_schema_pathname()
static void set_application_schema_pathname(const char* path);
Specifies the location of the application schema database. This function must be
called before you initialize ObjectStore.
objectstore::set_asmarkers_useless()
static void get_asmarkers_useless(os_boolean);
Specifying a nonzero value (true) as the argument disables address-space markers;
if the argument is 0 (false), they are enabled. Address-space markers are enabled
by default. For information enabling and disabling address-space markers, see
objectstore::get_asmarkers_useless() on page 64 and OS_ASMARKERS_
USELESS in Managing ObjectStore.
objectstore::set_autoload_DLLs_function()
static os_autoload_DLLs_function set_autoload_DLLs_function(
os_autoload_DLLs_function func
);
Controls whether DLLs are loaded automatically by setting a hook function that is
called when a database is put in use and its required DLL set is not empty. Calling
this function returns the previously set hook function.
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:
1 Call os_database::get_required_DLL_identifiers().
2 For each DLL_identifier, call objectstore::find_DLL_schema() with
arguments of the DLL identifier, true, and false, and ignore the result.
There is caching to avoid calling the hook function when a database is being put in
use for the second or later time in a session, the database’s required DLL set has not
grown, and the session has not unloaded any DLLs.
objectstore::set_auto_open_mode()
enum auto_open_mode_enum
{auto_open_read_only, auto_open_multi_db_mvcc, auto_open_mvcc, auto_
open_update, auto_open_disable};
static void set_auto_open_mode(
auto_open_mode mode = auto_open_update
);
Release 6.3
83
objectstore
Enables autoopen mode. This mode automatically opens any databases that need to
be opened because of traversal of a reference or a cross-database pointer. Specify the
mode in which to open the database with one of the following values:
Value
Meaning
auto_open_read_only
Opens the database as read-only.
auto_open_multi_db_mvcc
Opens the database for multidatabase
multiversion concurrency control. See os_
database::open_multi_db_mvcc() on page 165.
auto_open_mvcc
Opens the database for single-database
multiversion concurrency control. See os_
database::open_mvcc() on page 165.
auto_open_update
Opens the database for updates.
auto_open_disable
Disables autoopen mode.
If a database is already open, a nested open is not done on that database. If autoopen
mode is disabled, the error err_database_not_open is signaled upon an attempt to
do an auto open.
For information on setting the fetch policy for any database, see os_database::set_
fetch_policy() on page 169.
To set the fetch policy for all databases (including autoopened ones), call
objectstore::set_fetch_policy(). For information on setting the fetch policy for
any database, see os_database::set_fetch_policy() on page 169.
Warning
84
Exercise extra caution if you have several databases open for multiversion
concurrency control (MVCC) at once. In particular, be aware that the databases are
not necessarily consistent with each other. Unless you are very careful, this could
lead to unexpected results.
C++ A P I Reference
Chapter 2: Class Library
objectstore::set_cache_file()
static void set_cache_file(
const char* cache_path,
os_boolean pre_allocate = 1
);
For use with ObjectStore/Single on UNIX only. Names a file to be used as the
ObjectStore / Single cache on UNIX platforms. This entry point has no effect if called
in a full ObjectStore (networked) application.
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() on
page 85). Preallocation slows down startup 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, err_
internal is signaled. The error message (admittedly obscure) will specify a
problem with mmap, page protections, or possibly page locks.
set_cache_file() must be called before you initialize ObjectStore. It takes
precedence over the environment variable OS_CACHE_FILE. Note that, if the file
already exists, it is overwritten.
The cache file is not removed when the application ends. Normally, users should
remove it in the interest of conserving disk space.
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.
objectstore::set_cache_size()
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. The set_cache_size() function can be called after
you initialize ObjectStore but must be called before doing any ObjectStore operations
in a session. This function may be called at the beginning of every session. Calling
this function affects performance only.
objectstore::set_client_name()
static void set_client_name(const 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
ObjectStore server and the ossvrstat command) easier to understand. This function
must be called before you initialize ObjectStore.
Release 6.3
85
objectstore
objectstore::set_current_schema_key()
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
you initialize ObjectStore. Otherwise, err_schema_key is signaled, and ObjectStore
issues an error message such as 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.
For information about schema keys, see the C++ A P I User Guide, Chapter 7, Database
Access Control.
objectstore::set_decache_soft_pointers_after_address_space_
release()
static void
set_decache_soft_pointers_after_address_space_release(
os_boolean decache);
If the decache argument is nonzero (true), enables soft-pointer decaching. To
disable decaching (the default), set decache to 0 (false).
By default, ObjectStore does not automatically decache soft pointers on a page when
that page is accessed again. When a page that contains cached soft pointers is reused,
the address space for the soft-pointer targets is immediately reserved. When softpointer decaching is enabled and a page containing cached soft pointers is reused,
the soft pointers on the page are decached, ensuring that address space is not
reserved for their targets.
To determine if soft-pointer decaching is in effect, see objectstore::get_decache_
soft_pointers_after_address_space_release() on page 65. For more
information about soft-pointer decaching, see Soft-Pointer Decaching in Chapter 1 of
the Advanced C++ A P I User Guide.
86
C++ A P I Reference
Chapter 2: Class Library
objectstore::set_default_address_space_partition_size()
static void set_default_address_space_partition_size(
os_ptr_val size
);
Sets the application‘s default partition size. The size is specified in bytes and must be
a multiple of 64 KB. The application’s default partition size is the amount of address
space assigned to newly created sessions.
err_misc is signaled if the argument is not a multiple of 64 KB.
When a session is initialized (see os_session::force_full_initialization() on
page 370), ObjectStore initializes the session’s address space partition, that is, the
portion of the persistent storage region associated with the session. When a session
is initialized, the size of the partition is determined as follows:
• If objectstore::acquire_address_space() has been called during the session,
the size specified in the last call to that function is used.
• Otherwise, if objectstore::set_default_address_space_partition_size()
has been called subsequent to objectstore::initialize_for_sessions(), the
size last passed to set_default_address_space_partition_size() is used.
• Otherwise, if the environment variable OS_DEFAULT_AS_PARTITION_SIZE is set,
its value is used. See the following information.
• Otherwise, the size argument is the size of the process-wide persistent storage
region divided by the n_expected_sessions argument of the first call to
objectstore::initialize_for_sessions() (rounded up to the nearest 64 KB).
See objectstore::initialize_for_sessions() on page 73.
When the session is initialized, err_address_space_full is signaled if the session’s
address space partition is too small or if the partition size is too large to fit in any
portion of free space in the process-wide persistent storage region.
objectstore::set_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
static void set_fetch_policy(
os_fetch_policy policy = os_fetch_page,
os_int32 bytes = 0
);
Sets the fetch policy for all databases, including autoopened ones. The bytes
argument specifies the fetch quatum, and the policy argument can be one of the
following enumerators:
• os_fetch_cluster
• os_fetch_page
• os_fetch_stream
Release 6.3
87
objectstore
The default for the policy argument is os_fetch_page, with a fetch quantum of one
page. For information about the meaning of the os_fetch_policy enumerators and
about retrieving the fetch policy, see objectstore::get_fetch_policy() on
page 66.
objectstore::set_handle_transient_faults()
static void set_handle_transient_faults(os_boolean);
For UNIX only. (Calls to this function are ignored under Windows.) Determines
whether dereferencing an illegal pointer (for example, a null pointer) in the current
session causes an operating system signal or an ObjectStore exception. If a nonzero
value is supplied as argument, an ObjectStore exception results; if 0 is supplied, or if
the function has not been invoked, an operating system signal results.
objectstore::set_incremental_schema_installation()
static void set_incremental_schema_installation(os_boolean);
If a nonzero value (true) is supplied as argument, the current application run
performs 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 are in incremental mode and the schema of the creating
application is 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 an argument, databases subsequently
created by the current execution of the application are 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).
objectstore::set_locator_file()
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.
objectstore::set_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
88
C++ A P I Reference
Chapter 2: Class Library
own_page_write
};
static void set_lock_option(objectstore_lock_option);
Sets the locking behavior for all databases, segments, and clusters. For information
about the argument, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
• objectstore::own_page_write on page 79
objectstore::set_lock_timeout()
static void set_lock_timeout(os_int32 milliseconds );
Sets the time in milliseconds for which the current session waits to acquire a lock.
The time is rounded up to the nearest whole number of seconds. A value of –1
indicates that the session waits forever, if necessary.
After an attempt is made to acquire a 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 specified timeout
value.
For information about retrieving the timeout value, see objectstore::get_lock_
timeout() on page 68.
objectstore::set_log_file()
static void set_log_file(const char* log_path);
For use with ObjectStore/Single applications. Names a file that will be used for the
ObjectStore / Single server log. This entry point has no effect if called in a full
ObjectStore (networked) application. It takes precedence over the environment
variable OS_LOG_FILE. Note the discussion of considerations about this environment
variable in Managing ObjectStore.
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 normally is 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.
Release 6.3
89
objectstore
objectstore::set_null_illegal_pointers()
static void set_null_illegal_pointers(os_boolean);
If the argument is nonzero (true), 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 session. See os_
segment::set_null_illegal_pointers() on page 361.
objectstore::set_pathname_encoding()
void objectstore::set_pathname_encoding(const char* encoding);
Sets the character set encoding to be encoding. The value of the encoding argument
can be one of the following:
Valid encoding values
Meaning
ASCII
7-bit ASCII
CP1252
Microsoft Code Page 1252 (US English)
CP932
Microsoft Code Page 932 (Japanese)
EUCJP
Extended UNIX Code (Japanese)
UTF8
UCS Transformation Format 8
NONE
No encoding translation; values 0x01 through 0xFF are
passed through without modification.
The default encoding is determined by the system on which the client application is
running. If you supply an invalid encoding value, calling this function will result in
the err_invalid_pathname_encoding exception.
Note that the objectstore::set_pathname_encoding() function must be called
before objectstore::initialize() or objectstore::initialize_for_
sessions().
You can also set the character set encoding with an environment variable; for more
information, see OS_PATHNAME_ENCODING in Managing ObjectStore.
objectstore::set_persistent_to_transient_pointer()
static void* set_persistent_to_transient_pointer(
void* p_pointer,
const void* p,
os_persistent_to_transient_pointer_manager& mgr
);
Sets the value of a persistent pointer to a transient object and returns the old value.
p_pointer is the pointer that is to be changed, and p is the new value to be stored
into that pointer. The mgr argument is a user-supplied object that manages the class
of objects that pointer points at. See os_persistent_to_transient_pointer_
manager::release() on page 277 for more information about the user-supplied
manager object.
90
C++ A P I Reference
Chapter 2: Class Library
For information about using this function to manage persistent pointers to transient
objects, Persistent Pointers to Transient Objects in Chapter 1 of the Advanced C++
A P I User Guide.
objectstore::set_propagate_on_commit()
static void set_propagate_on_commit(
os_boolean when_to_propagate
);
For use with ObjectStore / Single applications. Determines when ObjectStore
propagates committed data from the transaction log to the affected database. If
when_to_propagate is nonzero (true), propagations occur whenever a top-level
transaction commits. This is the default.
If when_to_propagate is 0 (false), propagations occur when a database is closed and
the program ends normally. If the program ends prematurely, some of the
committed data in the log might not have been propagated to the database. This data
is propagated the next time ObjectStore is initialized or when
objectstore::propagate_log() is called, provided that the correct transaction log
exists at the time.
In client-server mode, propagation is controlled by server parameters and set_
propagate_on_commit() has no effect.
For information about retrieving when propagations occur, see objectstore::get_
propagate_on_commit() on page 70. For additional information about the log file,
see
• objectstore::propagate_log() on page 79
• objectstore::set_log_file() on page 89
objectstore::set_reserve_as_mode()
static void set_reserve_as_mode(os_boolean new_mode);
See the documentation for the environment variable OS_RESERVE_AS (UNIX Only)
in Managing ObjectStore.
objectstore::set_retain_persistent_addresses()
static void set_retain_persistent_addresses(os_boolean);
If set to true, enables retaining the validity of persistent addresses across transaction
boundaries. After being executed within a given session, pointers to persistent
memory remain valid even after the transaction in which they were retrieved from
the database has executed. This is true until the end of the session. When set to true,
this function has the same effect as setting objectstore:retain_persistent_
addresses() to true.
If set to false, globally disables retaining the validity of persistent addresses across
transaction boundaries.
See also objectstore::reset_persistent_addresses() on page 81.
Release 6.3
91
objectstore
objectstore::set_simple_auth_ui()
static void set_simple_auth_ui(
void(*handler_func)(os_void_p, os_char_const_p, os_char_p,
os_int32, os_char_p, os_int32),
void* data_val
);
Registers an authentication handler function.
handler_func is a handler function that is called by ObjectStore when the
application first attempts to access an ObjectStore server that requires Name
Password authentication (see Managing ObjectStore). The function is responsible for
providing user name and password information.
data_val is a data value that is 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 ObjectStore 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 an server requiring Name
Password authentication. By registering a handler function, you can, for example,
use a dialog instead of standard input and output to obtain authentication
information from an end user.
objectstore::set_suppress_invalid_hard_pointer_errors()
static void set_suppress_invalid_hard_pointer_errors(
os_boolean
);
Allows examination of pages containing pointers that are encoded in export ID form
and that have a hard-pointer representation in the current schema. If suppression is
enabled and such a pointer is encountered during inbound relocation, the pointer is
stored in soft-pointer form even though the schema indicates it should be hard.
objectstore::set_transaction_max_retries()
static void set_transaction_max_retries(
os_unsigned_int32 max_retries
);
Sets the number of times a lexical transaction is retried automatically after being
aborted because of a deadlock.
For information about the macros used to set up a lexical transaction, see Chapter 4,
System-Supplied Macros, on page 469.
objectstore::set_transaction_priority()
static void set_transaction_priority(
os_unsigned_int16 priority
92
C++ A P I Reference
Chapter 2: Class Library
);
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 in the following paragraphs.
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 client should be forced to abort,
and possibly restart, its transaction.
In making this decision, ObjectStore first compares the transaction priorities of all the
participants. If they do not all have equal priority, those 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 ObjectStore server parameter Deadlock Victim. See Managing
ObjectStore.
Note
If all the participants have priority 0, the ObjectStore server victimizes 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 and
set all their priorities to 0. When a deadlock happens, all of them will abort, allowing
you to see what each one of them was doing at the time. You should never use a
priority of 0 unless you want this special debugging behavior.
objectstore::set_transient_delete_function()
static void set_transient_delete_function(
void (*)(os_void_p)
);
Instead of overriding ObjectStore’s global ::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. When
ObjectStore’s ::operator delete( ) is given a transient pointer and set_
transient_delete_function( ) has been called, the specified transient delete
function is called 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. If you want, you can set the value back to 0.
For information about ObjectStore’s global ::operator delete( ), see ::operator
delete() on page 458. For information about implementing your own global
::operator delete( ) to free persistent or transient storage, see
objectstore::free_memory() on page 61.
Release 6.3
93
objectstore
objectstore::set_union_variant()
static void set_union_variant(
void* addr,
const char* type_name,
os_unsigned_int16 variant
);
Indicates to ObjectStore the currently active member object of a union in persistent
memory. addr is the persistent memory address of the union, and type_name is the
name of the union type. The name of a union member object can be either the fully
qualified name (for example, "A::B::C") or the unqualified name (for example,
"C").
The variant argument is the number that corresponds to the position of the active
member object in the union declaration (1 for the first, 2 for the second, and so on; 0
indicates an uninitialized union).
For information about retrieving the currently active member object, see
objectstore::get_union_variant() on page 72. For information about using
persistent unions, see Using Persistent Unions on page 39 of Chapter 1 of the
Advanced C++ A P I User Guide.
objectstore::shutdown()
static void shutdown();
Conducts an orderly shutdown of ObjectStore. In particular, all open databases are
closed to facilitate propagation of committed data from the ObjectStore server log to
the databases.
For ObjectStore / Single, this call attempts to propagate all committed data in the log
and then 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. ObjectStore Technical Support recommends that you use
objectstore::shutdown for both full ObjectStore and ObjectStore / Single
applications.
objectstore::unload_DLL()
static void unload_DLL(os_DLL_handle h);
If h designates a loaded DLL, calling this function unloads it. If h is set to os_null_
DLL_handle, calling this function has no effect. 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 signaled.
objectstore::which_product()
static os_product_type which_product();
94
C++ A P I Reference
Chapter 2: Class Library
Always returns ostore_cpp.
Release 6.3
95
objectstore_exception
objectstore_exception
All TIX exceptions are instances of the class objectstore_exception, including the
system-supplied predefined exceptions (see Chapter 5, Predefined TIX Exceptions,
on page 499) and those you define using the macro DEFINE_EXCEPTION() (see
DEFINE_EXCEPTION() on page 472).
objectstore_exception::signal()
void signal([os_int32 value,] char const* format ...);
Signals the TIX exception for which the function is called. The first argument is
optional. It is used to associate an error code with the signaling of the exception. The
value of the error code can be retrieved; see tix_handler::get_value() on
page 456. The subsequent arguments work as with the function printf(). A format
string is supplied, followed by any number of additional arguments.
When objectstore_exception::signal() is called, control is transferred to the
most recently established handler for the exception, or to one of its parents, and the
message supplied in the format string is ignored. If a handler has not been
established, the exception’s associated message is issued, together with the message
specified by format and associated arguments. The session is then aborted or exited
from, as determined by the environment variable OS_DEF_EXCEPT_ACTION (see
Managing ObjectStore).
For information about the macros that are used to establish TIX exception handlers,
see Chapter 4, System-Supplied Macros, on page 469.
objectstore_exception::vsignal()
void vsignal(
[os_int32 value,]
char const* format,
va_list args
);
Signals the TIX exception for which the function is called. The first argument is
optional. It is used to associate an error code with the signaling of the exception. The
value of the error code can be retrieved; see tix_handler::get_value() on
page 456. The subsequent arguments work as with the function vprintf(). A format
string is supplied, followed by a va_list.
When objectstore_exception::vsignal() is called, control is transferred to the
most recently established handler for the exception, or to one of its parents, and the
message supplied in the format string is ignored. If a handler has not been
established, the exception’s associated message is issued, along with the message
specified by format and associated arguments. The session is then aborted or exited
from, as determined by the environment variable OS_DEF_EXCEPT_ACTION (see
Managing ObjectStore).
For information about the macros that are used to establish TIX exception handlers,
see Chapter 4, System-Supplied Macros, on page 469.
96
C++ A P I Reference
Chapter 2: Class Library
os_access_modifier
class os_access_modifier : public os_member
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents the access
modification performed by a class on an inherited member. os_access_modifier is
derived from os_member.
os_access_modifier::create()
static os_access_modifier& create(os_member* mem);
Creates an os_access_modifier that modifies access to the specified member.
os_access_modifier::get_base_member()
const os_member& get_base_member( ) const;
Returns a reference to the const member whose access was modified.
Overloadings
The following overloading is supported:
os_member& get_base_member( );
Returns a reference to the non-const member whose access was modified.
os_access_modifier::set_base_member()
void set_base_member(os_member& mem);
Updates the member whose access is to be modified.
Release 6.3
97
os_address_space_marker
os_address_space_marker
To use the address space marker feature, create an os_address_space_marker at
some convenient point at which address space consumption that is to be undone is
about to begin (such as the beginning of a query). Later, when os_address_space_
marker::release() is called, all address space reservations added since that
marker was created will be released (subject to the same restrictions mentioned for
objectstore::release_persistent_addresses() on page 81 — some address
space cannot be released during a transaction).
Address space markers can be nested, which means that several markers can be in
effect at the same time. Calling os_address_space_marker::release() on an
outer marker releases any markers nested within it.
The os_address_space_marker::retain() function allows selective release of
address space, similar to creating os_retain_address objects, but without the
requirement for stack allocation (which binds the usage to a lexical scope). Call os_
address_space_marker::retain() on any pointers that should remain valid
across the release boundary before calling os_address_space_
marker::release(). The os_address_space_marker::retain() function can
also be passed a marker. In this case, the address space required by the pointer is not
released until that marker is released. It is not possible to use the os_address_
space_marker::retain() function on an address to release it sooner, by a more
nested marker; attempts to do so are ignored.
The os_address_space_marker::release() function releases address space
added since the creation of the mark, minus any address space retained by calls to
the os_address_space_marker::retain() function, as well as any retained by os_
retain_address objects. The release() function can be called on a marker
repeatedly, each time releasing the address space accumulated since the previous
release or since the marker was created.
If a marker is deleted and no call to os_address_space_marker::release() is
made, the marker is removed and the address space that it controlled is now
controlled by its previous marker. If there is no previous marker, the address space
is not governed by any marker and is no longer incrementally releasable.
After the outermost marker is created, no more than 232–2 minus 1 additional
markers can be created before the outermost one is deleted. This is true even if some
or all of the inner markers are deleted.
Like objectstore::release_persistent_addresses(), markers cannot be
released within nested transactions.
The implementation of os_address_space_marker::release(), besides possibly
not freeing as much address space as objectstore::release_persistent_
addresses(), also does not cool the client cache as much. The os_address_space_
marker::release() function must relocate out all pages that were relocated in or
modified after the marker was constructed.
98
C++ A P I Reference
Chapter 2: Class Library
os_address_space_marker::get_current()
static os_address_space_marker* get_current();
Returns the current address space marker. The current marker is defined as the most
recently constructed marker that has not yet been deleted. This function can be used
with nested markers.
os_address_space_marker::get_level()
os_unsigned_int32 get_level() const;
The level of a marker is 1 if there was no current marker when it was created.
Otherwise, the level is 1 greater than the level of the previously created marker. Use
get_level() to quickly compare address space markers. Markers with lower levels
precede those with higher levels. This function can be used with nested markers.
os_address_space_marker::get_next()
os_address_space_marker* get_next() const;
Returns the next address space marker (or NULL if the this marker is the last). The
next address space marker is the first one that was created after the this address
space marker. This function can be used with nested markers.
os_address_space_marker::get_previous()
os_address_space_marker* get_previous() const;
Returns the previous address space marker (or NULL if the this marker is the first).
The previous address space marker is the last one that was created before the this
address space marker. This function can be used with nested markers.
os_address_space_marker::of()
static os_address_space_marker* of(void* p);
Returns the address space marker (or NULL) with the highest level that, when
released, releases the address space needed for pointer p.
os_address_space_marker::os_address_space_marker()
os_address_space_marker();
Creates an os_address_space_marker.
os_address_space_marker::release()
void release(os_boolean unmap_all_fast = 0);
Releases the address space that was added to the PSR (persistent storage region)
since the address space marker was created or since the last time os_address_
space_marker::release() was called.
If the unmap_all_fast argument is nonzero (true), ObjectStore unmaps the entire
PSR. Such an operation takes less time than unmapping only the marked pages.
Note, however, that setting unmap_all_fast to true can decrease performance by
Release 6.3
99
os_address_space_marker
causing the application to take more page faults after releasing the marker. The
default — unmap_all_fast is set to 0 (false) — is to unmap only the marked pages.
If you use the unmap_all_fast argument, you should set it to true only when you
are sure that the application will no longer need to access the unmapped pages or is
near the end of a transaction, when all pages in the PSR will be unmapped anyway.
Deleting a marker does not release the address space it has marked. Conversely,
releasing a marker does not deactivate or delete it. This means you can call the
release() function again on the same marker after more address space has been
accumulated. os_address_space_marker::release() does not affect the value of
os_address_space_marker::get_current(). This function can be used with
nested markers.
os_address_space_marker::retain()
static void retain(
void* p,
os_address_space_marker* marker = NULL
);
Returns the address space marker (or NULL) with the highest level that, when
released, releases the address space needed for pointer p. Retains space needed by
pointer p back to some marker or, if the marker is NULL, back past all markers.
os_address_space_marker::~os_address_space_marker()
~os_address_space_marker();
Destructor function.
100
C++ A P I Reference
Chapter 2: Class Library
os_anonymous_indirect_type
class os_anonymous_indirect_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a const or
volatile type. This class is derived from os_type.
os_anonymous_indirect_type::create()
static os_anonymous_indirect_type& create(
os_type* target_type
);
Creates an anonymous indirect type with the specified target_type.
os_anonymous_indirect_type::get_target_type()
const os_type& get_target_type( ) const;
Returns the type to which the const or volatile specifier applies. For example, the
type const int is represented as an instance of os_anonymous_indirect_type
whose target type is an instance of os_integral_type.
os_anonymous_indirect_type::is_const()
os_boolean is_const( ) const;
Sets the name of an os_anonymous_indirect_type of type const.
os_anonymous_indirect_type::is_volatile()
os_boolean is_volatile( ) const;
Sets the name of an os_anonymous_indirect_type of type volatile.
os_anonymous_indirect_type::set_is_const()
void set_is_const(os_boolean);
Sets the name of an os_anonymous_indirect_type of type const.
os_anonymous_indirect_type::set_is_volatile( )
void set_is_volatile(os_boolean);
Sets the name of an os_anonymous_indirect_type of type volatile.
Release 6.3
101
os_app_schema
os_app_schema
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents an application
schema stored in an application schema database, or a component schema stored in
a component schema database. os_app_schema is derived from os_schema.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_app_schema::get()
static const os_app_schema& get( );
Returns the schema of the application making the call. Signals err_no_schema if the
schema could not be found.
Overloadings
The following overloading for get() is supported:
static const os_app_schema &get(const os_database& db);
Returns the schema of the specified database. Signals err_no_schema if the specified
database is not an application or component schema database.
102
C++ A P I Reference
Chapter 2: Class Library
os_application_schema_info
This class information in an application about its application schema, including the
path name of the schema database, pointers to vtbls, and so on. Its base class is os_
schema_info; for more information, see os_schema_info on page 350.
Required
header files
Release 6.3
You must include the header file <ostore/nreloc/schftyps.hh>.
103
os_archiver
os_archiver
The os_archiver class provides the means to archive databases from an ObjectStore
application. For more information on using a command-line utility to archive
databases, see osarchiv in Managing ObjectStore.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/dbutil.hh>.
os_archiver::os_archiver()
os_archiver(const char* archiver_ID)
Constructs the necessary class for archiving databases. The archiver_ID argument
should be a unique character string identifying this archiver process in the backrest
log, as described in os_dbutil::start_backrest_logging() on page 191.
os_archiver::~os_archiver()
~os_archiver();
Performs internal cleanup of the archiver.
os_archiver::add_db_to_archive()
void add_db_to_archive(const char * db_pathname);
Adds the database specified by the db_pathname argument to the archiver.
os_archiver::change_time_interval()
void change_time_interval(os_unsigned_int32 n_seconds);
Changes the current time interval between snapshots.
os_archiver::get_current_archive_file_name()
char * get_current_archive_file_name();
Returns the pathname of the current archive file that must be deleted by the caller.
os_archiver::get_status()
os_int32 get_status();
Returns the current status of the archiver process. The possible return values are:
Return Value Meaning
104
-1
The archiver process is still running.
0
The archiver process has either completed successfully or has not
yet started.
1
The archiver process has failed. Check the backrest log for
additional information.
C++ A P I Reference
Chapter 2: Class Library
os_archiver::remove_db_from_archive()
void remove_db_from_archive(const char * db_pathname);
Removes the database specified by the db_pathname argument from the archiver.
os_archiver::start_archiver()
void start_archiver(os_archiver_options * options);
Starts the archiver process in a separate thread and then return immediately. The
options calling argument should have the ncessary data members set. For
information about the options you can use, see os_archiver_options on page 106.
os_archiver::stop_archiver()
void stop_archiver();
Stops the current archiver process after completing the last snapshot.
os_archiver::take_a_snapshot()
void take_a_snapshot();
Takes a specific snapshot.
Release 6.3
105
os_archiver_options
os_archiver_options
The os_archiver_options class specifies data members that must be set in order for
an instance of the os_archiver class to archive ObjectStore databases. An instance
of the os_archiver_options class is used as an argument when starting the
archiver process. See also os_archiver on page 104 for more information on the os_
archiver class.
For more information on using a command-line utility to archive databases, see
osarchiv in Managing ObjectStore.
Required
header files
Programs using the os_archiver_options class must include
<ostore/ostore.hh>, followed by <ostore/dbutil.hh>.
Public data
members
The os_archiver_options class has the following public data members:
os_boolean flag_recursive;
os_boolean flag_compression;
os_unsigned_int32 time_interval;
os_unsigned_int32 server_buf_size_in_KB;
os_unsigned_int32 max_file_size_in_KB;
os_unsigned_int32 network_timeout;
os_unsigned_int32 n_archive_databases;
const char* import_file;
const char* archive_record_file;
const char* archive_directory;
const char** archive_databases;
The following describes the public data members:
flag_recursive
Instructs the archiver process to descend into any rawfs directories
specified in the archive_databases array and add all rawfs databases
found to the list of databases to be archived. This option has no effect when
archiving file databases; you must explicitly specify each file database.
Default is false; only databases in the specified directory will be archived.
flag_compression
When true, the archiver process compresses the archived data from
osserver which reduces the amount of disk space required for the archiveimage files
Default is false; no compression.
time_interval
Specifies in seconds an integer that the archiver process uses as the interval
between snapshots.
Default is 0; no snapshots are taken automatically and os_
archiver::take_a_snapshot() must be called to take a snapshot.
server_buf_size_in_KB Specifies the size of the buffer used by the osservers contacted by the
archiver process.
Default is 1MB
max_file_size_in_KB
Specifies the maximum amount of data to write to an archive file. When an
archive file is full, the archiver process automatically starts using the next
file in the archive file sequence.
Default is 2048KB.
106
C++ A P I Reference
Chapter 2: Class Library
Sets the timeout value in seconds that the archiver process will wait for
osserver to respond.
network_timeout
Default is 10 hours.
n_archive_databases
Specifies the number of database paths listed in the archive_databases
array.
Default is 0; in this case, the import_file option must be set.
Specifies the name of a file that contains the list of file or rawfs database
path names to be archived. The archiver process cannot read such a list
from standard input
import_file
Default is NULL.
archive_record_file
Specifies the path of the file that an archiver process uses to record the
cluster change IDs for the archive set. The archiver process updates this file
each time it successfully records committed changes to the archive set. The
archive_record_file is comparable to the incremental_record_file
data member for os_backup_options.
archive_directory
This is required. Specifies the directory in which to create the archive log
file.
archive_databases
Specifies an array of databases to archive; the number of entries in the array
must correspond to the number specified by n_archive_databases. The
user is responsible for deleting these objects.
Default is NULL; in this case, the import_file option must be set.
Member
functions
The following functions are public members of the os_archiver_options class:
os_archiver_options::os_archiver_options()
os_archiver_options();
Constructs the os_archiver_options class and sets all options to their default
values.
os_archiver_options::~os_archiver_options()
~os_archiver_options() {}
Performs internal cleanup.
os_archiver_options::reset()
void reset();
Resets all options back to their default values.
Release 6.3
107
os_array_type
os_array_type
class os_array_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ array type.
This class is derived from os_type.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_array_type::create()
static os_array_type& create(
os_unsigned_int32 number_of_elements,
os_type* elem_type
);
Creates an array type with the specified number of elements and the specified
element type.
os_array_type::get_element_type()
const os_type& get_element_type( ) const;
Returns the type of element contained in instances of the specified array type.
Overloadings
The following overloading for get_element_type() is supported:
os_type& get_element_type( );
Returns the type of element contained in instances of the specified array type.
os_array_type::get_number_of_elements()
os_unsigned_int32 get_number_of_elements( ) const;
Returns the number of elements associated with the specified array type. If the
number is not known, 0 is returned.
os_array_type::set_element_type()
void set_element_type(os_type& elem_type);
Specifies the type of element contained in instances of the specified array type.
os_array_type::set_number_of_elements()
void set_number_of_elements(os_unsigned_int32);
Specifies the number of elements associated with the specified array type.
108
C++ A P I Reference
Chapter 2: Class Library
os_authentication
The os_authentication class enables applications to access the Windows registry
location used by ObjectStore. This location stores such information as parameters
used by the ObjectStore server and cache manager as well as UNIX user and group
IDs.
By default, the registry location used by ObjectStore is
HKEY_LOCAL_MACHINE\SOFTWARE\Object Design Inc.\ObjectStore 6.0
You can call the os_authentication::set_nt_registry_location() function to
specify a different location in the registry.
For information about setting the Windows registry location, see Changing the
Registry Location for ObjectStore (Windows Only) in Managing ObjectStore, Chapter
8.
Type definitions
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_int16 is defined as
an unsigned 16-bit integer type.
Required
header file
Programs using this class must include <ostore/ostore.hh>.
os_authentication::get_nt_registry_location()
static void get_nt_registry_location(
char* location,
os_unsigned_int16 size);
Retrieves the registry location used by ObjectStore, relative to HKEY_LOCAL_
MACHINE\SOFTWARE\. The location is stored in location, and size specifies the
maximum size of the allocation referenced by location. If location is not large
enough to hold the string, the function signals the err_os_auth_reg_string_
array_too_small exception. The maximum length of the string returned in
location is os_authentication::MAX_REGISTRY_STRING_LENGTH.
The user is responsible for managing the memory allocated for location.
os_authentication::set_nt_registry_location()
static void set_nt_registry_location(
const char* location);
Sets the registry location for ObjectStore. The string referenced by location is
appended to HKEY_LOCAL_MACHINE\SOFTWARE\ to form the absolute location. If the
length of location exceeds os_authentication::MAX_REGISTRY_STRING_LENGTH,
this function signals err_os_auth_reg_string_too_long exception. If location is
null or empty, this function signals the err_os_auth_reg_string_invalid
exception .
Release 6.3
109
os_backup
os_backup
The os_backup class provides the means to backup databases from an ObjectStore
application.
For more information on using a command-line utility to back up databases, see
osbackup in Managing ObjectStore.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/dbutil.hh>.
os_backup::os_backup()
os_backup(const char* backup_ID)
Constructs the necessary class for backing up databases. The backup_ID argument
should be a unique character string identifying this backup process in the backrest
log, as described in os_dbutil::start_backrest_logging() on page 191.
os_backup::~os_backup()
~os_backup();
Performs internal cleanup of the backup. Calling ~os_backup() while the process is
running can result in an inconsistent backup image file.
os_backup::get_status()
os_int32 get_status();
Returns the current status of the backup process. The possible return values and their
meanings are:
Return Value Meaning
-1
The backup process is still running.
0
The backup process has either completed successfully or has not
yet started.
1
The backup process has failed. Check the backrest log for
additional information.
os_backup::start_and_run_backup()
os_boolean start_and_run_backup(os_backup_options & options);
Starts and runs the backup process to completion. The options calling argument
should have the necessary data members set. A return code of zero indicates the
backup process successfully completed. For a non-zero return code, check the
backrest log for further information. For information about the options you can use,
see os_backup_options on page 112.
110
C++ A P I Reference
Chapter 2: Class Library
os_backup::start_backup()
void start_backup(os_backup_options * options);
Starts the backup process in a separate thread and then return immediately. The
options calling argument should have the necessary data members set. After calling
start_backup() call os_backup::get_status() to determine when the backup is
complete. For information about the options you can use, see os_backup_options
on page 112.
os_backup::stop_backup()
void stop_backup();
Stops the backup process by waiting for the backup process to complete before
returning. After calling stop_backup() call os_backup::get_status() to verify
that the backup was successful.
Release 6.3
111
os_backup_options
os_backup_options
The os_backup_options class specifies data members that must be set in order for
an instance of the os_backup class to backup ObjectStore databases. An instance of
the os_backup_options class is used as an argument when starting the backup
process. See also os_backup on page 110 for more information on the os_backup
class.
For more information on using a command-line utility to back up databases, see
osbackup in Managing ObjectStore.
Required
header files
Programs using the os_backup_options class must include <ostore/ostore.hh>,
followed by <ostore/dbutil.hh>.
Public data
members
The os_backup_options class has the following public data members:
os_boolean flag_recursive;
os_boolean flag_compression;
os_unsigned_int32 server_buf_size_in_KB;
os_unsigned_int32 max_file_size_in_KB;
os_unsigned_int32 network_timeout;
os_unsigned_int32 blocking_factor;
os_unsigned_int32 backup_level;
os_unsigned_int32 n_backup_databases;
os_unsigned_int32 n_backup_files;
os_backup_switch_volume_hook switch_volume_hook;
void * switch_volume_hook_context;
const char* switch_volume_command;
const char* import_file;
const char* incremental_record_file;
const char** backup_files;
const char** backup_databases;
The following describes the public data members:
flag_recursive
Instructs the backup process to descend into any
rawfs directories specified in the backup_
databases array and add all rawfs databases
found to the list of databases to be backed up.
This option has no effect when backing up file
databases; you must explicitly specify each file
database.
Default is false; only databases in the specified
directory will be backed up.
flag_compression
When true, the backup process compresses the
backup data from osserver which reduces the
amount of disk space required for the backupimage files
Default is false; no compression.
server_buf_size_in_KB
Specifies the size of the buffer used by the
osservers contacted by the backup process.
Default is 1MB
112
C++ A P I Reference
Chapter 2: Class Library
max_file_size_in_KB
Set the size in kilobytes of the volume being
dumped to. When the size is reached, the
application will be prompted to insert a new
tape. The type of prompt depends on whether
switch_volume_command or switch_volume_
hook is specified. If a switch_volume_hook
function is defined, that function is called. If a
function is not defined but the switch_volume_
command is set, the default is to process the
prompt using stdout/stdin.
This option is mainly for use when you are
backing up to a tape device because end-ofmedia cannot be detected reliably on some
systems. On Solaris, this option is not required
because the end of the tape is reliably signaled
to the application without any loss of data On
other systems, if you do not specify this option,
the backup process will terminate when it
reaches the end of the tape.
You can use this option together with the
backup_files option to perform a multivolume
backup. However, if an insufficient number of
files are specified with backup_files option,
the backup will terminate.
Default is 0; no volume switching is done.
network_timeout
Sets the timeout value in seconds that the
backup process will wait for osserver to
respond.
Default is 10 hours.
blocking_factor
Specifies a blocking factor to use for tape input
and output. The blocking factor is in units of
512-byte blocks. This parameter is ignored for
regular files. The maximum setting is 512
blocks.
Default on UNIX is 126 blocks.
backup_level
Specifies the level of the backup as an integer
from 0 to 9. See the -l option in osbackup in
Managing ObjectStore for more information
Default is level 0.
n_backup_databases
Specifies the number of database paths listed in
the backup_databases array.
Default is 0; in this case, the import_file option
must be set.
n_backup_files
This is required. It specifies the number of
backup image files specified in the backup_
files array.
Default is 0.
Release 6.3
113
os_backup_options
switch_volume_hook
Specifies a pointer to a user-defined function in
the format:
char* my_function(
os_boolean insert_next_tape,
os_unsigned_int32 volume_num,
void* context)
This function is called at a media volume
switch, such as a request for the next tape, a file
having reached the limit specified by the max_
file_size_in_KB option, or an out of file disk
space condition. If insert_next_tape is true,
the next tape volume specified by volume_num
should be inserted and NULL returned. If
insert_next_tape is false, the next file
pathname string should be returned, which is
deleted by the caller. The context argument is
user-specified data; see the switch_volume_
hook_context option, below.
Default is NULL; no function defined.
switch_volume_hook_context
The value of this pointer is passed to switch_
volume_hook through the context calling
argument. This data member should point to
any user data that will be needed within the
hook.
Default is NULL.
switch_volume_command
Specifies the path of a command to be executed
when the backup process reaches the end of the
media. This command should mount the next
volume before returning. The exit status from
this command must be 0 or the backup
operation aborts.
Default is NULL.
import_file
Specifies the name of a file that contains the list
of file or rawfs database path names to be
backed up. If you specify “-” (hyphen) as the
import_file name, the database list is read
from standard input.
Default is NULL.
114
C++ A P I Reference
Chapter 2: Class Library
incremental_record_file
This is required. Specifies the incremental
record file which contains information about the
databases that have been backed up and when
they were backed up. This information is used
to determine the clusters within a database that
have been modified since the last backup at a
lower level; only modified clusters are backed
up. The incremental record file is comparable to
the os_archive_options::archiver_record_
file. Performing a backup at any level for
which no previous information exists is
equivalent to doing a level 0 backup for that
database.
backup_files
This is required. Specifies an array of backup
image files; the number of entries in the array
must correspond to the number specified by n_
backup_files. The backup will be aborted if
the backup device cannot be opened (for
example, if a tape is write-protected or is not
loaded). This option raises an exception that
indicates the problem.
backup_databases
Specifies an array of databases to backup; the
number of entries in the array must correspond
to the number specified by n_backup_
databases.
Default is NULL; in this case, the import_file
option must be set.
Member
functions
The following functions are public members of the os_backup_options class:
os_backup_options::os_backup_options()
os_backup_options();
Constructs the os_backup_options class and sets all options to their default values.
os_backup_options::~os_backup_options()
~os_backup_options() {}
Performs internal cleanup.
os_backup_options::reset()
void reset();
Resets all options back to their default values.
Release 6.3
115
os_base_class
os_base_class
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of os_base_class represents a class
from which another class is derived, together with the nature of the derivation (that
is, virtual or nonvirtual, and private, public, or protected).
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_base_class::create()
static os_base_class& create(
os_unsigned_int32 access,
os_boolean is_virtual,
os_class_type* associated_class
);
Creates an os_base_class. The arguments specify the initial values for the
attributes access, is_virtual, and associated_class.
os_base_class::get_access()
int get_access( ) const;
Returns an enumerator describing the access to the base class members. The possible
return values are os_base_class::Public, os_base_class::Private, or os_
base_class::Protected.
os_base_class::get_class()
const os_class_type& get_class( ) const;
Returns a reference to a const os_class_type — the class serving as base class in
the derivation represented by the specified os_base_class object.
Overloadings
The following overloading for get_class() is supported:
os_class_type& get_class( );
Returns a reference to a non-const os_class_type — the class serving as base class
in the derivation represented by the specified os_base_class object.
os_base_class::get_offset()
os_unsigned_int32 get_offset( ) const;
Returns the offset in bytes to the base class from the immediately enclosing class. For
virtual bases, this offset is meaningful only if the base class was obtained by a call to
os_class_type::get_allocated_virtual_base_classes( ).
Overloadings
116
The following overloading for get_offset() is supported:
C++ A P I Reference
Chapter 2: Class Library
os_unsigned_int32 get_offset(const os_class_type& base_class) const;
Returns the offset in bytes to the base class from the specified most derived class.
this must be a virtual base class.
os_base_class::get_size()
os_unsigned_int32 get_size( ) const;
Returns the size in bytes of the base class.
os_base_class::get_virtual_base_class_pointer_offset()
os_unsigned_int32 get_virtual_base_class_pointer_offset( ) const;
Returns the offset of the virtual base class pointer.
os_base_class::is_virtual()
os_boolean is_virtual( ) const;
Returns 1 if and only if the specified base class is virtual.
os_base_class::Private
This enumerator is a possible return value from os_base_class::get_access( ),
indicating private access.
os_base_class::Protected
This enumerator is a possible return value from os_base_class::get_access( ),
indicating protected access.
os_base_class::Public
This enumerator is a possible return value from os_base_class::get_access( ),
indicating public access.
os_base_class::set_access()
void set_access(os_unsigned_int32);
Specifies an enumerator describing the access to the base class members. The
possible values for the argument are
• os_base_class::Public
• os_base_class::Private
• os_base_class::Protected
os_base_class::set_class()
void set_class(os_class_type& base_class);
Specifies the class serving as base class in the derivation represented by the specified
os_base_class object.
Release 6.3
117
os_base_class
os_base_class::set_offset()
void set_offset(os_unsigned_int32);
Sets the offset in bytes of the base class from the immediately enclosing class.
os_base_class::set_virtual_base_class_no_pointer()
void set_virtual_base_class_no_pointer( );
Specifies that the base class has no virtual base class pointer.
os_base_class::set_virtual_base_class_pointer_offset()
void set_virtual_base_class_pointer_offset(os_unsigned_int32);
Sets the offset of the virtual base class pointer.
os_base_class::set_virtuals_redefined()
void set_virtuals_redefined(os_boolean);
Specifies whether the base class redefines any virtual functions.
os_base_class::virtual_base_class_has_pointer()
os_boolean virtual_base_class_has_pointer( ) const;
Returns nonzero if the base class has a virtual base class pointer.
os_base_class::virtuals_redefined()
os_boolean virtuals_redefined( ) const;
Returns nonzero if the base class redefines any virtual functions.
118
C++ A P I Reference
Chapter 2: Class Library
os_class_type
class os_class_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of os_class_type represents a C++
class. os_class_type is derived from os_type.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_class_type::Anonymous_union
This enumerator is a possible return value from os_class_type::get_class_
kind( ). It indicates an anonymous union type.
os_class_type::Class
This enumerator is a possible return value from os_class_type::get_class_
kind( ). It indicates a class declared with the class-key class.
os_class_type::create()
static os_class_type& create(const char* name);
Creates a new class with the specified name (which is copied by ObjectStore). It
initializes the other attributes of os_class_type as follows:
Overloadings
Attribute
Value
base_classes
empty os_List<os_base_class*>
members
empty os_List<os_member*>
defines_virtual_functions
0
class_kind
os_class_type::Class
defines_get_os_typespec_function
0
is_template_class
0
is_persistent
0
is_forward_definition
1
The following overloading for create() is supported:
static os_class_type& create(
const char* name,
os_List<os_base_class*>& base_classes,
os_List<os_member*>& members,
os_boolean defines_virtual_functions
);
Release 6.3
119
os_class_type
Creates a new class. The arguments specify the initial values for the attributes name,
base_classes, members, and defines_virtual_functions. The initial values for
the remaining attributes are as follows:
Attribute
Value
class_kind
os_class_type::Class
defines_get_os_typespec_function
0
is_template_class
0
is_persistent
0
is_forward_definition
0
If you create a class with the MOP, there is no direct way to make it compiler
heterogeneous.
os_class_type::declares_get_os_typespec_function()
os_boolean declares_get_os_typespec_function( ) const;
Returns nonzero if and only if the specified class declares a get_os_typespec( )
member function.
os_class_type::defines_virtual_functions()
os_boolean defines_virtual_functions( ) const;
Returns nonzero if and only if the specified class defines any virtual functions.
os_class_type::find_base_class()
const os_base_class* find_base_class(const char* class_name) const;
Returns a pointer to the const os_base_class whose class has the given name and
is a base class of this. Either the inheritance is direct or the base class is a virtual base
class. If there is no such class, 0 is returned. err_mop_forward_definition is
signaled if the specified class is known only through a forward definition.
Overloadings
The following overloading for find_base_class() is supported:
os_base_class *find_base_class(const char* class_name);
Returns a pointer to the non-const os_base_class whose class has the given name
and is a base class of this. Either the inheritance is direct or the base class is a virtual
base class. If there is no such class, 0 is returned. err_mop_forward_definition is
signaled if the specified class is known only through a forward definition.
os_class_type::find_member_variable()
const os_member_variable* find_member_variable(
const char* name
) const;
Returns a pointer to a const os_member_variable representing the data member of
this with the given name. The member must be defined by this, not inherited by it.
120
C++ A P I Reference
Chapter 2: Class Library
If there is no such data member, 0 is returned. err_mop_forward_definition is
signaled if the specified class is known only through a forward definition.
Overloadings
The following overloading of find_member_variable() is supported:
os_member_variable *find_member_variable(const char *name);
Returns a pointer to a non-const os_member_variable representing the data
member of this with the given name. The member must be defined by this, not
inherited by it. If there is no such data member, 0 is returned. err_mop_forward_
definition is signaled if the specified class is known only through a forward
definition.
os_class_type::get_access_of_get_os_typespec_function()
os_member::os_member_access
get_access_of_get_os_typespec_function( ) const;
Returns one of the following enumerators:
• os_member::Private
• os_member::Protected
• os_member::Public
os_class_type::get_allocated_virtual_base_classes()
os_list get_allocated_virtual_base_classes( ) const;
Returns a list of pointers to const os_base_class objects. Each os_base_class
object represents a virtual base class from which the specified class inherits (that is,
whose storage is allocated as part of the specified class). The order of list elements is
not significant. err_mop_forward_definition is signaled if the specified class is
known only through a forward definition.
Overloadings
The following overloading is supported:
os_list get_allocated_virtual_base_classes( );
Returns a list of pointers to non-const os_base_class objects. Each os_base_
class object represents a virtual base class from which the specified class inherits
(that is, whose storage is allocated as part of the specified class). The order of list
elements is not significant. err_mop_forward_definition is signaled if the
specified class is known only through a forward definition.
os_class_type::get_base_classes()
os_list get_base_classes( ) const;
Returns a list, in declaration order, of pointers to const os_base_class objects.
Each os_base_class object represents a class from which the given class is derived,
together with the nature of the derivation (virtual or nonvirtual, and public, private,
or protected). err_mop_forward_definition is signaled if the specified class is
known only through a forward definition.
Overloadings
The following overloading is supported:
os_list get_base_classes( );
Release 6.3
121
os_class_type
Returns a list, in declaration order, of pointers to non-const os_base_class objects.
Each os_base_class object represents a class from which the given class is derived,
together with the nature of the derivation (virtual or nonvirtual, and public, private,
or protected). err_mop_forward_definition is signaled if the specified class is
known only through a forward definition.
os_class_type::get_class_kind()
os_unsigned_int32 get_class_kind( ) const;
Returns an enumerator indicating the kind of class represented by the specified
instance of os_class_type:
• os_class_type::Struct indicates a struct.
• os_class_type::Union indicates a named union.
• os_class_type::Anonymous_union indicates an anonymous union.
• os_class_type::Class indicates a class declared with the class-key class.
os_class_type::get_dispatch_table_pointer_offset()
os_int32 get_dispatch_table_pointer_offset( ) const;
Returns the offset at which the pointer to the dispatch table is stored. The dispatch
table is the one that was generated by the compiler currently in use. This function
signals err_mop if there is no dispatch table.
os_class_type::get_dispatch_table_pointer_offset_other_
compiler()
os_int32 get_dispatch_table_pointer_offset_other_compiler( ) const;
Returns the offset at which the pointer to the dispatch table is stored. The compiler
that generated the dispatch table is not necessarily the one currently in use. This
function signals err_mop if there is no dispatch table.
os_class_type::get_indirect_virtual_base_classes()
os_list get_indirect_virtual_base_classes( ) const;
Returns a list of pointers to const os_base_class objects. Each os_base_class
object represents a virtual base class from which the specified class inherits virtually
and indirectly. The order of list elements is not significant. err_mop_forward_
definition is signaled if the specified class is known only through a forward
definition.
Overloadings
The following overloading is supported:
os_list get_indirect_virtual_base_classes( );
Returns a list of pointers to non-const os_base_class objects. Each os_base_
class object represents a virtual base class from which the specified class inherits
virtually and indirectly. The order of list elements is not significant. err_mop_
forward_definition is signaled if the specified class is known only through a
forward definition.
122
C++ A P I Reference
Chapter 2: Class Library
os_class_type::get_members()
os_list get_members( ) const;
Returns a list, in declaration order, of pointers to const os_member objects. Each os_
member object represents a member defined by the specified class. Note that
currently only discriminant member functions are stored in the schema. err_mop_
forward_definition is signaled if the specified class is known only through a
forward definition.
Overloadings
The following overloading is supported:
os_list get_members( );
Returns a list, in declaration order, of pointers to non-const os_member objects. Each
os_member object represents a member defined by the specified class. Note that
currently only discriminant member functions are stored in the schema. err_mop_
forward_definition is signaled if the specified class is known only through a
forward definition.
os_class_type::get_most_derived_class()
static const os_class_type& get_most_derived_class(
const void* obj,
const void*& most_derived_object
) const;
If obj points to the value of a data member for some other object, o, this function
returns a reference to the most derived class of which o is an instance. A class, c1, is
more derived than another class, c2, if c1 is derived from c2, or if c1 is derived from
a class derived from c2, and so on. The most_derived_object argument is set to the
beginning of the instance of the most derived class. There is one exception to this
behavior, described in the following paragraphs.
If obj points to an instance of a class, o, but not to one of its data members (for
example, because the memory occupied by the instance begins with a virtual table
pointer rather than a data member value), the function returns a reference to the
most derived class of which o is an instance. The most_derived_object argument
is set to the beginning of the instance of the most derived class. There is one exception
to this behavior, described in the following paragraph and example.
If obj does not point to the memory occupied by an instance of a class, most_
derived_object is set to 0, and err_mop is signaled. ObjectStore issues an error
message such as the following:
<err-0008-0010>Unable to get the most derived class in os_class_
type::get_most_derived_class( ) containing the address 0x%lx.
Following is an example:
Example
class B {
public:
int ib;
};
class D : public B {
public:
Release 6.3
123
os_class_type
int id;
};
class C {
public:
int ic;
D cm;
};
void baz ( ) {
C* pC = new (db) C;
D *pD = &C->cm;
int *pic = &pC->ic, *pid = &pC->cm.id, *pib = &pC->cm.ib;
...
}
Invoking get_most_derived_class( ) on the pointers pic, pid, and pib produces
the results shown in the following table:
First Argument
(object)
Second Argument
(most_derived_object)
Return Value
(os_class_type)
pic
pC
C
pid
pD
D
pib
pD
D
The exception to the behavior described previously can occur when a class-valued
data member is collocated with a base class of the class that defines the data member.
If a pointer to such a data member, which is also a pointer to such a base class, is
passed to get_most_derived_class( ), a reference to the value type of the data
member is returned, and most_derived_object is set to the same value as obj.
Consider, for example, the following class hierarchy:
Example
class C0 {
public:
int i0;
};
class B0 {
public:
void f0( );
};
class B1 : public B0 {
public:
virtual void f1();
C0 c0;
};
class C1 : public B1 {
public:
static os_typespec* get_os_typespec();
int i1;
};
Some compilers optimize B0 so that it has zero size in B1 (and C1). This means the
class-valued data member c0 is collocated with a base class, B0, of the class, C1, that
defines the data member.
124
C++ A P I Reference
Chapter 2: Class Library
Given the following:
C1
C1
B0
C0
c1;
* pc1 = & c1;
* pb0 = (B0 *)pc1;
* pc0 = & pc1->c0;
the pointers pb0 and pc0 will have the same value because of this optimization.
In this case, get_most_derived_class( ) called on the pb0 or pc0 returns a
reference to the os_class_type for C0 (the value type of the data member c0), and
most_derived_object is set to the same value as obj.
If B1 is instead defined as
class B1 : public B0 {
public:
virtual void f1();
int i;
C0 c0;
};
and
int * pi = & pc1->i;
pb0 and pi have the same value because of the optimization, but the base class, B0,
is collocated with an int-valued data member rather than a class-valued data
member. get_most_derived_class( ) called on pb0 or pi returns a pointer to the
os_class_type for the class C1 and sets most_derived_object to the same value as
pc1.
os_class_type::get_name()
const char *get_name( ) const;
Returns the name of the specified class.
os_class_type::get_pragmas()
os_List<os_pragma*> get_pragmas( ) const;
Returns the pragmas associated with the specified class.
os_class_type::get_size_as_base()
os_unsigned_int32 get_size_as_base( ) const;
Returns the size of the specified class when serving as a base class.
os_class_type::get_source_position()
void get_source_position(
const char*& file,
os_unsigned_int32& line
) const;
Returns the source position associated with the specified class.
Release 6.3
125
os_class_type
os_class_type::has_constructor()
os_boolean has_constructor( ) const;
Returns nonzero if the class defines a constructor.
os_class_type::has_destructor()
os_boolean has_destructor( ) const;
Returns nonzero if the class defines a destructor.
os_class_type::has_dispatch_table()
os_boolean has_dispatch_table( ) const;
Returns nonzero if the class has a dispatch table. The dispatch table is the one that
was generated by the compiler currently in use.
os_class_type::has_dispatch_table_other_compiler()
os_boolean has_dispatch_table_other_compiler( ) const;
Returns nonzero if the class has a dispatch table. The compiler that generated the
dispatch table is not necessarily the one currently in use.
os_class_type::introduces_virtual_functions()
os_boolean introduces_virtual_functions( ) const;
Returns nonzero if and only if the class defines, rather than merely inherits, a virtual
function.
You can set this attribute with set_introduces_virtual_functions( ).
os_class_type::is_abstract()
os_boolean is_abstract( ) const;
Returns nonzero if and only if the specified class is abstract.
os_class_type::is_forward_definition()
os_boolean is_forward_definition( ) const;
Returns 1 if and only if the specified class is known only through a forward
definition.
os_class_type::is_persistent()
os_boolean is_persistent( ) const;
Returns nonzero if and only if the specified class is marked as persistent.
os_class_type::is_template_class()
os_boolean is_template_class( ) const;
Returns 1 if and only if the specified class is a template class.
126
C++ A P I Reference
Chapter 2: Class Library
os_class_type::operator os_instantiated_class_type&()
operator const os_instantiated_class_type&( ) const;
Provides for safe casts from os_class_type to const os_instantiated_class_
type. If the cast is not permissible, err_mop_illegal_cast is signaled.
Overloadings
The following overloading is supported:
operator os_instantiated_class_type&( );
Provides for non-const casts from os_class_type to os_instantiated_class_
type. If the cast is not permissible, err_mop_illegal_cast is signaled.
os_class_type::set_access_of_get_os_typespec_function()
void set_access_of_get_os_typespec_function(
os_member::os_member_access
);
Passes os_member::Private, os_member::Protected, or os_member::Public to
specify the type of access allowed to the class’s get_os_typespec( ) function.
os_class_type::set_base_classes()
void set_base_classes(os_List<os_base_class*>& class_type);
Sets the list, in declaration order, of os_base_classes of the specified class. Each os_
base_class object represents a class from which the given class is derived, together
with the nature of the derivation (virtual or nonvirtual, and public, private, or
protected).
os_class_type::set_class_kind()
void set_class_kind(os_unsigned_int32);
Sets the class kind of the specified class. The argument should be one of the following
enumerators to indicate the kind of class represented by the specified instance of os_
class_type:
• os_class_type::Struct indicates a struct.
• os_class_type::Union indicates a named union.
• os_class_type::Anonymous_union indicates an anonymous union.
• os_class_type::Class indicates a class declared with the class-key class.
os_class_type::set_declares_get_os_typespec_function()
void set_declares_get_os_typespec_function(os_boolean);
Specifies whether this declares a get_os_typespec( ) member function.
os_class_type::set_defines_virtual_functions()
void set_defines_virtual_functions(os_boolean);
Specifies whether the specified class defines any virtual functions.
Release 6.3
127
os_class_type
os_class_type::set_dispatch_table_pointer_offset()
void set_dispatch_table_pointer_offset(os_int32);
Sets the offset at which the pointer to the dispatch table is stored.
os_class_type::set_has_constructor()
void set_has_constructor(os_boolean);
Specifies whether the class defines a constructor.
os_class_type::set_has_destructor()
void set_has_destructor(os_boolean);
Specifies whether the class defines a destructor.
os_class_type::set_indirect_virtual_base_classes()
void set_indirect_virtual_base_classes(
os_List<os_base_class*> base_classes
);
Sets the indirect virtual base classes of the specified class.
os_class_type::set_introduces_virtual_functions()
void set_introduces_virtual_functions(os_boolean);
Passing a nonzero value specifies that the class defines, rather than merely inherits,
a virtual function.
os_class_type::set_is_abstract()
void set_is_abstract(os_boolean);
Specifies whether the specified class is abstract.
os_class_type::set_is_forward_definition()
void set_is_forward_definition(os_boolean);
Specifies whether the specified class is known only through a forward definition.
os_class_type::set_is_persistent()
void set_is_persistent(os_boolean);
Specifies whether the specified class is marked as persistent. To be installed into a
database schema, a class must either be marked as persistent or be reachable from a
persistent class. Making a class persistent with set_is_persistent( ) is similar to
marking it with OS_MARK_SCHEMA_TYPE( ).
os_class_type::set_members()
void set_members(os_List<os_member*>& class_type);
Sets the members, in declaration order, of the specified class.
128
C++ A P I Reference
Chapter 2: Class Library
os_class_type::set_name()
void set_name(const char* class_type);
Sets the name of the specified class. ObjectStore copies the character array pointed to
by the argument.
os_class_type::set_pragmas()
void set_pragmas(os_List<os_pragma*> class_type);
Sets the pragmas associated with the specified class.
os_class_type::set_source_position()
void set_source_position(
const char* file,
os_unsigned_int32 line
);
Sets the source position associated with the specified class.
os_class_type::Struct
This enumerator is a possible return value from os_class_type::get_class_
kind( ). It indicates a struct.
os_class_type::Union
This enumerator is a possible return value from os_class_type::get_class_
kind( ). It indicates a named union type.
Release 6.3
129
os_close_database
os_close_database
The os_close_database class enables you to close a database when a function ends,
even if an exception causes it to end. To use this class, declare an automatic variable
of the class os_close_database, giving its constructor a pointer to the os_database
object that represents the database — usually, the pointer returned by os_
database::open(). When the variable goes out of scope, its destructor calls os_
database::close(). If the open count reaches 0, the database is closed; otherwise,
it remains open for use by other parts of the application.
The os_close_database class should be used only in a function that opens a
database by calling os_database::open() or os_database::create().
For more information about how open() and close() use the open count, see the
following:
• os_database::close() on page 150
• os_database::open() on page 164
• C++ A P I User Guide
130
C++ A P I Reference
Chapter 2: Class Library
os_cluster
The cluster is the basic physical unit of allocation in an ObjectStore database. Each
cluster can be used as an atomic unit of transfer to and from persistent storage.
A segment is a group of one or more clusters. Every segment is created with an initial
cluster, which is also the initial (default) cluster. New objects allocated using the os_
segment or os_database overload of operator new are allocated to the appropriate
default cluster. More clusters can be added by the application at any time. The
application can also change the default cluster for the duration of the current session.
For information about iterating over clusters, see os_cluster_cursor on page 138.
Type definitions
The types os_int32 and os_boolean, used throughout this document, are each
defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as
an unsigned 32-bit integer type.
Required
header files
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_cluster::database_of()
os_database *database_of() const;
Returns a pointer to the database in which the specified cluster resides. The transient
database is returned if the transient cluster is specified.
os_cluster::destroy()
void destroy();
Deletes the persistent cluster for which the function is called. When a cluster is
destroyed, all data it contains is permanently destroyed and pointers into the cluster
become invalid. Any subsequent use of the destroyed cluster (such as an attempt to
allocate memory within it) is an error. Invoking destroy() on a destroyed cluster
results in the err_cluster_is_deleted exception.
os_cluster::get_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
os_allocation_strategy get_allocation_strategy(void) const;
Returns the current strategy to use when ObjectStore allocates storage for an object
in the specified cluster. For information about the return values, see
objectstore::get_allocation_strategy() on page 62. For information about
specifying the allocation strategy in a cluster, see os_cluster::set_allocation_
strategy() on page 135.
os_cluster::get_fetch_policy()
enum os_fetch_policy {
Release 6.3
131
os_cluster
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
void get_fetch_policy(
os_fetch_policy& policy,
os_int32& bytes
) const;
Retrieves the cluster’s current fetch policy. An enumerator of type os_fetch_policy
is returned in policy, and the fetch quantum is returned in bytes. For information
about the arguments, see objectstore::get_fetch_policy() on page 66. For
information about setting the fetch policy on a cluster, see os_cluster::set_
fetch_policy() on page 135.
os_cluster::get_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
objectstore_lock_option get_lock_option() const;
Returns the locking behavior currently in effect for the specified cluster. For more
information about the return value, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
• objectstore::own_page_write on page 79
For information about setting the lock option, see os_cluster::set_lock_
option() on page 135.
os_cluster::get_null_illegal_pointers()
os_boolean get_null_illegal_pointers() const;
If the specified cluster is in null_illegal_pointers mode, the function returns
nonzero (true); otherwise, it returns 0 (false). See os_cluster::set_null_illegal_
pointers() on page 136.
132
C++ A P I Reference
Chapter 2: Class Library
os_cluster::get_number()
os_unsigned_int32 get_number() const;
Returns the cluster number of the specified cluster. This number is suitable for
passing to the function os_segment::get_cluster(); see os_segment::get_
cluster() on page 353.
os_cluster::get_transient_cluster()
static os_cluster *const get_transient_cluster();
Returns a pointer to the transient cluster, which can be used as an argument to
::operator new() to request transient allocation. For information about
::operator new(), see ::operator new() on page 459.
os_cluster::is_deleted()
os_boolean is_deleted();
Returns nonzero (true) if the specified os_cluster has been deleted, and 0 (false)
otherwise.
os_cluster::is_empty()
os_boolean is_empty();
Returns nonzero (true) if the specified os_cluster contains no nondeleted objects,
and 0 (false) otherwise.
os_cluster::is_transient_cluster()
os_boolean is_transient_cluster() const;
Returns nonzero (true) if the specified cluster is transient and 0 (false) if persistent.
os_cluster::of()
static os_cluster* of(void const* obj);
Returns a pointer to the cluster in which the specified object resides. If the specified
void* is 0 or points to transient memory, a pointer to the transient cluster is
returned.
See os_cluster::get_transient_cluster() on page 133.
os_cluster::release_pointer()
void release_pointer();
Releases the pointer specified by the implicit this argument.
When an application calls a function that returns an os_cluster pointer, ObjectStore
increments a use count of the number of times it has returned a pointer to the same
object. The use count thus represents the number of pointers to the same object that
are currently in use.
Release 6.3
133
os_cluster
When the application calls release_pointer(), ObjectStore decrements the use
count for an ObjectStore object. When the last pointer is released, the count reaches
0 and the os_cluster object is deleted.
See the following for related information:
• The C++ A P I User Guide discusses how to release pointers.
• You can also release os_cluster pointers when they go out of scope; see os_
release_cluster_pointer on page 312.
• See os_cluster::retain_pointer() on page 134 for information about
retaining os_cluster pointers.
os_cluster::retain_pointer()
void retain_pointer();
Retains the pointer specified by the this argument.
When an application calls a function that returns an os_cluster pointer, ObjectStore
increments a use count of the number of times it has returned a pointer to the same
object. The use count thus represents the number of pointers to the same object that
are currently in use. The application calls os_cluster::release_pointer() when
it no longer needs the pointer, thus releasing it and decrementing the use count.
When the application calls retain_pointer(), ObjectStore increments the use count
for an os_cluster object. Calling retain_pointer() ensures that the pointer is
retained even when another part of the application releases it.
For information about using retain_pointer(), see Chapter 3 in the C++ A P I User
Guide. See also os_cluster::release_pointer() on page 133.
os_cluster::return_memory()
void return_memory(os_boolean evict_now);
Just like objectstore::return_memory() on page 81, except that it acts on a
specified cluster rather than on a specified range of addresses.
os_cluster::segment_of()
os_segment* segment_of() const;
Returns a pointer to the segment in which the specified cluster resides. The transient
segment is returned if the transient cluster is specified.
os_cluster::session_of()
os_session* session_of() const;
Returns the os_session object for the session in which the specified os_cluster*
was retrieved.
This function can be used with os_session::set_current() to enable a thread to
join the session associated with an os_cluster object. For example, if cluster_ptr
references an os_cluster object, then the statement
134
C++ A P I Reference
Chapter 2: Class Library
os_session::set_current(cluster_ptr->session_of());
enables the currently executing thread to access the object by setting the thread’s
current session to the session associated with cluster_ptr.
os_cluster::set_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
void set_allocation_strategy(os_allocation_strategy);
Sets the strategy to use when ObjectStore allocates storage for an object in the
specified cluster. This strategy can be overridden by subsequent calls to
• objectstore::set_allocation_strategy() on page 82
• os_cluster::set_allocation_strategy() on page 135
• os_database::set_allocation_strategy() on page 168
• os_segment::set_allocation_strategy() on page 359
For information about the meaning of the os_allocation_strategy enumerators
that can be used as arguments, see objectstore::get_allocation_strategy() on
page 62.
os_cluster::set_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
void set_fetch_policy(
os_fetch_policy policy,
os_int32 bytes) const;
Sets the fetch policy for the specified cluster. The default for the policy argument is
os_fetch_page. For more information about the arguments, see
objectstore::get_fetch_policy() on page 66.
The fetch policy established with set_fetch_policy() remains in effect only until
the end of the session making the function call. Moreover, set_fetch_policy()
affects only transfers made by this session. Other concurrent sessions can use a
different fetch policy for the same cluster.
For information about retrieving the fetch policy for a cluster, see os_
cluster::get_fetch_policy() on page 131.
os_cluster::set_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
Release 6.3
135
os_cluster
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
void set_lock_option(objectstore_lock_option);
Sets the locking behavior for the specified cluster. For information about the
argument, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
• objectstore::own_page_write on page 79
os_cluster::set_null_illegal_pointers()
os_boolean set_null_illegal_pointers(os_boolean);
By default, ObjectStore signals a run-time error when it detects an illegal pointer. If
you pass nonzero (true) to this function, ObjectStore changes the illegal pointer to 0
(null). You can specify the default behavior by passing 0 (false) to this function. The
results of using this function do not remain in effect after the current session ends,
and they are invisible to other sessions. See os_cluster::get_null_illegal_
pointers() on page 132.
os_cluster::set_size()
void set_size(os_unsigned_int32 n_bytes);
Specifies the size in n_bytes of the cluster represented by the this argument. This
function allows you to presize a cluster in order to minimize fragmentation; see
Managing Database Fragmentation in Chapter 1 of Managing ObjectStore.
This function can also be used to shrink a cluster to remove unused space at the end
of the cluster. n_bytes can be larger, equal to, or smaller than the current size, but it
cannot shrink a cluster other than removing free space at the end. If n_bytes would
require deleting a persistent object, calling this function will signal the err_cannot_
shrink_cluster exception.
This function must be called within a transaction and always write-locks the whole
cluster unless n_bytes is already equal to the requested size.
136
C++ A P I Reference
Chapter 2: Class Library
os_cluster::size()
os_unsigned_int32 size(os_boolean b_lock_cluster = 1);
Returns the size in bytes of the specified cluster. If b_lock_cluster is nonzero (true,
the default), the function waits until the specified cluster is read locked before
returning its size. If b_lock_cluster is 0 (false), the function returns the cluster’s
size without waiting. The reported size is transaction consistent if the cluster is
locked.
os_cluster::with()
static os_cluster_with with(const void* obj);
Returns an os_cluster_with object. The returned object is a C++ automatic object;
that is, it is allocated from the stack and does not require the user to explicitly delete
it. This value can be used as the first argument to persistent new when you allocate
storage that is as close as possible to obj.
For more information, see os_cluster_with on page 140.
Release 6.3
137
os_cluster_cursor
os_cluster_cursor
Instances of the class os_cluster_cursor can be used to iterate over clusters in a
segment.
Type definitions
The types os_int32 and os_boolean, used throughout this document, are each
defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as
an unsigned 32-bit integer type.
Required
header files
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_cluster_cursor::os_cluster_cursor()
os_cluster_cursor(
const os_segment* seg,
os_unsigned_int32 max_n_clusters_at_a_time = 100
);
Constructs an instance of os_cluster_cursor for iterating over the clusters in seg.
The max_n_clusters_at_a_time argument sets the number of clusters that can be
maintained on the client at one time without returning to the ObjectStore server for
another group. The constructor allocates a buffer large enough to hold the clusters.
After constructing os_cluster_cursor, call os_cluster_cursor::next() to
position os_cluster_cursor at the first cluster in the segment.
os_cluster_cursor::get_current()
os_cluster* get_current() const;
If os_cluster_cursor is positioned at a cluster, returns a pointer to that cluster. If
os_cluster_cursor is not positioned at a cluster, it returns NULL. To position os_
cluster_cursor at a cluster, call os_cluster_cursor::next().
os_cluster_cursor::next()
os_cluster* next();
Advances to the next cluster and returns a pointer to that cluster. If next() is called
immediately after os_cluster_cursor is created, it positions os_cluster_cursor
at the first cluster in the segment and returns a pointer to that cluster. If next()
advances beyond the last cluster in the segment, it returns NULL.
138
C++ A P I Reference
Chapter 2: Class Library
os_cluster_cursor::reset()
void reset();
Resets the os_cluster_cursor object to its initial state. You must call os_cluster_
cursor::next() to position os_cluster_cursor at the first cluster in the segment.
Overloadings
void reset(os_unsigned_int32 clstr_num);
Positions os_cluster_cursor at the cluster specified by clstr_num. If the cluster at
clstr_num does not exist, os_cluster_cursor::get_current() returns NULL. The
value returned by os_cluster::get_number() is suitable for clstr_num.
void reset(const os_segment* seg);
If seg is specified, os_cluster_cursor can be used to iterate over the clusters in seg.
You must call os_cluster_cursor::next() to position os_cluster_cursor at the
first cluster in seg.
Release 6.3
139
os_cluster_with
os_cluster_with
os_cluster_with is the return value of os_cluster::with(). This value can be
used in an overloading of persistent new to allocate storage for an object as close as
possible to another object. For example, the following statement allocates storage for
obj2 as close as possible to obj1:
a_class *obj2 = new(os_cluster::with(obj1), a_typespec)
a_class;
In contrast, the following overloading of new tries to allocate storage for obj2 in the
same cluster as obj1, assuming that obj1 is in a_cluster.
a_class *obj2 = new(a_cluster, a_typespec) a_class;
For more information, see os_cluster::with() on page 137.
Required
header files
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_cluster_with::get()
const void* get() const;
Returns a pointer to the object near which another object is to be allocated. This
pointer is the argument to os_cluster::with() on page 137.
140
C++ A P I Reference
Chapter 2: Class Library
os_compact
ObjectStore databases consist of clusters containing persistent data. As persistent
objects are allocated and deallocated in a cluster, internal fragmentation in the
cluster can increase because of the presence of holes produced by deallocation. Of
course, the ObjectStore allocation algorithms recycle deleted storage when objects
are allocated; however, there might be a need to compact persistent data by
squeezing out the deleted space. Such compaction frees persistent storage space so it
can be used by other clusters.
The os_compact API removes deleted space in specified databases by compacting all
C++ persistent data, including ObjectStore collections, indexes, and bound queries,
and correctly relocates pointers and all forms of ObjectStore references to compacted
data. After you compact a database, access is usually faster so performance
improves. Once a database is compacted it cannot be de-compacted.
For more information about using a command-line utility for compaction, see
oscompact in Chapter 4 of Managing ObjectStore.
Required
header files
Programs using the os_compact class must include <ostore/ostore.hh> followed
by <ostore/compact.hh>. On UNIX platforms you need to link with the
compaction library (liboscmp); on Windows platforms, linking with the compaction
library is done automatically.
os_compact::augment_cluster_split_avoidance()
static void augment_cluster_split_avoidance(
const char* class_name)
This function specifies that any cluster containing objects of class_name will not be
split when the cluster size exceeds set_maximum_cluster_size(). This is useful
when a cluster contains user defined data that should not be split across clusters. For
more information about maximum cluster size, see os_compact::set_maximum_
cluster_size() on page 145. To help determine when objects should not be split,
see the Clustering Techniques white paper at
http://www.progress.com/realtime/publications/index.ssp#odbms.
os_compact::augment_post_compact_transformers()
static void augment_post_compact_transformers(
const os_transformer_binding& );
This function adds the specified transformer binding to the set of transformer
bindings to be used during subsequent compaction. This applies to compaction
initiated in the current process. A transformer binding associates a class with a
function so that the function is executed on each instance of the class after all objects
are moved.
See also os_transformer_binding on page 417.
Overloadings
The following overloading is supported:
static void augment_post_compact_transformers(
Release 6.3
141
os_compact
const os_Collection<os_transformer_binding*>& );
This overloading of the function adds the elements of the specified collection to the
set of transformer bindings to be used during subsequent compaction. This applies
to compaction initiated in the current process. A transformer binding associates a
class with a function so that the function is executed on each instance of the class after
all objects are moved. See also os_transformer_binding on page 417.
os_compact::compact()
static void compact(
const char** dbs_to_compact);
dbs_to_compact is a null-terminated array of pointers to strings identifying the set
of databases to compact. If using cross-database pointers or ObjectStore references
then all affiliated databases should be compacted in the same call to os_
compact::compact().
static void os_compact::compact(
const char** dbs_to_compact,
const char* work_db);
dbs_to_compact is a null-terminated array of pointers to strings identifying the set
of databases to compact. If using cross-database pointers or ObjectStore references
then all affiliated databases should be compacted in the same call to os_
compact::compact().
work_db is used when compacting a large set of databases that require a lengthy
compaction. The argument should be a path to a database that os_compact will use
to store information so that an interruption of compaction can be resumed from the
most recent consistent state. Using this argument allows the compaction to be done
in multiple smaller transactions rather than one large transaction. This can prevent
the osserver transaction log from becoming too large and prevents address_
space_full exceptions.
When you do not specify this argument, ObjectStore performs the entire compaction
operation in one transaction. When you specify this argument, ObjectStore uses a
separate transaction for each cluster. Therefore, you can use separate threads to
concurrently work on separate clusters.
Note
The ObjectStore fast schema evolution facility is used to provide rapid compaction,
so seeing an err_schema_evolution exception coming from os_compact is normal.
You can use the os_compact API on both file databases and rawfs databases.
Compacting file
databases
142
The clusters in file databases are made up of extents, all of which are allocated in the
space provided by the host operating system for the single host file. When there are
no free extents left in the host file and growth of an ObjectStore cluster is required,
the ObjectStore server extends the host file to provide the additional space. The
compactor permits holes contained in clusters to be compacted for return to the
allocation pool for the host file. This frees that space for use by other clusters in the
same database. However, because operating systems provide no mechanism to free
disk space allocated to regions internal to the host file, any such free space remains
inaccessible to other databases stored in other host files. In other words, compacting
C++ A P I Reference
Chapter 2: Class Library
a file database does not reclaim space for use by other databases. To decrease the size
of the file database after compaction, use the oscopy utility to copy the database. The
newly copied database will not contain the free space reclaimed by the compactor.
Compacting
rawfs
databases
The ObjectStore rawfs stores all databases in a storage pool, on either one or more
host files or raw partitions. Any space in a rawfs that is freed by the compaction
operation can be reused by any cluster in any database stored in the rawfs.
Database
locking
During compaction the database is locked and only applications running MVCC
transactions can access the database. However, when running with the work_db
argument the compaction is done in multiple transactions which can result in an
MVCC application seeing an inconsistent view of data. For example, some objects
might have been moved but an ObjectStore collection containing pointers to those
objects has not transformed, resulting in an inconsistent view.
Backing up
compacted
databases
Before compacting a database the database should be backed up to safeguard against
unexpected results. After compacting a database, the next backup for that database
should be a full backup. The reason for this is that most clusters will be modified
during compaction and running an incremental backup after that will not be
practical.
Transformers
Some data structures become invalid as a result of compaction. The classic example
of a data structure that might require user transformation is a hash table that hashes
on the offset of an object within a cluster. Because compaction modifies these offsets,
there is no way that such an implicit dependence on the cluster offset can be
accounted for by compaction. Therefore, the compacted hash table becomes invalid.
ObjectStore collections and indexes are transformed by compaction. Invocation of a
user data transformer can be registered by using os_compact::augment_post_
compact_transformers() which associates a class with a function so that the
function is executed on each instance of the class during the transformation phase of
compaction.
Schema key
protection
If you are developing an application and will be running os_compact on a database
protected with a schema key, ensure that the correct key is specified for the
environment variables OS_SCHEMA_KEY_LOW and OS_SCHEMA_KEY_HIGH. If the
correct key is not specified for these variables, os_compact fails and ObjectStore
signals:
err_schema_key _CT_invalid_schema_key,
"<err-0025-0151> The schema is protected and the key provided
did not match the one in the schema."
Very large
databases
See Advanced C++ A P I User Guide, Evolving or Compacting Very Large Databases.
os_compact::initialize()
static void initialize(
os_unsigned_int32 n_threads,
os_unsigned_int32 prefetch_KB,
os_ptr_val secondary_psr_size);
Release 6.3
143
os_compact
This method initializes ObjectStore and must be called prior to using any ObjectStore
features. Specifying zero for the calling arguments to will set them to the default
values.
n_threads specifies number of threads to use for schema evolution. The default
value is 1.5 times the number of CPUs in the system (rounded up). The default
should provide good performance on most hardware if there is no other significant
load on the system.
prefetch_KB specifies the size in KB of persistent pages to prefetch at one time. The
default is 80 KB which should provide good performance on most hardware.
secondary_psr_size specifies the size in MB of virtual address space for secondary
sessions. The default is 16 MB. Increase this value in the unlikely event that your
application runs out of address space, for example, because of an extremely large
schema.
os_compact::set_address_space_release_interval()
static void set_address_space_release_interval(
os_unsigned_int32 interval);
Specifies the frequency of address space releases, where interval is in units of bytes
and controls the frequency. Specify a smaller value for more frequent releases, a
larger value for less frequent. The default value is 1 MB.
os_compact::set_avoid_page_boundary()
static void set_avoid_page_boundary(
os_unsigned_int32 max_bytes_wasted);
Specifies that you want compaction to avoid placing objects across page boundaries
in the compacted database. This applies to objects that are being moved to compact
the space used by the database. The default is that compaction does not avoid page
boundaries when moving objects. When compaction avoids a page boundary, it
inserts a free region and leaves some bytes on the page unused.
The max_bytes_wasted argument specifies the maximum bytes that can be wasted
when page boundaries are avoided. If trying to avoid a page boundary would cause
more than max_bytes_wasted bytes to be wasted, compaction does not avoid
placing that object across the page boundary.
The value of max_bytes_wasted can be any value from 0 through 4095. A value of
0 disables the feature.
Note: In the context of this function, all pages are server pages, which are always 4K
in size. It does not matter what platform the server is running on.
os_compact::set_explanation_level()
static void set_explanation_level(os_unsigned_int32 level);
144
C++ A P I Reference
Chapter 2: Class Library
Specifies the level of debugging information that is output during compaction. The
level argument can be one of the following enumerators:
Enumerator
Meaning
silent
Do not output any debugging information. This is the default.
phase_level
Output information about the phases of compaction for each
cluster, segment, and database.
type_level
Output information about all types in the database.
object_level
Output information about all objects in the database.
verbose
Output information about all pointers in the database.
Note that the levels are cumulative; that is, each level includes information that is
output at the previous levels.
os_compact::set_malloc_size()
static void set_malloc_size(os_unsigned_int32);
Sets the relocation map malloc size in bytes. The default is 0x100000 bytes (1024 KB).
os_compact::set_maplet_size()
static void set_maplet_size(os_unsigned_int32);
Sets the relocation map maplet size in bytes.; the value must be a power of 2. The
default is 64 bytes. You should change this value only if you fully understand the
performance characteristics of your CPU and all its levels of cache.
os_compact::set_maximum_cluster_size()
static void set_maximum_cluster_size(
os_unsigned_int32 max_cluster_size_in_bytes)
During compaction clusters larger than max_cluster_size_in_bytes are split into
multiple clusters. This function specifies the size of max_cluster_size_in_bytes.
The value of max_cluster_size_in_bytes is rounded up to the next multiple of 64
KB. The default is to split any cluster that exceeds 1600 MB. See os_
compact::augment_cluster_split_avoidance() on page 141 for how to prevent
compaction from splitting clusters that exceed max_cluster_size_in_bytes.
Note that some ObjectStore collections manage an internal cluster which will not be
split because the internal clusters maintain data structures that cannot be split across
multiple clusters. Examples of collections that maintain internal clusters are os_set,
os_Set, os_bag, os_Bag, os_Dictionary, and indexes.
os_compact::set_maximum_memory_size()
static void set_maximum_memory_size(os_ptr_val);
Sets the maximum memory to use for pointer relocation maps in bytes. The default
is one-half the main memory size or one-half the size of virtual memory, whichever
is less.
Release 6.3
145
os_compact
os_compact::shutdown()
static void shutdown();
After completion shutdown() must be called to clean up ObjectStore resources.
146
C++ A P I Reference
Chapter 2: Class Library
os_comp_schema
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a compilation
schema, stored in a compilation schema database. os_comp_schema is derived from
os_schema.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_comp_schema::get()
static const os_comp_schema& get(const os_database& db);
Returns the schema of the specified database.
Release 6.3
147
os_database
os_database
Instances of the class os_database represent ObjectStore databases. Pointers to such
instances can be used as arguments to persistent new.
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.
When a session terminates, any databases left open are closed automatically.
Instances of the class os_database are sometimes used to hold session local or persession state, representing a property of the database for the current session. For
example, a database opened for read-only access in one session could be opened for
update in another session. For this reason, it is sometimes preferable to think of an
instance of the class os_database as representing an association between a database
and the session that retrieves the pointer to it. In fact, instances of os_database are
actually transient objects.
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 os_dbutil on page 178.
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_database::affiliate()
void affiliate(
os_database* target_db,
os_boolean deep = 0,
os_boolean relative = 1,
const char* common_parent = NULL
);
Invoking this function on the specified database causes target_db to become
affiliated with the specified database and writes an entry in its path name pool to the
target database. You must call affiliate() once for each target database that will
contain objects pointed to by objects in the specified database.
target_db points to the target database.
When deep is nonzero (true), affiliate() copies all affiliation entries from the path
name pool of target_db. This argument is useful when the target database contains
objects that include cross-database pointers.
148
C++ A P I Reference
Chapter 2: Class Library
When relative is nonzero (true), affiliate() writes the relative path name to
target_db; if it is 0 (false), affiliate() writes the absolute path name, including
the ObjectStore server name.
common_parent specifies the path that is common to both the this database and the
target database. By default, the common parent is the last directory in the path
hierarchy that is common to the paths of both the this database and the target
database. For example, the common parent of /a/b/c/this_db and /a/b/d/tgt_db
is /a/b, so the relative path from this_db to tgt_db is .. /d/tgt_db.
Note that os_database::affiliate() is directional. That is, after calling db1>affiliate(db2), db1 can have pointers to objects in db2, but not the reverse. You
must call db2->affiliate(db1) if you want db2 to have pointers to objects in db1.
os_database::change_affiliation()
void change_affiliation(os_unsigned_int16 index,
const os_database* target_db,
os_boolean relative = 1,
const char* common_parent = NULL
);
Replaces the path to an affiliated database with the path to target_db. This function
is especially useful when you are making a copy of a database that is affiliated with
another database, and you want to change the affiliation from the original database
to its copy. Calling this function does not modify or validate the user’s persistent
pointers.
index references an entry in the path name pool of the this database. After change_
affiliation() has been called, the entry is overwritten with the path to target_db.
For information about retrieving an index value, see os_database::get_
affiliation_index_of() on page 154.
target_db points to the target database.
When relative is nonzero (true), change_affiliation() writes the relative path
name to target_db; if it is 0 (false), change_affiliation() writes the absolute path
name, including the server name prefix.
common_parent specifies the path that is common both to the this database and to
the target database. The common_parent argument controls the form of the relative
path when the relative argument is nonzero (true). For more information, see os_
database::affiliate() on page 148.
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
);
Sets the schema key of the specified database. Call this function from within an
update transaction. The specified database must be opened for update; otherwise,
Release 6.3
149
os_database
ObjectStore signals err_opened_read_only and issues an error message such as the
following:
<err-0025-0155> Attempt to change the schema key of database db1, but
it is opened for read only.
If the database has had its key frozen, err_schema_key is signaled and ObjectStore
issues an error message such as the following:
err_schema_key
<err-0025-0152> The schema key of database db1 is frozen and may not
be changed.
If the database already has a schema key at the time of the call, old_key_low must
match the first component of the key and old_key_high must match the second
component, or err_schema_key is signaled and ObjectStore issues an error message
such as the following:
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)
If the database has no schema key, old_key_low and old_key_high are ignored.
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_boolean force = 0);
Decrements the open count, which is the number of times that the database has been
opened without successive closes.
ObjectStore maintains an open count for each opened database. Calling os_
database::open() increments the count, and calling os_database::close()
decrements it. When the count reaches 0, the database is closed. To close a database
regardless of its open count, specify nonzero (true) for the optional force argument,
which also resets the open count to 0. By default, an open database is not closed until
its open count is 0.
For information about opening the database and the open count, see os_
database::open() on page 164. For information about using an automatic variable
of the class os_close_database to close a database, see os_close_database on
page 130.
os_database::create()
static os_database* create(
const char* db_path,
os_int32 mode = 0664,
os_boolean if_exists_overwrite = 0,
os_database* schema_database = 0,
objectstore::segment_reference_policy
150
C++ A P I Reference
Chapter 2: Class Library
default_segment_reference_policy =
objectstore::dsco_access_allowed
);
Returns a pointer to a newly created database (an instance of the class os_database)
with the specified db_path and mode. (The octal values for mode are the same as those
used by the oschmod utility, which is described in Managing ObjectStore.) The new
database is opened for reading and writing.
If a database with the specified path name 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 path name is deleted, a
new database is created with the specified mode, and the new database is opened for
read and 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);
If schema_database is nonzero, the database it specifies is used as the schema database
for the newly created database. This means that ObjectStore installs in the schema
database all schema information for the data stored in the new database; the new
database itself will have no schema information in it.
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 and 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.
default_segment_reference_policy specifies the default reference policy for new
segments in a database; see os_database::create_segment() on page 152.
For file databases, pathname is an operating system path name. ObjectStore takes
into account local NFS mount points when it is interpreting the path name, so path
names 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 path name
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.
Release 6.3
151
os_database
ObjectStore supports multibyte encoded path names. In environments where
ObjectStore applications and servers are located on different machines, the client and
server machines can use different multibyte encodings.
os_database::create_root()
os_database_root* create_root(char* name);
Creates a root in the specified database to associate a copy of the specified name with
an as-yet-unspecified entry-point object. (Because the name is copied to persistent
memory by this function, the supplied char* can point to transient memory.) If the
specified name is already associated with an entry-point object in the same database,
an err_root_exists exception is signaled. If the specified database is the transient
database, an err_database_not_open exception is signaled.
os_database::create_segment()
os_segment* create_segment( );
Creates a segment in the specified database and returns a pointer to an instance of
the class os_segment. Call this function within a transaction. The return value points
to a transient object representing the new segment. Note that because it points to
transient memory, the return value of this function cannot be stored persistently.
If create_segment() is invoked on a transient database, it signals the error err_
database_segment.
Overloading
The following overloading is supported:
enum objectstore::segment_reference_policy {
export_id_access_required,
dsco_access_allowed
};
os_segment* os_database::create_segment(
objectstore::segment_reference_policy ref_policy
);
Creates a segment in the specified database.
The ref_policy argument specifies the reference policy for the this segment.
If ref_policy is objectstore::export_id_access_required, certain
reorganization facilities, such as compaction, can operate more efficiently on the
segment. The cost of this policy is the overhead of having to export objects in the
segment that might be referred to from other segments, as well as the additional
overhead of traversing cross-segment pointers to the segment.
When export_id_access_required is in effect, you must export every object in the
segment that might be referred to by an object in a different segment. (See
objectstore::export_object() on page 60.) If you fail to export an object in an
export_id_access_required segment, cross-segment pointers to the object are
treated as illegal pointers (see objectstore::set_null_illegal_pointers() on
page 90).
152
C++ A P I Reference
Chapter 2: Class Library
If ref_policy is objectstore::dsco_access_allowed (the default), reorganizing
the segment can require scanning an entire database or group of databases, rather
than scanning just that segment. This policy does not carry the costs described for
export_id_access_required, described previously.
In addition to affecting reorganization, a segment’s reference policy also affects
garbage collection. The ObjectStore garbage collector automatically treats exported
objects in export_id_access_required segments as garbage-collection roots. For
garbage collection of dsco_access_allowed segments, you must explicitly identify
the roots (the objects referred to by other segments).
os_database::destroy()
void destroy( );
Deletes the database for which the function is called. The specified database must be
persistent. If the database is open at the time of the call, destroy( ) closes the
database before deleting it.
When a session destroys a database, this can affect other sessions that have the
database opened. Such a session might subsequently be unable to access some of the
database’s data, even if earlier in the same transaction it accessed the database
successfully.
Data already cached in the session’s client cache continues to be accessible, but
attempts to access other data cause ObjectStore to signal err_database_not_found.
Attempts to open the database also signal err_database_not_found. Note that
performing os_database::lookup( ) on the destroyed database’s path name might
succeed because the instance of os_database representing the destroyed database
might be in the session’s client cache.
If you attempt to operate on a destroyed persistent database, err_database_is_
deleted is signaled.
This function can be used only on a persistent database. Invoking destroy() on a
transient database causes the err_database_transient exception. Use ::operator
delete to delete a transient database.
os_database::find_root()
os_database_root* find_root(char* name);
Returns a pointer to the root in the specified database with the specified name.
Returns 0 if such a root is not found.
os_database::freeze_schema_key()
void freeze_schema_key(
os_unsigned_int32 key_low,
os_unsigned_int32 key_high
);
Freezes the specified database’s schema key, preventing any change to the key, even
by applications with a matching key.
Release 6.3
153
os_database
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 such as the following:
<err-0025-0156> Attempt to freeze the schema key of database db1, but
it is opened for read only.
If the database is schema protected and has not been accessed since the last time its
open count was incremented from 0 to 1, the application’s schema key must match
the database’s schema key. If it does not, err_schema_key is signaled and
ObjectStore issues an error message such as the following:
<err-0025-0151>The schema is protected and the key, if provided, did
not match the one in the schema of database dba.
key_low and key_high must match the database’s schema key, or else err_schema_
key is signaled and ObjectStore issues an error message such as the following:
<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.
If the database’s schema key is already frozen, and you specify the correct key, the
call has no effect.
os_database::get_affiliated_databases()
void get_affiliated_databases(
os_int32& n_databases,
os_database**& dbs
) const;
Returns an array of pointers to the affiliated databases — that is, to all databases with
entries in the path name pool of the specified database. The call must occur inside a
transaction. When the function returns, n_databases refers to the number of
elements in the array. It is the user’s responsibility to deallocate the array when it is
no longer needed.
For information about affiliating one database with another, see os_
database::affiliate() on page 148.
os_database::get_affiliation_index_of()
os_unsigned_int16 get_affiliation_index_of(
const os_database* target_db)
const;
Returns the index of the path to target_db in the path name pool of the this
database. target_db must have been previously affiliated with the this database. If
it is not affiliated, get_affiliation_index_of() returns 0.
The return value is useful when you want to change the affiliation of a database; see
os_database::change_affiliation() on page 149.
os_database::get_all_databases()
static void get_all_databases(
154
C++ A P I Reference
Chapter 2: Class Library
os_int32 max_to_return,
os_database_p* dbs,
os_int32& n_returned
);
Provides access to all the databases retrieved by the current session. os_database_
p* is an array of pointers to databases. This array must be allocated by the user. The
function os_database::get_n_databases( ) can be used to determine the size of
an array to allocate. The max_to_return argument is specified by the user and is the
maximum number of elements the array is to have. The n_returned argument refers
to the actual number of elements in the array.
os_database::get_all_roots()
void get_all_roots(
os_int32 max_to_return,
os_database_root_p* roots,
os_int32& n_returned
);
Provides access to all the roots in the specified database (see os_database_root on
page 172). os_database_root_p* is an array of pointers to roots. This array must be
allocated by the user. The os_database::get_n_roots( ) function can be used to
determine the size of an array to allocate. The max_to_return argument is specified
by the user and is the maximum number of elements the array is to have. The n_
returned argument refers to the actual number of elements in the array.
os_database::get_all_segments()
void get_all_segments(
os_int32 max_to_return,
os_segment_p* segs,
os_int32& n_returned
) const;
Provides access to all the segments in the specified database. os_segment_p* is an
array of pointers to segments. This array must be allocated by the user. The os_
database::get_n_segments( ) function can be used to determine the size of an
array to allocate. The max_to_return argument is specified by the user and is the
maximum number of elements the array is to have. The n_returned argument refers
to the actual number of segment pointers returned.
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
) const;
Provides access to all the segments in the specified database, together with each
segment’s associated os_segment_access. The nth element of controls points to the
os_segment_access associated with the segment pointed to by the nth element of
segs. The arrays controls and segs must be allocated by the user. The max_to_
return argument is specified by the user.
Release 6.3
155
os_database
os_database::get_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
os_allocation_strategy get_allocation_strategy(void) const;
Returns the current strategy to use when allocating storage for an object in the
specified database. For information about the return values, see objectstore::get_
allocation_strategy() on page 62. For information about setting the allocation
strategy in a specific database, see os_database::set_allocation_strategy() on
page 168.
os_database::get_application_info()
void* get_application_info( ) const;
Returns a pointer to the object pointed to by the pointer last passed, during the
current session, to os_database::set_application_info( ) for the specified
database. If set_application_info( ) has not been called for the specified database
during the current session, 0 is returned.
os_database::get_default_segment()
os_segment* get_default_segment( ) const;
Returns a pointer to the default segment of the specified database. The default
segment is the segment in which persistent memory is allocated by default when the
function new is called with only an os_database* argument. Initially the default
segment is the initial segment, the one segment (besides the schema segment) with
which the database was created. A session can change this at any time (see os_
database::set_default_segment() on page 168), but the change remains in effect
only for the duration of the session and is invisible to other sessions. Simple
ObjectStore applications need not create any segments; all the database’s persistent
data can be stored in the initial segment, if desired. If more sophisticated clustering
is required, the application can create new segments in the database, and it might be
convenient to make one of these the default.
os_database::get_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
void get_fetch_policy(
os_fetch_policy& policy,
os_int32& bytes
) const;
Retrieves the current fetch policy for the specified database. An enumerator of type
os_fetch_policy is returned in policy, and the fetch quantum is returned in
bytes. For information about the arguments, see objectstore::get_fetch_
156
C++ A P I Reference
Chapter 2: Class Library
policy() on page 66. For information about setting the fetch policy for a database,
see os_database::set_fetch_policy() on page 169.
os_database::get_file_host_name()
char* get_file_host_name( ) const;
If the specified database is a file database, the function allocates on the heap and
returns the name of the host machine for the database. If the database is a rawfs
database or the transient database, 0 is returned. Note that it is the user’s
responsibility to deallocate the character array when it is no longer needed.
os_database::get_fragmentation()
void get_fragmentation(
os_fragmentation_statistics& stat);
Returns statistics on the fragmentation of the physical structure of the database
specified by the this argument. The statistics are returned in the stat argument.
This function can be called outside a transaction.
The stat argument is an os_fragmentation_statistics object that the get_
fragmentation() function fills with statistics about the fragmentation of this
database. The os_fragmentation_statistics class has the following public data
members:
os_element_fragmentation_statistics cluster_data;
os_element_fragmentation_statistics metadata_table_dirs;
os_element_fragmentation_statistics metadata_table_leaves;
Each member provides statistics for one of three types of physical data structure
within a database:
• Clusters, which refer to the disk space that holds the data (as opposed to
metadata) for a cluster.
• Metadata table directories, which point to metadata table leaves in clusters that
are large enough to need more than one leaf per table.
• Metadata table leaves, which contain per-page metadata such as free space, tags
(object type information), and PRMs (pointer reference maps).
The os_element_fragmentation_statistics class has the following public data
members:
os_item_fragmentation_statistics size;
os_item_fragmentation_statistics n_fragments;
os_item_fragmentation_statistics fragment_size;
where size specifies the number of clusters/directories/leaves in the database, n_
fragments specifies how many of each type are fragmented, and fragment_size
specifies the size of each fragment.
The os_item_fragmentation_statistics class has the following public data
members:
os_unsigned_int32 count;
os_unsigned_int32 minimum;
Release 6.3
157
os_database
os_unsigned_int32 maximum;
os_unsigned_int32 average;
os_unsigned_int32 median;
As indicated by their names, these members specify the number of values, the
minimum and maximum values encountered, the average value, and an estimate of
the median value. The median value is a number such that half of the values are
lower and the other half are higher. The median value is not computed exactly but is
usually within 20% of the true median. Because these distributions tend to be very
skewed, with more small values than large values, the median is often much smaller
than the average.
The size values are in units of 512-byte sectors.
You can get the same statistical information in a report format either by invoking the
ossize utility (with the -f option) on the command line or by calling os_
dbutil::ossize(). For more information, see
• ossize in Chapter 4 of Managing ObjectStore
• os_dbutil::ossize() on page 186
• Managing Database Fragmentation in Chapter 1 of Managing ObjectStore
os_database::get_host_name()
char* get_host_name( ) const;
Returns the name of the host machine on which the specified database resides. The
returned char* points to an array allocated on the heap by this function. Note that it
is the user’s responsibility to deallocate the character array when it is no longer
needed.
os_database::get_incremental_schema_installation()
os_boolean get_incremental_schema_installation( ) const;
Returns nonzero (true) if the schema installation mode of the specified database is
set to incremental mode. Returns 0 (false) if the mode is set to batch mode (the
default). See os_database::set_incremental_schema_installation() on
page 169.
os_database::get_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
objectstore_lock_option get_lock_option() const;
158
C++ A P I Reference
Chapter 2: Class Library
Returns the locking behavior currently in effect for the specified database, including
all its segments and clusters. For more information about the return value, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
• objectstore::own_page_write on page 79
For information about setting the lock option, see os_database::set_lock_
option() on page 169.
os_database::get_n_databases()
static os_int32 get_n_databases( );
Returns the number of databases retrieved by the current session.
os_database::get_n_roots()
os_int32 get_n_roots( ) const;
Returns the number of roots in the specified database (see os_database_root on
page 172).
os_database::get_n_segments()
os_int32 get_n_segments( ) const;
Returns the number of segments in the specified database, including the schema
segment.
os_database::get_new_segment_reference_policy()
objectstore::segment_reference_policy
os_database::get_new_segment_reference_policy() const;
Gets the default reference policy for new segments in the this database. See os_
database::create_segment() on page 152.
os_database::get_null_illegal_pointers()
os_boolean get_null_illegal_pointers() const;
If the specified database is in null_illegal_pointers mode, the function returns
nonzero (true); otherwise, it returns 0 (false). See os_database::set_null_
illegal_pointers() on page 170.
Release 6.3
159
os_database
os_database::get_open_mode()
enum open_modes {
not_open,
open_for_update,
open_for_read_only,
open_for_multi_db_mvv,
open_for_mvcc};
open_modes get_open_mode() const;
Returns the open mode of the database specified as the this argument.
The return value can be one of the following:
Return Value
Meaning
not_open
Database is not open.
open_for_update
Database is open for updates.
open_for_read_only
Database is open for read-only.
open_for_multi_db_mvcc
Database is open for multidatabase multiversion
concurrency control; see os_database::open_
multi_db_mvcc() on page 165.
open_for_mvcc
Database is open for multiversion concurrency
control; see os_database::open_mvcc() on
page 165.
os_database::get_path_to()
char* get_path_to(os_database* target_db) const;
Returns a newly allocated string that contains the path from the this database to
target_db. Depending on how the affiliation was established, the path can be
absolute or relative; see os_database::affiliate() on page 148. The user must
delete the string.
os_database::get_pathname()
char* get_pathname( ) const;
Returns the path name of the specified database. For databases in ObjectStore
directories, the path name consists of a rawfs host prefix (rawfs-host-name::)
followed by a rooted path name (for example, oak::/parts/db1). For file databases,
the path name is identical to the one passed to os_database::open( ), os_
database::create( ), or os_database::lookup( ) when this was first retrieved
by the current session. The returned char* points to an array allocated on the heap
by this function. Note that it is the user’s responsibility to deallocate the array when
it is no longer needed.
os_database::get_required_DLL_identifiers()
const char* const* get_required_DLL_identifiers(
os_unsigned_int32& count
);
160
C++ A P I Reference
Chapter 2: Class Library
Returns an array of pointers to DLL identifiers and the number of elements in the
array. The order of elements in the array is not significant. The array and the
elements must not be modified or deallocated.
This function can be called only within a transaction with the database open. The
returned array and strings might reside in the database, so they are valid only for one
transaction.
os_database::get_schema_database()
os_database* get_schema_database( ) const;
Returns a pointer to the schema database for this. If this is not a database whose
schema is stored remotely, 0 is returned. This function must be invoked within a
transaction.
os_database::get_sector_size()
os_unsigned_int32 get_sector_size( );
Returns the size of a sector, in bytes.
os_database::get_segment()
os_segment* get_segment(os_unsigned_int32 seg_num);
Returns a pointer to the segment in the specified database with the specified segment
number. See os_segment::get_number() on page 357.
os_database::get_segments()
void get_segments(
os_unsigned_int32 first_seg_num,
os_unsigned_int32 max_segments,
os_segment_p* segs,
os_unsigned_int32& n_segments,
os_boolean& b_more
) const;
Returns a maximum number of segments, as specified in max_segments. The first_
seg_num argument specifies the number of the first segment in the range. The
segments are returned in segs, which must be allocated by the user. The n_segments
argument contains the number of segments actually returned, and b_more is nonzero
(true) if there are more segments to retrieve.
You can use get_segments() to write your own segment iterator, or you can use the
iterator class os_segment_cursor; see os_segment_cursor on page 365.
os_database::get_transient_database()
static os_database* const get_transient_database( );
Returns a pointer to the transient database, which can be used as an argument to
::operator new() to request transient allocation. For information about
::operator new(), see ::operator new() on page 459.
Release 6.3
161
os_database
os_database::has_affiliation_to()
os_boolean has_affiliation_to(
const os_database* target_db
) const;
Returns nonzero (true) if target_db is affiliated with the this database; otherwise,
returns 0 (false). For information about retrieving a list of all the databases affiliated
with a specific database, see os_database::get_affiliated_databases() on
page 154.
os_database::insert_required_DLL_identifier()
void insert_required_DLL_identifier(
const char* DLL_identifier
);
Copies the DLL_identifier string and adds it to the database’s set of required DLLs.
If DLL_identifier is already in the database’s set of required DLLs, this function
does nothing. Call this function only in an update transaction with the database open
for write.
See also os_database::insert_required_DLL_identifiers() on page 162.
os_database::insert_required_DLL_identifiers()
void insert_required_DLL_identifiers
(const char* const* DLL_identifiers,
os_unsigned_int32 count
);
Copies DLL_identifiers to a database’s set of required DLLs.
For each identifier, checks that the identifier is not already in the set. If it is already
present, the identifier is not copied. If the identifier is not 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 it is more
efficient.
os_database::is_open()
os_boolean is_open( ) const;
Returns nonzero (true) if the this database is open, and 0 (false) otherwise.
os_database::is_open_multi_db_mvcc()
os_boolean os_database::is_open_multi_db_mvcc() const;
Returns nonzero (true) if the specified database is open for multidatabase MVCC
and 0 (false) otherwise.
162
C++ A P I Reference
Chapter 2: Class Library
os_database::is_open_mvcc()
os_boolean is_open_mvcc( ) const;
Returns nonzero (true) if the this database is opened for either single-database or
multidatabase multiversion concurrency control (MVCC) and 0 otherwise. See os_
database::open_multi_db_mvcc() on page 165 and os_database::open_mvcc()
on page 165.
os_database::is_open_read_only()
os_boolean is_open_read_only( ) const;
Returns nonzero (true) if the this database is open for read only, and 0 (false)
otherwise.
os_database::is_open_single_db_mvcc()
os_boolean os_database::is_open_single_db_mvcc() const;
Returns nonzero (true) if the specified database is open for single-database MVCC
and 0 (false) otherwise.
os_database::is_open_update()
os_boolean is_open_update() const;
Returns nonzero (true) if the this database is open for update, and 0 (false)
otherwise.
os_database::is_transient_database()
os_boolean is_transient_database() const;
Returns nonzero (true) if the this database is transient, and 0 (false) if it is persistent.
os_database::lookup()
static os_database* lookup(
const char* db_path,
os_int32 create_mode = 0
);
Returns a pointer to the database with the specified db_path but does not open it. If
it is not found, an err_database_not_found exception is signaled. The create_
mode argument is a Boolean value; if its value is nonzero and no database named db_
path exists, it creates the database.
For information on database path names, see os_database::create() on page 150.
os_database::of()
static os_database* of(void* location);
Returns a pointer to the database in which the specified object resides. If the object is
transiently allocated, a pointer to the transient database is returned.
Release 6.3
163
os_database
Note that using os_database::of( ) to allocate a new persistent object defeats
clustering. Use os_cluster::with( ) instead; see os_cluster::with() on
page 137.
os_database::open()
void open(os_boolean read_only = 0);
Opens the this database, and establishes the access mode specified by the read_
only argument — nonzero for read only, and 0 for read and write. Note that you can
use this overloading of os_database::open() only if you already have a pointer to
the database you want to open.
The first time a database is opened, ObjectStore establishes an open count for the
database. Calling open() on a database that is already open increments the count if
the second call requests the same mode as used in the initial call. If the second call
requests a different mode, err_db_cannot_change_open is signaled. Calling os_
database::close() decrements the open count. An opened database is closed
when its open count reaches 0. (However, see os_database::close() on page 150.)
ObjectStore maintains open counts for all databases opened with this and the
following overloadings of os_database::open().
Overloadings
static os_database* open(
const char* db_path,
os_boolean read_only = 0,
os_int32 create_mode = 0,
objectstore::segment_reference_policy
default_segment_reference_policy =
objectstore::dsco_access_allowed
);
Opens the database with the specified db_path, establishes the access type specified
by the read_only argument — nonzero for read only, and 0 for read and write —
and returns a pointer to that database. If the database is not found, an err_
database_not_found exception is signaled unless create_mode is nonzero.
If create_mode is nonzero and no database named db_path exists, the effect is the
same as calling os_database::create( ) with the same db_path, create_mode,
schema_database, and default_segment_reference_policy arguments. The
octal values for mode are the same as those used by the oschmod utility; see oschmod
in Managing ObjectStore.
For information on database path names, see os_database::create() on page 150.
static os_database* open(
const char* db_path,
os_boolean read_only,
os_int32 create_mode,
os_database* schema_database,
objectstore::segment_reference_policy
default_segment_reference_policy =
objectstore::dsco_access_allowed
);
164
C++ A P I Reference
Chapter 2: Class Library
All arguments other than schema_database are as described for the previous
overloading of open( ). If no database named db_path is found and both create_
mode and schema_database are nonzero, schema_database is used as the schema
database for the newly created database. This means that ObjectStore installs in the
schema database all schema information for the data stored in the new database; the
new database itself will have no schema information in it.
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 for read
only, ObjectStore attempts to reopen it for read or 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 information about closing a database and the effect of calling close() on the
open count, see os_database::close() on page 150.
os_database::open_multi_db_mvcc()
void os_database::open_multi_db_mvcc();
Opens the database specified by the this argument for multidatabase multiversion
concurrency control (MVCC). The err_db_already_open_single_db_mvcc
exception is thrown if the specified database is already open for single-database
MVCC.
Opening databases with this function provides multiversion concurrency control
across multiple databases. Like single-database MVCC, multidatabase MVCC
allows nonblocking read — that is, an ObjectStore client or session can read data
while another client or session is making concurrent updates to the same data, with
no waiting for locks by either the reader or the writer. Unlike single-database
MVCC, multidatabase MVCC provides a consistent, aggregate snapshot of multiple
databases.
Overloadings
The following overloading is supported:
static os_database* os_database::open_multi_db_mvcc(
const char* pathname
);
This overloading opens the database specified by pathname for multidatabase
MVCC and returns a pointer to the opened database. The err_db_already_open_
single_db_mvcc exception is thrown if the specified database is already open for
single-database MVCC.
os_database::open_mvcc()
void open_mvcc( );
Release 6.3
165
os_database
Opens a single database for multiversion concurrency control (MVCC). After you
open a database for MVCC, multiversion concurrency control is used for access to it
until you close it. If the database is already opened, but not for MVCC, err_mvcc_
nested is signaled. If you try to perform write access on a database opened for
MVCC, err_opened_read_only is signaled.
If a database is open for multidatabase MVCC, err_db_already_open_multi_db_
mvcc is thrown if you try to open it for single-database 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 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 sessions.
• It does contain all changes committed before the transaction started.
Because of the second characteristic, the snapshot might not be consistent with other
databases accessed in the same transaction, although it always will be internally
consistent. Even two databases, both of which are opened for MVCC, might not be
consistent with each other because updates might be performed on one of the
databases between the times of their snapshots.
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.
Overloadings
The following overloading is supported:
static os_database* open_mvcc(const char* db_path);
Opens the database with the specified path name for multiversion concurrency
control.
os_database::release_pointer()
void release_pointer();
Releases the pointer specified by the implicit this argument.
When an application calls a function that returns an os_database pointer,
ObjectStore increments a use count of the number of times it has returned a pointer
to the same object. The use count thus represents the number of pointers to the same
object that are currently in use.
166
C++ A P I Reference
Chapter 2: Class Library
When the application calls release_pointer(), ObjectStore decrements the use
count for an ObjectStore object. When the last pointer is released, the count reaches
0 and the os_database object is deleted.
See the following for related information:
• The C++ A P I User Guide discusses how to release pointers.
• You can also release os_database pointers when they go out of scope; see os_
release_database_pointer on page 313.
• See os_database::retain_pointer() on page 167 for information about
retaining os_database pointers.
os_database::retain_pointer()
void retain_pointer();
Retains the pointer specified by the this argument.
When an application calls a function that returns an os_database pointer,
ObjectStore increments a use count of the number of times it has returned a pointer
to the same object. The use count thus represents the number of pointers to the same
object that are currently in use. The application calls os_database::release_
pointer() when it no longer needs the pointer, thus releasing it and decrementing
the use count.
When the application calls retain_pointer(), ObjectStore increments the use count
for an os_database object. Calling retain_pointer() ensures that the pointer is
retained, even when another part of the application releases it.
For information about using retain_pointer(), see the C++ A P I User Guide. See
also os_database::release_pointer() on page 166.
os_database::remove_required_DLL_identifier()
void remove_required_DLL_identifier(
const char* DLL_identifier
);
Removes the DLL_identifier from the database’s set of required DLLs. If DLL_
identifier is not in the set, this function does nothing. This function can only be
called in an update transaction with the database open for write.
os_database::return_memory()
void return_memory(os_boolean evict_now);
Like objectstore::return_memory() on page 81 except that it acts on a specified
database rather than on a range of addresses.
os_database::session_of()
os_session* session_of() const;
Returns the os_session object for the session in the database specified by the this
argument.
Release 6.3
167
os_database
This function can be used with os_session::set_current() to enable a thread to
join the session associated with an os_database object. Consider the following
example, where db_ptr references an os_database object:
os_session::set_current(db_ptr->session_of());
This statement enables the currently executing thread to access the object by setting
the thread’s current session to the session associated with db_ptr.
os_database::set_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
void set_allocation_strategy(os_allocation_strategy);
Sets the strategy to use when ObjectStore allocates storage for an object in the
specified database. This strategy applies to all segments and clusters in the database
unless specifically overridden by subsequent calls to
• objectstore::set_allocation_strategy() on page 82
• os_cluster::set_allocation_strategy() on page 135
• os_database::set_allocation_strategy() on page 168
• os_segment::set_allocation_strategy() on page 359
For information about the meaning of the os_allocation_strategy enumerators
that can be used as arguments, see objectstore::get_allocation_strategy() on
page 62.
os_database::set_application_info()
void set_application_info(void* info);
Associates the specified object with the specified database for the current session.
The argument info must point to a transient object. See os_database::get_
application_info() on page 156.
os_database::set_default_segment()
void set_default_segment(os_segment* db);
Sets the default segment for the specified database. The default segment is the
segment in which persistent memory is allocated by default when the function new
is called with only an os_database* argument. Initially the default segment is the
initial segment — the one segment (besides the schema segment) with which the
database was created. Changing the default segment remains in effect only for the
duration of the session and is invisible to other sessions. Simple ObjectStore
applications need not create any segments; all the database’s persistent data can be
stored in the initial segment, if you want. If more sophisticated clustering is required,
however, the application can create new segments in the database, and it might be
convenient to make one of these the default.
168
C++ A P I Reference
Chapter 2: Class Library
os_database::set_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
void set_fetch_policy(os_fetch_policy policy, os_int32 bytes);
Specifies the fetch policy for all clusters and segments in the specified database. The
default fetch policy is os_fetch_page. For more information about the arguments,
see objectstore::get_fetch_policy() on page 66. For information about
retrieving the fetch policy, see os_database::get_fetch_policy() on page 156.
os_database::set_incremental_schema_installation()
void set_incremental_schema_installation(os_boolean);
If nonzero (true) is supplied as the os_boolean argument, the schema installation
mode of the specified database is set to incremental mode. 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 the argument, the
mode is set to 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 the class is not already present in the database schema).
os_database::set_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
void set_lock_option(objectstore_lock_option);
Sets the locking behavior for the database specified by the this argument, including
all its segments and clusters. For information about the argument, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
Release 6.3
169
os_database
• objectstore::own_page_write on page 79
os_database::set_new_segment_reference_policy()
void
os_database::set_new_segment_reference_policy(
objectstore::segment_reference_policy ref_policy);
Sets the default reference policy for new segments in the this database. See os_
database::create_segment() on page 152.
os_database::set_null_illegal_pointers()
void set_null_illegal_pointers(os_boolean);
Provides a convenient way to set null_illegal_pointers mode for every segment
in the specified database. If the argument is nonzero (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 (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() on page 361.
os_database::set_schema_database()
void set_schema_database(os_database& schema_database);
If you move a schema database, you must use os_database::set_schema_
database( ) or the ObjectStore utility ossetrsp to inform ObjectStore of the schema
database’s new path name. Calling this function establishes schema_database as the
schema database for this. You must invoke this function outside any transaction.
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_size()
os_unsigned_int64 set_size(os_unsigned_int64 n_bytes);
Specifies the size in n_bytes of the database represented by the this argument and
returns the new size. If the database’s could not be changed (for example, this
database is a rawfs database or n_bytes would shrink the database), the size of the
database is unchanged, and the function returns the old size. The new size can be
smaller than the requested size if there was not enough disk space available.
This function can be called outside a transaction.
The set_size() function can be used to presize database files in order to minimize
fragmentation. For more information, see Managing Database Fragmentation in
Chapter 1 of Managing ObjectStore.
170
C++ A P I Reference
Chapter 2: Class Library
os_database::set_size_in_sectors()
os_unsigned_int32 set_size_in_sectors(
os_unsigned_int32 n_sectors);
Specifies the size in n_sectors of the database represented by the this argument
and returns the new size. A sector is 512 bytes. If the database’s could not be changed
(for example, this database is a rawfs database or n_sectors would shrink the
database), the size of the database is unchanged, and the function returns the old
size. The new size can be smaller than the requested size if there was not enough disk
space available.
This function can be called outside a transaction.
The set_size_in_sectors() function can be used to presize database files in order
to minimize fragmentation. For more information, see Managing Database
Fragmentation in Chapter 1 of Managing ObjectStore.
os_database::size()
os_unsigned_int32 size( ) const;
Returns the size in bytes of the specified database. If this number cannot be
represented in 32 bits, err_misc is signaled.
os_database::size_in_sectors()
os_unsigned_int32 size_in_sectors( ) const;
Returns the size in sectors of the specified database. If this number cannot be
represented in 32 bits, err_misc is signaled.
os_database::time_created()
os_unixtime_t time_created( ) const;
Returns the time at which the database was created.
Release 6.3
171
os_database_root
os_database_root
An object can be used as a database entry point if you associate a string with it by
using a root — an instance of the system-supplied class os_database_root. Each
root’s sole purpose is to associate an object with a name. After the association is
made, you can retrieve a pointer to the object by performing a look-up on the name
using a member function of the class os_database.
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_database_root::destroy()
void destroy();
Destroys the persistent root of the database for which the function is called. You
cannot use ::operator delete() to destroy a persistent root.
os_database_root::find()
static os_database_root* find(char* name, os_database* db);
Returns a pointer to the root in the specified database with the specified name.
Returns 0 if not found.
os_database_root::get_name()
const char* get_name( ) const;
Returns the name associated with the os_database_root for which the function is
called.
os_database_root::get_typespec()
const os_typespec* get_typespec( );
Returns a pointer to the typespec associated with the os_database_root for which
the function is called (the typespec last passed to set_value( ) for the root).
os_database_root::get_value()
void* get_value(os_typespec* typespec = 0);
Returns a pointer to the entry-point object associated with the os_database_root
for which the function is called. If an entry-point object was never set, this function
returns 0; see os_database_root::set_value() on page 174.
The return value is typed as void*, so a cast might be necessary when you use it. If
typespec does not match the typespec argument specified with os_database_
root::set_value(), err_typespec_mismatch is signaled. Note that this exception
172
C++ A P I Reference
Chapter 2: Class Library
is signaled if and only if the specified typespec does not match the stored typespec;
the actual type of the entry-point object is not checked.
os_database_root::release_pointer()
void release_pointer();
Releases the pointer specified by the implicit this argument.
When an application calls a function that returns an os_database_root pointer,
ObjectStore increments a use count of the number of times it has returned a pointer
to the same object. The use count thus represents the number of pointers to the same
object that are currently in use.
When the application calls release_pointer(), ObjectStore decrements the use
count for an ObjectStore object. When the last pointer is released, the count reaches
0 and the os_database_root object is deleted.
See the following for related information:
• The C++ A P I User Guide discusses how to release pointers.
• You can also release os_database_root pointers when they go out of scope; see
os_release_root_pointer on page 314.
• See os_database_root::retain_pointer() on page 173 for information about
retaining os_database_root pointers.
os_database_root::retain_pointer()
void retain_pointer();
Retains the pointer specified by the this argument.
When an application calls a function that returns an os_database_root pointer,
ObjectStore increments a use count of the number of times it has returned a pointer
to the same object. The use count thus represents the number of pointers to the same
object that currently are in use. The application calls os_database_root::release_
pointer() when it no longer needs the pointer, thus releasing it and decrementing
the use count.
When the application calls retain_pointer(), ObjectStore increments the use count
for an os_database_root object. Calling retain_pointer() ensures that the
pointer is retained even when another part of the application releases it.
For information about using retain_pointer(), see the C++ A P I User Guide. See
also os_database_root::release_pointer() on page 173.
Release 6.3
173
os_database_root
os_database_root::set_value()
void set_value(void* new_value, os_typespec* typespec = 0);
Establishes the object pointed to by new_value as the entry-point object associated
with the os_database_root for which the function is called. If new_value points to
transient memory or memory in a database other than the one containing the
specified os_database_root, err_invalid_root_value is signaled. The typespec
argument should designate the type of object pointed to by new_value. The typespec
(if specified) is stored for later use by os_database_root::get_value( ). See os_
database_root::get_value() on page 172.
os_database_root::~os_database_root()
~os_database_root( );
Called when a transient object of the class os_database_root is deleted. The
destructor cannot delete a persistent root or its name (a persistent char*).
174
C++ A P I Reference
Chapter 2: Class Library
os_database_schema
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a database
schema. os_database_schema is derived from os_schema.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_database_schema::get()
static const os_database_schema& get(const os_database& db);
Returns the schema of the specified database. Signals err_no_schema if the specified
database has no schema installed.
os_database_schema::get_for_update()
static os_database_schema& get_for_update(
const os_database& db
);
Returns the schema of the specified database. Signals err_no_schema if the specified
database has no schema installed. This differs from get( ) in that the return value is
a reference to a non-const os_database_schema rather than a const os_
database_schema.
os_database_schema::install()
void install(os_schema& new_schema);
Installs the classes in new_schema in the database schema specified by this.
Release 6.3
175
os_Database_table
os_Database_table
The database table records the mapping between predump objects and postload
objects. It stores sets of various kinds of fixups as well as the set of objects for which
object forms should not be generated. You can obtain the one and only instance of
this class with the static member get().
os_Database_table::find_reference()
os_Dumper_reference find_reference (
const os_Dumper_reference given_reference
) const;
Finds the postload object corresponding to a given predump object. Both objects are
specified with instances of os_Dumper_reference. The given_reference argument
refers to the predump object. The returned reference refers to the corresponding
postload object.
If there is no object that corresponds to the referent of given_reference, a null
reference is returned.
If given_reference is NULL, a null reference is returned.
os_Database_table::get()
static os_Database_table& get ();
Returns a reference to the one and only database table.
os_Database_table::insert()
void insert (
const os_Dumper_reference source,
const os_Dumper_reference target,
const os_type& referent_type
);
Inserts a mapping record that associates a predump object with a postload object.
Typically, you call this from type_loader::create().
The source argument is a dumper reference to the predump object. target is a
dumper reference to the postload object. referent_type refers to an os_type
representing the type of the object.
Overloadings
The following overloadings are supported:
void insert (
os_Reference_fixup_kind::Kind kind,
const os_Dumper_reference ref,
const os_Dumper_reference referent_original_location
);
Inserts a fixup record that instructs the loader to adjust the pointer, C++ reference,
or ObjectStore reference referred to by ref. The loader makes the adjustment after
loading all object forms and before loading any fixup forms. Typically, you call this
from type_loader::fixup().
176
C++ A P I Reference
Chapter 2: Class Library
kind is one of the following:
• os_Reference_fixup_kind::pointer
• os_Reference_fixup_kind::reference_local
• os_Reference_fixup_kind::reference_this_db
• os_Reference_fixup_kind::reference
• os_Reference_fixup_kind::reference_protected_local
• os_Reference_fixup_kind::reference_protected
The reference argument refers to the pointer or reference to be fixed up. The
referent_original_location refers to the predump referent of the pointer or
reference to be fixed up.
void insert (
os_segment& seg,
const os_Fixup& fixup
);
Associates the specified fixup dumper with the specified segment. Each fixup
dumper associated with a segment is invoked after all object forms for that segment
have been dumped. Typically, you call this function from type_dumper::operator
()().
void insert (
os_database& db,
const os_Fixup& fixup
);
Associates the specified fixup dumper with the specified database. Each fixup
dumper associated with a database is invoked after all object forms for that database
have been dumped. Typically, you call this function from type_dumper::operator
()().
void insert (
const os_Fixup& fixup
);
Associates the specified fixup dumper with the entire dump. Each fixup dumper
associated with the entire dump is invoked after all object forms for the dump have
been dumped. Typically, you call this function from type_dumper::operator ()().
void insert (
const os_Dumper_reference ignored_object
);
Inserts the specified object into the ignored set. If the object is already in the ignored
set, the insertion is silently ignored. Before dumping an object, the dumper checks to
see whether the object is in the ignored set. If it is, the dumper does not dump the
object.
ignored_object is a dumper reference to the object that should not be dumped.
os_Database_table::is_ignored()
os_boolean is_ignored (const os_Dumper_reference obj) const;
Returns nonzero if obj is in the ignored set; returns 0 otherwise.
Release 6.3
177
os_dbutil
os_dbutil
The database utility API provides C++ functions corresponding to the utilities
documented in Managing ObjectStore. You can use them as a basis for writing your
own database utilities and tools.
All the functions in this facility are members of the class os_dbutil. Call the
following function before using any other members of os_dbutil:
static void os_dbutil::initialize( );
You need to call this function only once in each application.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/dbutil.hh>.
os_dbutil::chgrp()
static void chgrp(
const char* pathname,
const char* gname
);
Changes the primary group of the rawfs directory or database whose name is
pathname. The gname argument is the name of the new group. This function does not
check for transaction consistency.
For information about using an ObjectStore utility to change the group name, see
oschgrp in Managing ObjectStore.
os_dbutil::chmod()
static void chmod(
const char* pathname,
const os_unsigned_int32 mode
);
Changes the protections on the rawfs database or directory whose name is pathname.
The mode argument specifies the new protections. This function does not check for
transaction consistency.
For information about using an ObjectStore utility to change permissions, see
oschmod in Managing ObjectStore.
os_dbutil::chown()
static void chown(
const char* pathname,
const char* uname
);
Changes the owner of the rawfs directory or database whose name is pathname. The
uname argument is the user name of the new owner. This function does not check for
transaction consistency.
178
C++ A P I Reference
Chapter 2: Class Library
For information about using an ObjectStore utility to change ownership, see
oschown in Managing ObjectStore.
os_dbutil::close_all_connections()
static void close_all_connections();
Closes the application’s connections to the cache manager and to all ObjectStore
servers.
os_dbutil::close_all_server_connections()
static void close_all_server_connections( );
Closes the application’s connections to all ObjectStore servers.
os_dbutil::close_server_connection()
static void close_server_connection(const char* hostname);
Closes the application’s connection to the ObjectStore server running on the machine
named hostname.
os_dbutil::cmgr_remove_file()
static char* cmgr_remove_file(
const char* hostname,
os_int32 cm_version_number
);
Makes the cache manager on the machine with the specified hostname delete all the
cache and commseg files that are not in use by any client. The cm_version_number
argument must match the cache manager’s version number. Returns a pointer to the
result message string.
For information about using an ObjectStore utility to remove cache and commseg
files, see oscmrf in Managing ObjectStore.
os_dbutil::cmgr_shutdown()
static char* cmgr_shutdown(
const char* hostname,
os_int32 cm_version_number
);
Shuts down the cache manager running on the machine with the specified hostname.
The cm_version_number argument must match the cache manager’s version
number. Returns a pointer to the result message string.
For information about using an ObjectStore utility to shut down the cache manager,
see oscmshtd in Managing ObjectStore.
os_dbutil::cmgr_stat()
static void cmgr_stat(
const char* hostname,
os_int32 cm_version_number,
Release 6.3
179
os_dbutil
os_cmgr_stat* cmstat_data
);
Gets information for the cache manager on the machine with the specified hostname.
The cm_version_number argument must match the cache manager’s version
number.
The cmstat_data argument points to an instance of os_cmgr_stat allocated by the
caller, using the no-argument constructor. The class os_cmgr_stat has the
following public data members:
os_unsigned_int32
struct_version;
os_unsigned_int32
major_version;
os_unsigned_int32
minor_version;
os_unsigned_int32
pid;
char
*executable_name;
char
*host_name;
os_unixtime_t
start_time;
os_int32
soft_limit;
os_int32
hard_limit;
os_int32
free_allocated;
os_int32
used_allocated;
os_int32
n_clients;
os_cmgr_stat_client
*per_client; /* array */
os_int32
n_servers;
os_cmgr_stat_svr
*per_server; /* array */
os_int32
n_cache_file_usage;
os_cmgr_stat_file_usage
*cache_file_usage; /* array */
os_int32
n_comseg_file_usage;
os_cmgr_stat_file_usage
*comseg_file_usage; /* array */
char
*cback_queue;
char
*extra;
The constructor sets struct_version to the value of os_free_blocks_version in
the dbutil.hh file included by your application. If this version is different from that
used by the library, err_misc is signaled. The constructor initializes all other
members to 0.
Within the results returned by os_dbutil::cmgr_stat, the information about each
client is provided in an object of class os_cmgr_stat_client. A data member named
notification, whose type is os_cmgr_stat_notification*, has been added to
class os_cmgr_stat_client.
The value of this pointer is 0 if this client is not using notifications because, for
example, the client has not yet called os_notification::subscribe() or os_
notification::_get_fd().
Otherwise, the value is a pointer to an object of the class os_cmgr_stat_
notification.
180
C++ A P I Reference
Chapter 2: Class Library
The class os_cmgr_stat_client has the following public data members:
os_unsigned_int32
struct_version;
os_unsigned_int32
queue_size;
os_unsigned_int32
n_queued;
os_unsigned_int32
n_received;
os_unsigned_int32
queue_overflows;
os_unsigned_int32
thread_state;
os_int32
pid;
os_unsigned_int32
euid;
char*
name;
os_int32
major_version;
os_int32
minor_version;
os_int32
commseg;
The class os_cmgr_stat_svr has the following public data members:
os_unsigned_int32
struct_version;
char
*host_name;
os_int32
client_pid;
char
*status_str;
The class os_cmgr_stat_file_usage has the following public data members:
os_unsigned_int32
struct_version;
char
*file_name;
os_unsigned_int32
file_length;
os_boolean
is_free;
For information about using an ObjectStore utility to get information about the cache
manager, see oscmstat in Managing ObjectStore.
os_dbutil::compare_schemas()
static os_boolean compare_schemas(
const os_database* db1,
const os_database* db2,
os_boolean verbose = 1
os_boolean layout_only = 0
);
Compares the schemas of db1 and db2. Returns nonzero if the schemas are
incompatible, and 0 otherwise. Each database can contain an application schema, a
compilation schema, or a database schema. If the database contains a database
schema, it can be local or remote.
If verbose is nonzero, the function issues a message to standard output that
describes any incompatibility.
If layout_only is nonzero, this overloading compares only the layouts of persistent
classes in the databases.
Release 6.3
181
os_dbutil
For information about using an ObjectStore utility to compare schema, see osscheq
in Managing ObjectStore.
os_dbutil::copy_database()
static void copy_database(
const char* src_database_name,
const char* dest_database_name
);
Copies the database named src_database_name and names the copy dest_
database_name. The database is copied in a separate thread, using a separate
transaction. If there is already a database named dest_database_name, it is silently
overwritten. If the copy fails for any reason, this function signals an exception.
For information about using an ObjectStore utility to copy a database, see oscopy in
Managing ObjectStore.
os_dbutil::disk_free()
static void disk_free(
const char*hostname,
os_free_blocks* blocks
);
Gets disk space usage in the rawfs managed by the ObjectStore server on the
machine named hostname. The blocks argument points to an instance of os_free_
blocks allocated by the caller, using the no-argument constructor.
The class os_free_blocks has the following public data members:
os_unsigned_int32
struct_version;
os_unsigned_int32
free_blocks;
os_unsigned_int32
file_system_size;
os_unsigned_int32
used_blocks;
disk_free( ) sets the values of these data members for the instance of os_free_
blocks pointed to by the blocks argument.
The os_free_blocks constructor sets struct_version to the value of os_free_
blocks_version in the dbutil.hh file included by your application. If this version
is different from that used by the library, err_misc is signaled.
For information about using an ObjectStore utility to get disk space information, see
osdf in Managing ObjectStore.
os_dbutil::expand_global()
static os_char_p* expand_global(
char const* glob_path,
os_unsigned_int32& n_entries
);
Returns an array of pointers to rawfs path names matching glob_path by expanding
glob_path’s wildcards (*, ?, {}, and [ ]). The n_entries argument is set to refer to
182
C++ A P I Reference
Chapter 2: Class Library
the number of path names returned. It is the caller’s responsibility to delete the array
and path names when they are no longer needed.
For information about using an ObjectStore utility to expand a pathname, see osglob
in Managing ObjectStore.
os_dbutil::file_db_pathname()
static os_boolean file_db_pathname(const char *pathname);
Returns nonzero (true) if pathname is a file-system pathname and 0 (false) if it is a
rawfs pathname.
See also os_dbutil::split_pathname() on page 191.
os_dbutil::get_client_name()
static char const* get_client_name( );
Returns the pointer last passed to set_client_name( ). If there was no prior call to
set_client_name( ), 0 is returned. This function does not allocate any memory.
os_dbutil::get_sector_size()
static os_unsigned_int32 get_sector_size( );
Returns 512, the size of a sector in bytes. Certain ObjectStore utilities (for example,
ossvrstat) report some of their results in numbers of sectors, and some ObjectStore
server parameters are specified in sectors.
os_dbutil::hostof()
static const char* hostof(const char *pathname);
Returns the name of the host of the database specified by pathname.
For information about using an ObjectStore utility to get the name of the host of a
database, see oshostof in Managing ObjectStore.
os_dbutil::initialize()
static void initialize( );
Call this before using any other members of os_dbutil. You need to call this
function only once in each application.
os_dbutil::install_backrest_control_c_handler()
void install_backrest_control_c_handler( );
Call this function to install the control-c handler for backup-and-restore (backrest)
operations. The backrest control-c handler ensures that when the application is killed
with a control-c, os_archive, os_backup, and os_replicator processes will
complete the current snapshot and terminate cleanly. For os_recover and os_
restore processes the current restore or recover transaction will be aborted.
Release 6.3
183
os_dbutil
This function should not be called when an application has its own control-c handler
installed.
For more information about ObjectStore’s backup-and-restore API, see the
following:
• os_archiver on page 104
• os_backup on page 110
• os_recover on page 287
• os_replicator on page 316
• os_restore on page 323
os_dbutil::list_directory()
static os_rawfs_entry_p* list_directory(
const char* rawfs_path,
os_unsigned_int32& n_entries
);
Lists the contents of the rawfs directory named rawfs_path. Returns an array of
pointers to os_rawfs_entry_p objects. The n_entries argument is set to the
number of elements in the returned array. If rawfs_path does not specify the
location of a directory, err_not_a_directory is signaled. It is the caller’s
responsibility to delete the array and os_rawfs_entry_p objects when they are no
longer needed.
For information about using an ObjectStore utility to list a rawfs directory, see osls
in Managing ObjectStore.
os_dbutil::make_link()
static void make_link(
const char* target_name,
const char* link_name
);
Makes a rawfs soft link. The target_name argument is the path pointed to by the
link, and link_name is the path name of the link. Signals err_database_exists or
err_directory_exists if link_name already points to an existing database or
directory.
A rawfs can have symbolic links pointing within itself or to another ObjectStore
server’s rawfs. The server follows symbolic links within its rawfs for all os_dbutil
members that pass path name arguments, unless otherwise specified by a function’s
description; only os_dbutil::stat( ) can override this behavior. All members
passing path name arguments also follow cross-server links on the application side,
unless otherwise specified by a function’s description.
A rawfs symbolic link always has the ownership and the permissions of the parent
directory.
For information about using an ObjectStore utility to create a rawfs link, see osln in
Managing ObjectStore.
184
C++ A P I Reference
Chapter 2: Class Library
os_dbutil::mkdir()
static void mkdir(
const char* rawfs_path,
const os_unsigned_int32 mode,
os_boolean create_missing_dirs = 0
);
Makes a rawfs directory whose path is rawfs_path. The new directory’s protection
is specified by mode. If create_missing_dirs is nonzero, creates the missing
intermediate directories. Signals err_directory_not_found if create_missing_
dirs is 0 and there are missing intermediate directories. Signals err_directory_
exists if there is already a directory with the specified path. Signals err_database_
exists if there is already a database with the specified path.
For information about using an ObjectStore utility to create a rawfs directory, see
osmkdir in Managing ObjectStore.
os_dbutil::osdbcontrol()
static void osdbcontrol(
const char** pathnames,
os_unsigned_int32 n_pathnames,
os_dbcontrol_options& options,
os_dbcontrol_result* results = 0
);
Performs various operations on a list of databases where n_pathnames is the number
of database names in the array. options is a reference to an instance of os_
dbcontrol_options allocated by the user using the zero-argument constructor. If
os_dbcontrol_options is a flag_status or flag_statistics request and
results is not null, the results from the request will be saved in the os_dbcontrol_
result object pointed to by result. See os_dbcontrol_result for additional
information.
Calling os_dbutil::osdbcontrol with the flag_offline option from an
application that currently has the database open will result in the application
hanging. This is because the processing of the offline request will first wait for all
users to close the database, including the outstanding open from the same
application that issued the offline request.
The os_dbcontrol_options class has the following public data members
os_boolean flag_offline
Set database offline; corresponds to the
osdbcontrol utility’s -offline option.
os_boolean flag_online
Set database online; corresponds to the
osdbcontrol utility’s -online option.
os_boolean flag_kill_clients Disconnect all clients using the database before
setting offline; corresponds to the
osdbcontrol utility’s -kill_clients option.
os_boolean flag_status
Release 6.3
Display database status; corresponds to the
osdbcontrol utility’s -status option.
185
os_dbutil
os_boolean flag_statistics
Display database statistics; corresponds to the
osdbcontrol utility’s -statistics option.
os_boolean flag_do_print
Print status or statistic information, default is
TRUE, which specifies always print.
char* reason_str
Append a reason string to the offline exception
message. The string is deleted in ~os_
dbcontrol_options().
The os_dbcontrol_options class has the following public method:
void reset()
Reset all the options.
The results of flag_status and flag_statistics requests are returned in the os_
dbcontrol_result object pointed to by the results argument passed to os_
dbcontrol(). The os_dbcontrol_option data member flag_do_print should be
set to zero to suppress os_dbutil::os_dbcontrol from printing the status and
statistics information.
The os_dbcontrol_result class has the following public data members:
os_unsigned_int32 n_info
Number of database names
os_db_statistic_info**
statistic_info
Array of statistics information
os_db_status_info ** status_info
Array of status information
char ** pathnames
Array of database names
The os_dbcontrol_result class has the following public methods:
void format_and_print_status(os_unsigned_int32 index);
The above method formats and prints status information for the database specified
by index in the database names array .
void format_and_print_statistics(os_unsigned_int32 index);
The above method formats and prints statistic information for the database specified
by index in the database names array.
void initialize(
const char** pathns,
os_unsigned_int32 n_pathns,
const os_dbcontrol_options& options
);
The above method initializes all data members. It is always called by os_
dbutil::osdbcontrol().
For information about using an ObjectStore utility that corresponds to os_
dbutil::osdbcontrol(), see osdbcontrol in Managing ObjectStore.
os_dbutil::ossize()
static os_int32 ossize(
const char* db_path,
const os_size_options* opts
186
C++ A P I Reference
Chapter 2: Class Library
);
Prints to standard output the size of the database whose name is db_path. The opts
argument points to an instance of os_size_options that has been allocated by the
caller with the no-argument constructor. This function returns 0 for success, –1 for
failure.
If OS__DBUTIL_NO_MVCC is set, this function opens the database for read only, rather
than for MVCC (the default).
The class os_size_options has the following public data members:
os_unsigned_int32 struct_version;
os_boolean
flag_all;
/* -a */
os_boolean
flag_segments;
os_boolean
flag_total_database;
os_boolean
flag_fragmentation;
/* -f */
os_unsigned_int32 one_segment_number;
/* -n */
/* -c */
/* -C */
os_boolean
flag_every_object; /* -o */
char
flag_summary_order;
/* -s ‘s’=space ‘n’=number ‘t’=typename */
os_boolean
flag_upgrade_rw; /* -u */
os_boolean
flag_internal_segments; /* -0 */
os_boolean
flag_access_control; /* -A */
The constructor sets struct_version to the value of os_size_options_version in
the dbutil.hh file included by your application. If this version is different from that
used by the library, err_misc is signaled. The constructor initializes all other
members to 0.
For information about using an ObjectStore utility to get the size of a database, see
ossize in Managing ObjectStore. Note that each public data member of os_size_
options corresponds to an option of ossize.
os_dbutil::osverifydb()
static os_unsigned_int32 osverifydb(
const char* db_path,
os_verifydb_options* opt = 0
);
Prints to standard output all pointers and references in the database named db_path.
The opt argument points to an instance of os_verifydb_options that has been
allocated by the caller with the no-argument constructor.The function returns 0 for
success, 1 for failure.
Note that you must call os_collection::initialize( ) and os_
mop::initialize( ) before calling this function.
If OS_ _DBUTIL_NO_MVCC is set, this function opens the database for read only, rather
than for MVCC (the default).
Release 6.3
187
os_dbutil
The class os_verifydb_options has the following public data members:
os_boolean verify_segment_zero;
/* verify the schema segment */
os_boolean verify_collections;
/* check all top-level collections */
os_boolean verify_pointer_verbose; /* print pointers as they are verified */
os_boolean verify_object_verbose;
/* print objects as they are verified */
os_boolean verify_references;
/* check all OS references */
os_int32 segment_error_limit;
/* maximum errors per segment */
os_boolean print_tag_on_errors;
/* print out the tag value on error */
const void* track_object_ptr;
/* Track object identified by pointer */
const char* track_object_ref_
string;
/* Track the object identified by the
reference string. */
enum {
default_action,
ask_action,
null_action
} illegal_pointer_action;
For information about using an ObjectStore utility to verify pointers and references
in a database, see osverifydb in Managing ObjectStore.
os_dbutil::osverifydb_one_segment()
static os_unsigned_int32 osverifydb_one_segment(
const char* db_path,
os_unsigned_int32 seg_num,
os_unsigned_int32 cluster_start_number = 0,
os_unsigned_int32 cluster_end_number = 0,
os_unsigned_int32 starting_offset = 0,
os_unsigned_int32 ending_offset = 0,
os_verifydb_options* opt = 0
);
Prints to standard output all pointers and references in seg_num in the database
named db_path.
The cluster_start_number and cluster_end_number arguments limit
verification to a range of clusters in seg_num. To limit verification to one cluster,
specify the same cluster number for both cluster_start_number and cluster_
end_number. If you omit these arguments or specify 0 for each, all clusters within the
segment are verified.
The offset items specify the starting and ending offsets (in bytes) in each cluster
within seg_num in which verification is to occur. If starting_offset is not
specified, it defaults to 0. This means verification starts at the beginning of the
segment. Similarly, if ending_offset is not specified, it defaults to 0. This means
verify to the end of the segment. The opt argument points to an instance of os_
verifydb_options that has been allocated by the caller with the no-argument
constructor. The function returns 0 for success, 1 for failure.
You must call os_collection::initialize() and os_mop::initialize() before
calling this function. If OS_ _DBUTIL_NO_MVCC is set, this function opens the database
for read only, rather than for MVCC (the default).
188
C++ A P I Reference
Chapter 2: Class Library
The class os_verifydb_options has the following public data members:
os_boolean verify_segment_zero;
/* verify the schema segment */
os_boolean verify_collections;
/* check all top-level collections */
os_boolean verify_pointer_verbose
/* print pointers as they are verified
*/
os_boolean verify_object_verbose
/* print objects as they are verified */
os_boolean verify_references
/* check all OS references */
os_int32 segment_error_limit
/* maximum errors per segment */
os_boolean print_tag_on_errors
/* print out the tag value on error */
const void* track_object_ptr
/* Track object identified by pointer */
const char* track_object_ref_string /* Track the object identified by the
reference string. */
enum {
default_action,
ask_action,
null_action
} illegal_pointer_action;
For information about using an ObjectStore utility to verify pointers and references
in a database, see osverifydb in Managing ObjectStore.
os_dbutil::rehost_all_links()
static void rehost_all_links(
const char* server_host,
const char* old_host,
const char* new_host
);
Changes the hosts of specified rawfs links. The server_host argument specifies the
host containing the links to be changed. All links pointing to old_host are changed
to point to new_host. On some operating systems, you must have special privileges
to use this function.
For information about using an ObjectStore utility to change the hosts of rawfs links,
see oschhost in Managing ObjectStore.
os_dbutil::rehost_link()
static void rehost_link(
const char* pathname,
const char* new_host
);
Changes the host to which a rawfs link points. The pathname argument must specify
a symbolic link, otherwise err_not_a_link is signaled. The new_host argument
specifies the new ObjectStore server host.
For information about using an ObjectStore utility to change the host of a rawfs link,
see oschhost in Managing ObjectStore.
Release 6.3
189
os_dbutil
os_dbutil::remove()
static void remove(const char* path);
Removes the database or rawfs link with the specified name. If path names a link,
the link is removed but the target of the link is not. If path names a directory, it is not
removed. Signals err_not_a_database if path exists in a rawfs but is not a
database. Signals err_file_error when a problem is reported by the ObjectStore
server host’s file system. Signals err_file_not_local if the file is not local to this
server.
For information about using an ObjectStore utility to remove a database or rawfs
link, see osrm in Managing ObjectStore.
os_dbutil::rename()
static void rename(
const char* source,
const char* target
);
Renames the rawfs database or directory. The source argument is the old name and
target is the new name. Signals err_cross_server_rename if source and target
are on different ObjectStore servers. Signals err_invalid_rename if the operation
makes a directory its own descendant. Signals err_database_exists if a database
named target already exists. Signals err_directory_exists if a directory named
target already exists.
For information about using an ObjectStore utility to rename (that is, move) a rawfs
database or directory, see osmv in Managing ObjectStore.
os_dbutil::rmdir()
static void rmdir(const char* rawfs_path);
Removes the rawfs directory with the specified path. Signals err_directory_not_
empty if the directory still contains databases. Signals err_not_a_directory if the
argument does not specify a directory path.
For information about using an ObjectStore utility to remove a rawfs directory, see
osrmdir in Managing ObjectStore.
os_dbutil::set_application_schema_path()
static char* set_application_schema_path(
const char* executable_path,
const char* new_schema_path
);
Finds or sets an executable’s application schema database. The executable_path
argument specifies the executable. The new_schema_path argument is either the new
schema’s path name or 0. If new_schema_path is 0, the function returns new storage
containing the current path name. If new_schema_path is nonzero, the function
returns 0.
190
C++ A P I Reference
Chapter 2: Class Library
For information about using an ObjectStore utility to set an executable’s application
schema database, see ossetasp in Managing ObjectStore.
os_dbutil::set_client_name()
static void set_client_name(const char* name);
Sets the client name string for message printing.
os_dbutil::split_pathname()
static os_boolean split_pathname(
const char *input_pathname_arg,
os_char_p *server_name,
os_char_p *filename);
Returns nonzero (true) if input_pathname_arg is a file-system pathname and 0
(false) if it is a rawfs pathname. If input_pathname_arg begins with a host name
(followed by : or ::), the host name is copied to server_name, and the remainder of
the path is copied to filename. If there is no host name at the head of input_
pathname_arg, ObjectStore sets server_name to null and copies input_pathname_
arg to filename.
ObjectStore allocates storage for the server_name and filename arguments. It is the
user’s responsibility to deallocate the storage when it is no longer needed.
See also os_dbutil::file_db_pathname() on page 183.
os_dbutil::start_backrest_logging()
static void start_backrest_logging(
const char* log_name,
os_boolean append = 0,
os_boolean write_log_only = 0
);
Directs backup-and-restore messages to the specified backrest log file. The log_name
argument specifies the log file to which messages are written. If the append
argument is set to true, all output messages will be appended to the log file. If the
write_log_only argument is set to true, all output messages will be written to the
log file and none will be directed to stdout.
This function must be called before starting any backup-and-restore operations.
For information about stopping output to the backrest log, see os_dbutil::stop_
backrest_logging() on page 192. For more information about ObjectStore’s
backup-and-restore API, see the following:
• os_archiver on page 104
• os_backup on page 110
• os_recover on page 287
• os_replicator on page 316
• os_restore on page 323
Release 6.3
191
os_dbutil
os_dbutil::stat()
static os_rawfs_entry* stat(
const char* rawfs_path,
const os_boolean b_chase_links = 1
);
Gets information about a rawfs path name. If b_chase_links is false and the path is
a link, the ObjectStore server does not follow it. The server still follows intrarawfs
links for the intermediate parts of the path.
Returns a pointer to an os_rawfs_entry to be destroyed by the caller, or 0 on error.
For information about using an ObjectStore utility to get information about a rawfs
pathname, see ostest and osls in Managing ObjectStore.
os_dbutil::stop_backrest_logging()
static void stop_backrest_logging();
Stops the writing of backup-and-restore messages to the backrest log file.
For information about starting output to the backrest log, see os_dbutil::start_
backrest_logging() on page 191. For more information about ObjectStore’s
backup-and-restore API, see the following:
• os_archiver on page 104
• os_backup on page 110
• os_recover on page 287
• os_replicator on page 316
• os_restore on page 323
os_dbutil::svr_checkpoint()
static os_boolean svr_checkpoint(
const char* hostname
);
Makes the specified ObjectStore server take a checkpoint asynchronously. Returns
nonzero when successful, 0 or an exception on failure.
For information about using an ObjectStore utility to make a server take a
checkpoint, see ossvrchkpt in Managing ObjectStore.
os_dbutil::svr_client_kill()
static os_boolean svr_client_kill(
const char* server_host,
os_int32 client_pid,
const char* client_name,
const char* client_hostname,
os_boolean all,
os_int32& status
);
192
C++ A P I Reference
Chapter 2: Class Library
Kills one or all clients of the specified ObjectStore server. The function returns 0
(false) if it fails and nonzero (true) if it succeeds.
The server_host argument is the name of the machine running the server. client_
pid is the process ID of the client to kill. client_name is the name of the client to kill.
client_hostname is the name of the machine running the client to kill.
If all is 1, all clients matching the specified criteria will be disconnected.
If the function fails (that is, it returns 0), you can examine status to learn the reason.
status is set to one of the following:
Return value
Meaning
1
The user was authorized to disconnect the specified clients.
-1
The user was denied access.
0
No clients matched the specified criteria.
2
More than one client matched the specified criteria.
For information about using an ObjectStore utility to disconnect a client, see
ossvrclntkill in Managing ObjectStore.
os_dbutil::svr_debug()
static os_boolean svr_debug(
const char *server_host,
os_unsigned_int32 debug_level);
Enables the output of debugging information for the server specified by server_
host. If successful, this function returns nonzero (true). Debugging information is
directed to standard output. The debug_level argument is an integer in the range 0
- 9, which specifies the level of debugging information. The higher the number, the
more information that is displayed. Specifying 0 disables debugging output.
For information about using the ossvrdebug utility to enable debugging output, see
ossvrdebug in Managing ObjectStore.
os_dbutil::svr_machine()
static const char* svr_machine(
const char* p_server_host);
Maps p_server_host (the name of a server) to the name of the machine on which
the server runs. If p_server_host is a logical server name, os_dbutil::svr_
machine() returns the machine name from the SERVER declaration in the locator file.
Otherwise, os_dbutil::svr_machine() returns p_server_host — that is, the
name of the machine is the name of the server. For information about the SERVER
declaration, see SERVER Declaration (ObjectStore-Managed Failover Only) in
Chapter 2 of Managing ObjectStore.
Note
Release 6.3
You cannot use os_dbutil::svr_machine() to map a logical host name as used
with Sun Clusters operating system to the name of the machine (cluster node) that is
193
os_dbutil
currently handling network connections to that logical host name. The node that is
currently being used can change at any time.
os_dbutil::svr_ping()
static char* svr_ping(
const char* server_host,
os_svr_ping_state& state
);
Returns a pointer to the status message string.
This function determines whether an ObjectStore server is running on the machine
named server_host. The referent of state is set to one of the following global
enumerators:
• os_svr_ping_is_alive
• os_svr_ping_not_reachable
• os_svr_ping_no_such_host
Returns a pointer to the status message string.
The os_dbutil::svr_ping() function returns the enumerator os_svr_ping_is_
alive_as_failover_backup if it is possible that the ObjectStore server is running in
backup failover mode. The heuristic for determining whether it possibly is running
in backup mode is if the exception err_broken_connection is signaled while
pinging a server and the current locator file indicates that the server is a member of
a failover pair.
For information about using an ObjectStore utility to ping a server, see ossvrping in
Managing ObjectStore.
os_dbutil::svr_shutdown()
static os_boolean svr_shutdown(
const char* server_host
);
Shuts down the ObjectStore server on the machine named server_host. Returns
nonzero for success, 0 otherwise. On some operating systems, you must have special
privileges to use this function.
For information about using an ObjectStore utility to shut down a server, see
ossvrshtd in Managing ObjectStore.
os_dbutil::svr_stat()
static void svr_stat(
const char* server_host,
os_unsigned_int32 request_bits,
os_svr_stat* svrstat_data
);
Retrieves statistics for an ObjectStore server on server_host.
194
C++ A P I Reference
Chapter 2: Class Library
The request_bits argument specifies the information that is desired. Supply this
argument by forming the bit-wise disjunction of zero or more of the following
enumerators:
• os_svr_stat::get_svr_rusage: displays server process information (UNIX
only)
• os_svr_stat::get_svr_meter_samples: displays performance meters for the
specified server
• os_svr_stat::get_svr_parameters : displays server parameter values
• os_svr_stat::get_client_info_self: displays information about the client
that called os_dbutil::svr_stat()
• os_svr_stat::get_client_info_others: displays the state of each client that is
connected to this server and shows any clients that are contending for locks
• os_svr_stat::get_log_statistics: displays information about the server
transaction log on this database
• os_svr_stat::get_client_open_databases: displays information about
databases open by each client connected to this server
For each enumerator that is specified, the corresponding information is retrieved.
(With ObjectStore/Single, only the get_svr_meter_samples and get_log_
statistics arguments are supported.)
For each of the classes described in the following paragraphs, the constructor sets
struct_version to the value in the dbutil.hh file included by your application. If
this version is different from that used by the library, err_misc is signaled. The
constructor initializes all other members to 0.
svrstat_data points to an os_svr_stat object. The user allocates an instance of the
os_svr_stat class by calling the no-argument constructor, os_svr_stat(). The os_
svr_stat class has the following public data members:
os_unsigned_int32
struct_version;
os_svr_stat_svr_header
header;
os_svr_stat_svr_parameters*
svr_parameters;
os_svr_stat_svr_rusage*
svr_rusage;
os_svr_stat_svr_meters*
svr_meter_samples;
os_unsigned_int32
n_meter_samples;
os_svr_stat_client_info*
client_info_self;
os_svr_stat_client_info*
client_info_others;
os_unsigned_int32
n_clients;
os_svr_stat_extension*
p_extended_status;
The os_dbutil::svr_stat() function allocates these and all other pointer-valued
members of all classes mentioned in this section. The ~os_svr_stat() destructor
deallocates them.
The class os_svr_stat_svr_header has the following public data members:
os_unsigned_int32
Release 6.3
struct_version;
195
os_dbutil
char*
os_release_name;
os_unsigned_int32
server_major_version;
os_unsigned_int32
server_minor_version;
char*
compilation;
The class os_svr_stat_svr_parameters has the following public data members.
(There is no member corresponding to the Failover Script server parameter.)
196
os_unsigned_int32
struct_version;
os_boolean
allow_nfs_locks;
os_boolean
allow_remote_database_access;
os_boolean
allow_shared_mem_usage;
os_int32*
authentication_list;
os_unsigned_int32
cache_mgr_ping_time;
os_svr_stat_growth_policy
cluster_growth_policy;
os_unsigned_int32
current_log_size_sectors;
os_svr_stat_growth_policy
database_file_growth_policy;
os_int32
deadlock_strategy;
os_unsigned_int32
direct_to_segment_threshold;
char*
failover_heartbeat_file_pathname;
os_unsigned_int32
failover_heartbeat_time
os_unsigned_int32
growth_log_data_sectors;
os_unsigned_int32
growth_log_record_sectors;
char*
identical_pathnames_on_failover_server;
os_unsigned_int32
initial_log_data_sectors;
os_unsigned_int32
initial_log_record_sectors;
os_unsigned_int32
log_buffer_sectors;
char*
log_path;
os_unsigned_int32
max_aio_threads;
os_unsigned_int32
max_connect_memory_usage;
os_unsigned_int32
max_data_propagation_threshold;
os_unsigned_int32
max_memory_usage;
os_unsigned_int32
max_msg_buffer_sectors;
os_unsigned_int32
max_msg_buffers;
os_unsigned_int32
max_propagation_sectors;
os_unsigned_int32
max_two_phase_delay;
os_unsigned_int32
n_authentications;
char*
parameter_file;
os_int32
rawfs_db_expiration_time;
os_svr_stat_growth_policy
rawfs_partition_growth_policy;
os_unsigned_int32
remote_db_grow_reserve;
os_int32
restricted_file_db_access_only;
os_unsigned_int32
sleep_time_between_2p_outcomes;
C++ A P I Reference
Chapter 2: Class Library
os_unsigned_int32
sleep_time_between_propagates;
os_unsigned_int32
tcp_recv_buffer_size;
os_unsigned_int32
tcp_send_buffer_size;
os_unsigned_int32
write_buffer_sectors;
The os_svr_stat_growth_policy class has the following public data members:
os_unsigned_int32* growth;
os_boolean* percentage;
os_unsigned_int32* limit;
The members have the following meanings:
• growth specifies the number of sectors, or the percentage, to grow
• percentage specifies whether the growth member represents an absolute size
(false) or a percentage (true)
• limit specifies the size limit that determines whether or not this growth policy
should be applied. It applies only if the current size of the cluster, database file, or
rawfs partition is less than or equal to the value specified for limit.
Each of the members (growth, percentage, and limit) is an array. A growth policy
consists of a sequence of triplets, with one element from each array making up a
triplet. Thus, { growth[0], percentage[0], limit[0] } is the first policy
element, { growth[1], percentage[1], limit[1] } is the second if there are at
least two, and so on. The end of the array is signalled when the value of limit[n] is
the one’s complement of zero (~0).
The os_svr_stat_svr_rusage class has the following public data members:
os_unsigned_int32
struct_version;
os_timesecs
ru_utime;
/* user time used */
os_timesecs
ru_stime;
/* system time used */
os_int32
ru_maxrss;
/* maximum resident set size */
os_int32
ru_ixrss;
/* integral shared memory size */
os_int32
ru_idrss;
/* integral unshared data size */
os_int32
ru_isrss;
/* integral unshared stack size */
os_int32
ru_minflt;
/* page reclaims */
os_int32
ru_majflt;
/* page faults */
os_int32
ru_nswap;
/* swaps */
os_int32
ru_inblock;
/* block input operations */
os_int32
ru_oublock;
/* block output operations */
os_int32
ru_msgsnd;
/* messages sent */
os_int32
ru_msgrcv;
/* messages received */
os_int32
ru_nsignals;
/* signals received */
os_int32
ru_nvcsw;
/* voluntary context switches */
os_int32
ru_nivcsw;
/* involuntary context switches */
The classes os_svr_stat_svr_meters and os_svr_stat_client_meters each
have data members named n_notifies_sent and n_notifies_received. All four
Release 6.3
197
os_dbutil
are of type os_unsigned_int32. They give the total number of notifications that
have been received by the ObjectStore server and the number that have been sent by
the server, giving the total for the server as a whole and the total for each client.
The class os_svr_stat_svr_meters has the following public data members:
os_unsigned_int32
198
struct_version;
os_boolean
valid;
os_unsigned_int32
n_minutes;
os_unsigned_int32
n_receive_msgs;
os_unsigned_int32
n_callback_msgs;
os_unsigned_int32
n_callback_sectors_requested;
os_unsigned_int32
n_callback_sectors_succeeded;
os_unsigned_int32
n_sectors_read;
os_unsigned_int32
n_sectors_written;
os_unsigned_int32
n_commit;
os_unsigned_int32
n_phase_2_commit;
os_unsigned_int32
n_readonly_commit;
os_unsigned_int32
n_abort;
os_unsigned_int32
n_phase_2_abort;
os_unsigned_int32
n_deadlocks;
os_unsigned_int32
n_msg_buffer_waits;
os_unsigned_int32
n_log_records;
os_unsigned_int32
n_log_seg_switches;
os_unsigned_int32
n_flush_log_data_writes;
os_unsigned_int32
n_flush_log_record_writes;
os_unsigned_int32
n_log_data_writes;
os_unsigned_int32
n_log_record_writes;
os_unsigned_int32
n_sectors_propagated;
os_unsigned_int32
n_sectors_direct;
os_unsigned_int32
n_do_some_propagation;
os_unsigned_int32
n_notifies_sent;
os_unsigned_int32
n_notifies_received;
os_unsigned_int32
n_lock_waits;
os_timesecs
total_lock_wait_time;
C++ A P I Reference
Chapter 2: Class Library
The class os_svr_stat_client_info has the following public data members:
os_unsigned_int32
struct_version;
os_svr_stat_client_process*
process;
os_svr_stat_client_state*
state;
os_svr_stat_client_meters*
meters;
The class os_svr_stat_open_database_info has the following public data
members:
os_unsigned_int32
struct_version;
char*
pathname; // Pathname of an open database
os_unsigned_int32
when_open; // time (in time_t) when database was opened
os_unsigned_int32
how_long_open; // Number of seconds open
os_unsigned_int32
aio_thread_serial_number; // Which thread serves this DB
os_boolean
b_writable; // Open for writing
os_boolean
b_mvcc; // Open in MVCC mode
os_boolean
b_houdini; // What kind of database
os_boolean
b_rawhfs; // Where stored
os_boolean
b_read_locked; // Any read locks in this DB
os_boolean
b_write_locked; // Any write locks in this DB
os_boolean
b_read_owned; // Any read ownership in client cache
os_boolean
b_write_owned; // Any write ownership in client cache
os_boolean
b_used_in_transaction; // Current txn accessed this DB
os_boolean
b_mod_in_transaction; // Current txn modified this DB
os_boolean
b_mvcc_conflict; // Current txn conflicts with MVCC txn
The class os_svr_stat_client_process has the following public data members:
os_unsigned_int32
struct_version;
char*
host_name;
os_unsigned_int32
process_id;
char*
client_name;
os_unsigned_int32
client_id;
The class os_svr_stat_client_state has the following public data members:
Release 6.3
os_unsigned_int32
struct_version;
os_client_state_type
client_state;
char*
message_name;
os_boolean
txn_in_progress;
os_unsigned_int32
txn_priority;
os_unsigned_int32
txn_duration;
os_unsigned_int32
txn_work;
os_client_lock_type
lock_state;
os_unsigned_int32
db_id;
199
os_dbutil
char*
db_pathname;
os_unsigned_int32
locked_seg_id;
os_unsigned_int32
locked_cluster_id;
os_unsigned_int32
locking_start_sector;
os_unsigned_int32
locking_for_n_sectors;
os_unsigned_int32
n_conflicts;
os_svr_stat_client_process*
lock_conflicts;
enum os_client_lock_type {
OSSVRSTAT_CLIENT_LOCK_TO_MAX_BLOCKS = 1,
OSSVRSTAT_CLIENT_LOCK_TO_NBLOCKS
};
enum os_client_state_type {
OSSVRSTAT_CLIENT_WAITING_MESSAGE,
OSSVRSTAT_CLIENT_EXECUTING_MESSAGE,
OSSVRSTAT_CLIENT_WAITING_RANGE_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_RANGE_WRITE_LOCK,
OSSVRSTAT_CLIENT_WAITING_SEGMENT_WRITE_LOCK,
OSSVRSTAT_CLIENT_DEAD,
OSSVRSTAT_CLIENT_WAITING_SEGMENT_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_DB_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_DB_WRITE_LOCK,
OSSVRSTAT_CLIENT_WAITING_CLUSTER_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_CLUSTER_WRITE_LOCK,
OSSVRSTAT_CLIENT_WAITING_CLUSTER_RANGE_READ_LOCK,
OSSVRSTAT_CLIENT_WAITING_CLUSTER_RANGE_WRITE_LOCK,
OSSVRSTAT_CLIENT_WAITING_WHILE_FREEZING_COHERENT_SET,
OSSVRSTAT_CLIENT_WAITING_FOR_CONFLICTING_UPDATE_COMMIT
};
Data in locking_start_sector and locking_for_n_sectors is valid only when
lock_state is OSSVRSTAT_CLIENT_STATE_WAITING_RANGE_READ_LOCK,
OSSVRSTAT_CLIENT_STATE_WAITING_RANGE_WRITE_LOCK, OSSVRSTAT_CLIENT_
WAITING_CLUSTER_RANGE_READ_LOCK, or OSSVRSTAT_CLIENT_WAITING_CLUSTER_
RANGE_WRITE_LOCK.
The class os_svr_stat_client_meters has the following public data members:
200
os_unsigned_int32
struct_version;
os_unsigned_int32
n_receive_msgs;
os_unsigned_int32
n_callback_msgs;
os_unsigned_int32
n_callback_sectors_requested;
os_unsigned_int32
n_callback_sectors_succeeded;
os_unsigned_int32
n_sectors_read;
os_unsigned_int32
n_sectors_written;
os_unsigned_int32
n_deadlocks;
os_unsigned_int32
n_lock_timeouts;
os_unsigned_int32
n_commit;
os_unsigned_int32
n_phase_2_commit;
os_unsigned_int32
n_readonly_commit;
os_unsigned_int32
n_abort;
C++ A P I Reference
Chapter 2: Class Library
os_unsigned_int32
n_phase_2_abort;
os_unsigned_int32
n_notifies_sent;
os_unsigned_int32
n_notifies_received;
os_unsigned_int32
n_lock_waits;
os_timesecs
total_lock_wait_time;
The class os_svr_stat_extension has the following public data members:
os_svr_log_stat_sample*
p_log_samples;
os_unsigned_int32
n_log_samples;
os_svr_stat_delayed_db_info* p_delayed_dbs;
os_unsigned_int32
n_delayed_dbs;
os_unsigned_int32
transaction_log_aio_thread_serial_number;
The class os_svr_log_stat_sample has the following public data members:
Release 6.3
os_unsigned_int32
struct_version;
os_boolean
valid;
os_unsigned_int32
n_minutes;
os_unsigned_int32
log_size;
os_unsigned_int32
data_segment_size;
os_unsigned_int32
record_segments_size;
os_unsigned_int32
log_free_size;
os_unsigned_int32
data_segment_active_size;
os_unsigned_int32
data_segment_min_active_size;
os_unsigned_int32
data_segment_max_active_size;
os_unsigned_int32
current_record_segment_active_size;
os_unsigned_int32
current_record_segment_min_active_size;
os_unsigned_int32
current_record_segment_max_active_size;
os_unsigned_int32
current_record_segment_live_size;
os_unsigned_int32
current_record_segment_min_live_size;
os_unsigned_int32
current_record_segment_max_live_size;
os_unsigned_int32
previous_record_segment_active_size;
os_unsigned_int32
previous_record_segment_min_active_size;
os_unsigned_int32
previous_record_segment_max_active_size;
os_unsigned_int32
previous_record_segment_live_size;
os_unsigned_int32
previous_record_segment_min_live_size;
os_unsigned_int32
previous_record_segment_max_live_size;
os_unsigned_int32
delayed_data_size;
os_unsigned_int32
delayed_data_min_size;
os_unsigned_int32
delayed_data_max_size;
os_unsigned_int32
n_garbage_collections;
os_unsigned_int32
n_trivial_garbage_collections;
os_unsigned_int32
n_grow_because_not_enough_time;
201
os_dbutil
Example
os_unsigned_int32
n_grow_because_not_enough_transactions;
os_unsigned_int32
n_grow_because_not_enough_time_and_transactions;
os_unsigned_int32
n_grow_because_not_enough_data;
os_unsigned_int32
n_grow_because_mvcc;
os_unsigned_int32
n_grow_because_unfinished_transactions;
os_unsigned_int32
n_grow_because_unpropagated_data;
os_db_statistic_info
log_io_stats;
The following code example calls the os_dbutil::svr_stat() function to retrieve
server-use meters. After the call returns, the code reads the number of notifications
sent and received by the server:
// construct an os_svr_stat object to pass as an argument
// to os_dbutil::svr_stat()
os_svr_stat svrstat;
os_dbutil::svr_stat(db->get_host_name(), // name of server
os_svr_stat::get_svr_meter_samples, // get server meters
, &svrstat); // os_svr_stat object for svr_stat() to fill
// retrieve metrics from first element of svr_meter_samples
// array, allocated by the call to os_dbutil::svr_stat()
os_unsigned_int32 n_sent =
svrstat.svr_meter_samples->n_notifies_sent;
os_unsigned_int32 n_received =
svrstat.svr_meter_samples->n_notifies_received;
// svrstat and its subobjects are deallocated by the
// ~os_svr_stat() destructor when svrstat goes out of scope
For information about using an ObjectStore utility to get information about a server,
see ossvrstat in Managing ObjectStore.
202
C++ A P I Reference
Chapter 2: Class Library
os_deadlock_exception
Instances of this class contain information on the circumstances that prevent
deadlocked processes from obtaining a transaction lock. An exception of this type
can be signaled by processes that attempt to obtain a lock that conflicts with a lock
held by a second process at the same time the second process is waiting for a lock
held by the first process. This situation can occur with more than two processes, each
waiting for a lock held by the next.
os_deadlock_exception is a dynamically allocated descendant of err_deadlock.
An exception handler that handles err_deadlock will normally receive an instance
of os_deadlock_exception.
Example
Here is a simple example of handling os_deadlock_exception:
TIX_HANDLE(err_deadlock) {
// application code
} TIX_EXCEPTION {
os_deadlock_exception* e =
\
tix_handler::get_exception()->get_os_deadlock_exception();
if (e)
{
os_char_p* deadlocked_applications =
e->get_application_names();
\
for (os_int32 i = 0; i<e->number_of_blockers(); i++)
printf("deadlocked with %s\n",
\
deadlocked_applications[i]);
e->release_pointer();
}
} TIX_END_HANDLE
See Chapter 6, Exception Handling in the C++ A P I User Guide for more information
on handling exceptions.
Type definitions
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.
os_deadlock_exception::get_application_names()
os_char_p* get_application_names( );
Returns an array of strings naming the deadlocked applications. This array is parallel
to the arrays returned by get_hostnames( ) and get_pids( ); that is, the ith element
of get_application_names( ) contains information about the same process as the
ith elements of get_hostnames( ) and get_pids( ). The member function number_
of_blockers( ) returns the number of elements in these arrays. Deleting the os_
deadlock_exception deallocates the arrays.
Release 6.3
203
os_deadlock_exception
os_deadlock_exception::get_fault_addr()
void* get_fault_addr( );
Returns the address on which ObjectStore faulted, causing the database access
leading to the deadlock.
os_deadlock_exception::get_hostnames()
os_char_p* get_hostnames( );
Returns an array of strings naming the host machines running the deadlocked
applications. This array is parallel to the arrays returned by get_application_
names( ) and get_pids( ); that is, the ith element of get_hostnames( ) contains
information about the same process as the ith elements of get_application_
names( ) and get_pids( ). The member function number_of_blockers( ) returns
the number of elements in these arrays. Deleting the os_deadlock_exception
deallocates the arrays.
os_deadlock_exception::get_lock_type()
os_int32 get_lock_type( );
Returns a value (os_read_lock or os_write_lock) indicating the type of lock
ObjectStore was requesting when the deadlock occurred. This will always be os_
write_lock.
os_deadlock_exception::get_pids()
os_unsigned_int32* get_pids( );
Returns an array of integers indicating the process IDs of the processes that are
deadlocked. This array is parallel to the arrays returned by get_application_
names( ) and get_hostnames( ); that is, the ith element of get_pids( ) contains
information about the same process as the ith elements of get_application_
names( ) and get_hostnames( ). The member function number_of_blockers( )
returns the number of elements in these arrays. Deleting the os_deadlock_
exception deallocates the arrays.
os_deadlock_exception::number_of_blockers()
os_int32 number_of_blockers( );
Returns the number of processes that are deadlocked, not counting the current
process.
204
C++ A P I Reference
Chapter 2: Class Library
os_DLL_finder
This class can be used to create a DLL identifier prefix. A prefix before a colon in a
DLL identifier string maps to a DLL finder subclass.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/client/dll_fndr.hh>.
os_DLL_finder::equal_DLL_identifiers()
static os_boolean equal_DLL_identifiers(
const char* id1, const char* id2
);
Compares two DLL identifier strings and returns nonzero (true) if the identifier
strings are equivalent.
os_DLL_finder::equal_DLL_identifiers_same_prefix()
virtual os_boolean equal_DLL_identifiers_same_prefix(
const char* id1,
const char* id2) = 0
;
Each subclass of os_DLL_finder must provide an implementation of equal_DLL_
identifiers_same_prefix() that compares two DLL identifiers that are both
implemented by this finder and returns true if they are equal.
os_DLL_finder::get()
static os_DLL_finder* get(const char* DLL_identifier);
Gets the finder for the specified DLL_identifier’s prefix or returns NULL if none is
registered.
os_DLL_finder::load_DLL()
virtual os_DLL_handle load_DLL(
const char* DLL_identifier,
os_boolean error_if_not_found) = 0
;
Each subclass of os_DLL_finder must provide an implementation of load_DLL()
that interprets the suffix part of the DLL identifier and calls the appropriate
operating system API (or calls another os_DLL_finder) to load the DLL.
os_DLL_finder::register_()
void register_(const char* prefix);
Registers this as the finder for DLL identifiers with the given prefix.
os_DLL_finder::unregister()
void unregister(const char* prefix);
Unregisters a DLL finder. It is no longer the finder for DLL identifiers with the given
prefix.
Release 6.3
205
os_DLL_schema_info
os_DLL_schema_info
This class provides access to information in a DLL about the component schema,
including (for example) the path name of the schema database, DLL identifiers, and
pointers to vtbls. Its base class is os_schema_info; for more information, see os_
schema_info on page 350.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/nreloc/schftyps.hh>.
os_DLL_schema_info::add_DLL_identifier()
void add_DLL_identifier(const char* id);
Adds the specified DLL identifier to the set of DLL identifiers of the os_DLL_
schema_info. This function can be called before os_DLL_schema_info::DLL_
loaded() if the DLL identifier is determined independently of the schema.
This can be used, for example, in a case in which one developer hands off the schema
database, schema file, and other object files to another developer who incorporates
these into a DLL that he builds. The schema starts with a dummy DLL identifier to
make it a component schema and has the real identifiers added by the second
developer.
The add_DLL_identifier() function allocates a small amount of memory that is
never freed. The amount of memory is proportional to the total number of DLL
identifiers in the os_DLL_schema_info. It also retains a pointer to the id argument
indefinitely.
os_DLL_schema_info::DLL_loaded()
os_schema_handle& DLL_loaded(
os_boolean load_DLL_schema_for_current_session_only = 0
);
Notifies ObjectStore that a DLL has been loaded and that the component schema
must be loaded and merged into the process’s complete program schema. The this
argument identifies the schema to be loaded. Typically the this argument is an os_
DLL_schema_info structure generated by ossg in the DLL that is calling DLL_
loaded(). Typically the call is in the DLL’s initialization function.
If load_DLL_schema_for_current_session_only is nonzero, the component
schema is loaded in the current session; otherwise, the component schema is marked
as global so that other sessions will automatically load it without calling this
function. If this function is called outside a session, the component schema is marked
as global regardless of the value of the boolean argument. This function returns 0 if
called outside a session.
Upon notification, one of the following then occurs:
• If ObjectStore is not yet initialized or there is no current transaction, this function
saves the arguments for later processing when the first database is put in use by
206
C++ A P I Reference
Chapter 2: Class Library
the next transaction. The arguments are saved in the form of an os_schema_
handle object that is not fully initialized.
• If the component schema is already loaded, this function returns its os_schema_
handle.
• For all other cases, os_DLL_schema_info::DLL_loaded() finds the schema and
loads it.
Aborting a transaction does not roll back os_DLL_schema_info::DLL_loaded().
The returned os_schema_handle represents the component schema that was loaded
or is to be loaded.
Debugging
Delayed loading of a component schema after calling os_DLL_schema_info::DLL_
loaded() can raise exceptions. It can be difficult to debug these because they occur
later than the program action that loaded the DLL, but the error message should
always include a DLL identifier of the DLL.
One way to debug such a program is to start a transaction and put a database in use
to force deferred loading to happen:
os_schema_handle& DLL_loaded(
const char* explicit_schema_database_path
);
The explicit_schema_database_path argument allows the file path name of the
component schema database to be passed in, overriding the path name in the os_
DLL_schema_info. This calls os_schema_handle::set_schema_database_
pathname() and then calls the no-argument overloading of DLL_loaded(), as
described above. See also os_schema_handle::set_schema_database_
pathname() on page 349.
os_DLL_schema_info::DLL_unloaded()
void DLL_unloaded();
Uses the os_DLL_schema_info to locate a loaded os_schema_handle and calls os_
schema_handle::DLL_unloaded().
An exception is thrown if no corresponding os_schema_handle currently exists.
Release 6.3
207
os_Dumper_reference
os_Dumper_reference
Instances of the class os_Dumper_reference can be used as substitutes for pointers
to predump or postload objects. Given a reference to a predump object, you can
retrieve a reference to the corresponding postload object; see os_Database_
table::find_reference() on page 176. Dumper references are required as
arguments to certain functions that your specializations call; see, for example, os_
Database_table::insert() on page 176.
As with a pointer, after the object referred to by a dumper reference is deleted, use
of the reference accesses arbitrary data and might cause a segmentation violation.
For information about constructing or setting a reference, see
• os_Dumper_reference::os_Dumper_reference() on page 210
• os_Dumper_reference::operator =() on page 209
For information about resolving a reference, see
• os_Dumper_reference::resolve() on page 210
• os_Dumper_reference::resolve() on page 210
os_Dumper_reference::get_database()
os_database* get_database () const;
Returns the database containing the referent of this reference.
os_Dumper_reference::get_database_number()
os_unsigned_int32 get_database_number () const;
Returns the database table number of the database containing the referent of this
reference.
os_Dumper_reference::get_offset()
os_unsigned_int32 get_offset () const;
Returns the offset of the referent of this reference within its segment.
os_Dumper_reference::get_segment()
os_segment* get_segment () const;
Returns the segment containing the referent of this reference.
os_Dumper_reference::get_segment_number()
os_unsigned_int32 get_segment_number () const;
Returns the segment number of the segment containing the referent of this reference.
os_Dumper_reference::get_string()
const char* get_string () const;
208
C++ A P I Reference
Chapter 2: Class Library
Returns the reference's value as an encoded string.
os_Dumper_reference::is_valid()
os_boolean is_valid () const;
Returns nonzero if this is completely valid; returns 0 otherwise.
os_Dumper_reference::operator void*()
operator void*() const;
Returns the pointer for which the specified reference is a substitute.
os_Dumper_reference::operator =()
os_Dumper_reference& operator = (const os_Dumper_reference&);
Establishes the referent of the right operand as the referent of the left operand.
Overloadings
The following overloading is supported:
os_Dumper_reference& operator = (void* obj);
Establishes the object pointed to by the right operand as the referent of the left
operand.
os_Dumper_reference::operator ==()
os_boolean operator == (const os_Dumper_reference&) const;
Returns 1 if the arguments have the same referent; returns 0 otherwise.
os_Dumper_reference::operator <()
os_boolean operator < (const os_Dumper_reference&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
argument precedes the referent of the second, and a return value of 0 indicates that
it does not. Otherwise, the results are undefined.
os_Dumper_reference::operator >()
os_boolean operator > (const os_Dumper_reference&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
argument follows the referent of the second, and a return value of 0 indicates that it
does not. Otherwise, the results are undefined.
os_Dumper_reference::operator !=()
os_boolean operator != (const os_Dumper_reference&) const;
Returns 1 if the arguments have different referents; returns 0 otherwise.
Release 6.3
209
os_Dumper_reference
os_Dumper_reference::operator >=()
os_boolean operator >= (const os_Dumper_reference&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
argument follows or is the same as the referent of the second, and a return value of
0 indicates that it does not. Otherwise, the results are undefined.
os_Dumper_reference::operator <=()
os_boolean operator <= (const os_Dumper_reference&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
argument precedes or is the same as the referent of the second, and a return value of
0 indicates that it does not. Otherwise, the results are undefined.
os_Dumper_reference::operator !()
os_boolean operator ! () const;
Returns nonzero if the reference is NULL, that is, has no current referent.
os_Dumper_reference::os_Dumper_reference()
os_Dumper_reference (const void*);
Constructs a reference to substitute for the specified void*.
Overloadings
The following overloadings are supported:
os_Dumper_reference
os_unsigned_int32
os_unsigned_int32
os_unsigned_int32
);
(
database_number,
seg_num,
offset
Constructs a reference to the object with the specified database number, segment
number, and offset.
os_Dumper_reference (const os_Dumper_reference&);
Constructs a reference with the same referent as the specified reference.
os_Dumper_reference ();
Constructs a null reference, that is, a reference without a current referent. See os_
Dumper_reference::operator =() on page 209.
os_Dumper_reference::resolve()
void* resolve() const;
Returns the valid void* for which the specified reference is a substitute.
210
C++ A P I Reference
Chapter 2: Class Library
os_Dumper_specialization
This class is part of the dump/load facility and is used by implementers of
customized dump and load utilities. It is an abstract base class that specifies the
protocol for a user-defined class derived from it. The derived class handles the
generation of object forms.
See Chapter 6, Dump/Load Facility, in the Advanced C++ A P I User Guide for
information on customizing the dumping and loading of ObjectStore databases.
This section describes the behavior, if implemented correctly, of the members of os_
Dumper_specialization that can be implemented in the derived class. The class
type_dumper is a class that is derived from os_Dumper_specialization for
customization of the dumping of the type type.
os_Dumper_specialization::get_specialization_name()
char* type_Dumper_specialization::get_specialization_name(
const os_class_type& class_type
) const;
Returns 0 or the name of the type whose dumper should be used for instances of
class_type, where class_type represents a subtype of type. If 0 is returned, it
indicates that the dumper for class_type should be used.
Deleting the returned string is the responsibility of the caller of this function.
See Implementing get_specialization_name() in the Advanced C++ A P I User Guide for
information on implementing this function.
os_Dumper_specialization::operator ()()
void type_Dumper_specialization::operator () (
const os_class_type& actual_class,
void* obj
);
An object form has the following structure:
id (Type) value
This function generates the value portion of the object form. The functions that
generate the rest of the object form are internal to the dump/load facility.
The function also inserts a fixup dumper into the database table, which causes the
dumper to generate a fixup form for object after generating all the object forms.
(When a load processes this kind of fixup form for object, it adjusts all pointers and
C++ references in object so that they refer to the appropriate newly loaded
referent.)
See Implementing operator ()() in the Advanced C++ A P I User Guide for information
on implementing this function.
Overloadings
The following overloading is supported:
void type_Dumper_specialization::operator () (
Release 6.3
211
os_Dumper_specialization
const os_class_type& actual_class,
void* obj,
unsigned number_of_elements
);
Same as the first overloading, but for an array of instances of type.
os_Dumper_specialization::should_use_default_constructor()
os_boolean should_use_default_constructor(
const os_class_type& class_type
) const;
When you customize the dump and load of a type, you supply code to create
instances of the type during a load. This code is used for all nonembedded instances
of the type. But for an instance of the type embedded in a noncustomized type, the
loader calls the customized type’s constructor automatically, using code generated
by the dumper.
This function returns 0 if the dumper-generated code calls a no-argument
constructor. The function returns 1 if the dumper-generated code calls the special
loader constructor, type(type_data&).
See Implementing should_use_default_constructor() in the Advanced C++ A P I User
Guide for information on implementing this function.
212
C++ A P I Reference
Chapter 2: Class Library
os_dynamic_extent
An instance of this class can be used to create an extended collection of all objects of
a particular type, regardless of the segments that the objects reside in. All objects are
retrieved in an arbitrary order that is stable across traversals of the segments, if no
objects are created or deleted from the segment and no reorganization is performed
(using schema evolution or compaction). This class is derived from os_Collection.
The os_dynamic_extent class is useful for joining together multiple collections of
the same object type into a new collection. The new collection is created dynamically,
which results in no additional storage consumption.
By default, os_dynamic_extent does not search subclasses when the requested
object type is a class type. To enable this behavior, set the argument include_
subclasses to true. When this behavior is enabled, os_dynamic_extent searches
all classes that the requested class type is derived from.
You iterate over the os_dynamic_extent collection by creating an associated
instance of os_cursor. Only the os_cursor::more(), os_cursor::first(), and
os_cursor::next() functions are supported by os_dynamic_extent. You can
create an index for the os_dynamic_extent collection by calling add_index();
however, creating an index requires additional storage.
os_dynamic_extent::insert()
void insert(const void*);
Adds the specified void* to the index for the current os_dynamic_extent
collection. You must first create an index by calling os_collection::add_index().
For more information, see the C++ Collections Guide and Reference.
os_dynamic_extent::os_dynamic_extent()
os_dynamic_extent(
os_database* db,
os_typespec* typespec,
os_boolean include_subclasses = 0
);
Constructs an os_dynamic_extent that associates all objects of os_typespec that
exist in the specified os_database. This constructor should be used only for
transient instances of os_dynamic_extent.
By default, os_dynamic_extent does not search subclasses when the requested
object type is a class type. Set the argument include_subclasses to true to enable
os_dynamic_extent to search all classes that the requested class type is derived
from.
Overloadings
The following overloadings are supported:
os_dynamic_extent(
os_typespec* typespec,
os_boolean options = os_dynamic_extent::all_segments,
os_boolean include_subclasses = 0
Release 6.3
213
os_dynamic_extent
);
Constructs an os_dynamic_extent that associates all objects of os_typespec. This
constructor assumes that the os_dynamic_extent is persistent and searches the
database in which the os_dynamic_extent resides. If the option is os_dynamic_
extent::all_segments, all segments are searched. The alternative option is os_
dynamic_extent::of_segment, which searches only the segment in which the os_
dynamic_extent is allocated.
By default, os_dynamic_extent does not search subclasses when the requested
object type is a class type. Set the argument include_subclasses to true to enable
os_dynamic_extent to search all classes that the requested class type is derived
from.
os_dynamic_extent(
os_database* db,
os_typespec* typespec,
os_segment* seg,
os_boolean include_subclasses = 0
);
Constructs an os_dynamic_extent that associates only those objects of os_
typespec that exist in the specified os_database and os_segment. This constructor
should be used only for transient instances of os_dynamic_extent.
By default, os_dynamic_extent does not search subclasses when the requested
object type is a class type. Set the argument include_subclasses to true to enable
os_dynamic_extent to search all classes that the requested class type is derived
from.
os_dynamic_extent::~os_dynamic_extent()
~os_dynamic_extent();
Performs internal maintenance associated with os_dynamic_extent deallocation.
os_dynamic_extent::remove()
os_int32 remove(const void*);
Removes the specified void* from the os_dynamic_extent collection index.
If the index is ordered, the first occurrence of the specified void* is removed.
Returns a nonzero os_int32 if an element was removed; returns 0 otherwise.
214
C++ A P I Reference
Chapter 2: Class Library
os_enum_type
class os_enum_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++
enumeration type. This class is derived from os_type.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_enum_type::create()
static os_enum_type& create(
const char* name,
os_List<os_enumerator_literal*>&
);
Creates an instance of os_enum_type named name. The specified list contains the
enumerators of the created enumeration type.
os_enum_type::get_enumerator()
const os_enumerator_literal* get_enumerator(os_int32) const;
Returns the enumerator that names the specified integer. Returns 0 if there is no
enumerator with the specified value. If there is more than one enumerator with the
specified value, the first one is returned.
os_enum_type::get_enumerators()
os_List<const os_enumerator_literal*> get_enumerators( ) const;
Returns a list, in declaration order, of the enumerator literals defined by the
enumeration.
os_enum_type::get_name()
const char* get_name( ) const;
Returns the name of the specified enumeration. A zero-length string is returned for
an anonymous enumeration.
os_enum_type::get_pragmas()
os_List<os_pragma*> get_pragmas( ) const;
Returns the pragmas associated with the specified enumeration.
Release 6.3
215
os_enum_type
os_enum_type::get_source_position()
void get_source_position (
const char*& file,
os_unsigned_int32& line
) const;
Returns the source position associated with the specified enumeration.
os_enum_type::set_enumerators()
void set_enumerators(os_List<os_enumerator_literal*>&);
Specifies, in declaration order, the enumerator literals defined by the specified
enumeration.
os_enum_type::set_name()
void set_name(const char*);
Sets the name of the specified enumeration.
os_enum_type::set_pragmas()
void set_pragmas(os_List<os_pragma*>);
Sets the pragmas associated with the specified enumeration.
os_enum_type::set_source_position()
void set_source_position(
const char* file,
os_unsigned_int32 line
);
Sets the source position associated with the specified enumeration.
216
C++ A P I Reference
Chapter 2: Class Library
os_enumerator_literal
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++
enumerator.
Type definitions
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.
os_enumerator_literal::create()
static os_enumerator_literal& create(const char*, os_int32);
Creates an os_enumerator_literal of the specified name and value.
os_enumerator_literal::get_name()
const char* get_name( ) const;
Returns the name of the specified enumerator.
os_enumerator_literal::get_value()
os_int32 get_value( ) const;
Returns the integer value of the specified enumerator.
os_enumerator_literal::set_name()
void set_name(const char*);
Sets the name of the specified enumerator.
os_enumerator_literal::set_value()
void set_value(os_int32);
Sets the integer value of the specified enumerator.
Release 6.3
217
os_evolve_subtype_fun_binding
os_evolve_subtype_fun_binding
Instances of this class represent an association between a class and a reclassifier
function. Instances of os_evolve_subtype_fun_binding are used as arguments to
os_schema_evolution::augment_subtype_selectors( ). Instances should be
allocated in transient memory only.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/schmevol.hh>.
os_evolve_subtype_fun_binding::os_evolve_subtype_fun_
binding()
os_evolve_subtype_fun_binding(
char* class_name,
char* (*func)(const os_typed_pointer_void&)
);
Associates the class named class_name with the function func.
218
C++ A P I Reference
Chapter 2: Class Library
os_export_id
class os_export_id
Instances of this class are used internally by ObjectStore in connection with segment
reference policies. See os_database::create_segment() on page 152.
os_export_id::create()
static os_export_id create(os_unsigned_int32);
Creates an export ID from the value returned by os_export_id::get_value().
os_export_id::get_value()
os_unsigned_int32 get_value() const;
Returns an integer representation of the this export ID.
os_export_id::is_null()
os_boolean is_null() const;
Returns a nonzero value if the this export ID is a null export ID; returns 0 otherwise.
os_export_id::operator ==()
os_boolean operator==(os_export_id const&) const;
If the operands are IDs for objects in the same segment, this function returns a
nonzero value if and only if the operands are IDs for the same object or are both the
null export ID (see os_export_id::is_null() on page 219).
The function might return a nonzero value if the operands are IDs for objects in
different segments.
Release 6.3
219
os_export_id_cursor
os_export_id_cursor
An export ID cursor allows retrieval of the export IDs of all exported objects in a
specified segment. The ordering used is arbitrary but stable across traversals in the
absence of additions, deletions, or reorganization.
os_export_id_cursor::get_current()
os_export_id get_current() const;
Returns the export ID at which the cursor is currently positioned. If the cursor is
positioned before the first export ID or after the last export ID, returns the null export
ID (see os_export_id::is_null() on page 219).
os_export_id_cursor::next()
os_export_id next();
Advances the cursor to the next export ID in the cursor’s associated segment.
Returns the export ID at which it is positioned subsequent to being advanced. If there
is no next export ID, positions the cursor immediately after the last export ID and
returns the null export ID (see os_export_id::is_null() on page 219).
os_export_id_cursor::os_export_id_cursor()
os_export_id_cursor(
os_segment* seg,
os_unsigned_int32 max_n_ids_at_a_time = 100
);
Constructs a cursor suitable for retrieving the export IDs of all exported objects in the
segment seg. The newly constructed cursor is positioned immediately before the
first export ID in the segment.
The max_n_ids_at_a_time argument is the batch size for fetching export IDs from
the table of IDs for the cursor’s associated segment. If an exported object is deleted
after its export ID has been fetched from the table, the ID is visited by the cursor, even
though it is no longer valid. If this is a potential problem, you can protect against this
either by specifying a batch size of 1 or by catching the err_invalid_export_id
exception when attempting to resolve the export ID. A batch size larger than 1 can
increase the efficiency of traversals performed with the cursor.
220
C++ A P I Reference
Chapter 2: Class Library
os_export_id_cursor::reset()
void reset();
Positions the cursor immediately before the first export ID in the cursor’s associated
segment.
Overloadings
The following overloadings are supported:
void reset(os_export_id const& export_id);
Positions the cursor at the specified export ID.
void reset(os_segment* seg);
Positions the cursor at the first export ID in the specified segment.
os_export_id_cursor::~os_export_id_cursor()
~os_export_id_cursor();
Frees internally used memory associated with the this cursor.
Release 6.3
221
os_failover_server
os_failover_server
class os_failover_server : public os_server
This class is derived from os_server.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh> followed by
<ostore/coll.hh> (if collections are used).
See Managing ObjectStore for more information on failover.
os_failover_server::get_logical_server_hostname()
char* get_logical_server_hostname() const;
Returns the logical name of a failover ObjectStore server. A failover server should
always be referred to by its logical server name.
The caller should delete the returned value.
os_failover_server::get_online_server_hostname()
char* get_online_server_hostname() const;
Returns the name of the ObjectStore server that the client is currently connected to
— the logical server, the alternative server, or the empty string if there is no
connection.
The caller should delete the returned value.
os_failover_server::get_reconnect_retry_interval()
os_unsigned_int32 get_reconnect_retry_interval() const;
Returns the retry interval, which determines how often ObjectStore should ping the
servers of a failover server pair while attempting to reconnect to them.
os_failover_server::get_reconnect_timeout()
os_unsigned_int32 get_reconnect_timeout() const;
Returns the maximum amount of time that a client application attempts to reconnect
to a broken failover server connection.
When the timeout is reached, the exception err_broken_failover_server_
connection is signaled.
222
C++ A P I Reference
Chapter 2: Class Library
os_failover_server::set_reconnect_timeout_and_interval()
os_boolean set_reconnect_timeout_and_interval(
os_unsigned_int32 total_timeout_secs,
os_unsigned_int32 interval_secs
);
Sets the total amount of time to try to reconnect a broken connection to a failover
server. The interval_secs argument is used to control how frequently the servers
of a failover server pair are pinged to see whether they are available.
Returns nonzero (true) if the function has reset the reconnect timeout and the retry
interval with the given argument values.
The arguments are invalid if interval_secs is greater than total_timeout_secs
or if interval_secs equals 0 when total_timeout_secs is nonzero. If the
arguments are invalid, the function returns 0 (false) and does not change the
reconnect timeout or retry interval.
Release 6.3
223
os_field_member_variable
os_field_member_variable
class os_field_member_variable : public os_member_variable
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a bit-field
member. This class is derived from os_member_variable.
Type definitions
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_int8 is defined as an
unsigned 8-bit integer type.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_field_member_variable::create()
static os_field_member_variable& create(
const char* name,
os_type* var_type,
os_unsigned_int8 size_in_bits
);
Creates an os_field_member_variable of the specified name, var_type, and size_
in_bits.
os_field_member_variable::get_offset()
void get_offset(
os_unsigned_int32& bytes, os_unsigned_int8& bits
) const;
Returns the offset in bytes and bits to the specified bit field.
os_field_member_variable::get_size()
os_unsigned_int8 get_size( ) const;
Returns the size in bits of the specified bit field.
os_field_member_variable::set_size()
void set_size(os_unsigned_int8 size_in_bits);
Sets the size in bits of the specified bit field.
224
C++ A P I Reference
Chapter 2: Class Library
os_Fixup_dumper
This class is part of the dump/load facility and is used by implementers of
customized dump and load utilities. It is an abstract base class that specifies the
protocol for a user-defined class derived from it. The derived class handles the
generation of fixup forms.
See Chapter 6, Dump/Load Facility, in the Advanced C++ A P I User Guide for
information on customizing the dumping and loading of ObjectStore databases.
This section describes the behavior, if implemented correctly, of the members of os_
Fixup_dumper that can be implemented in the derived class. It also describes some
members that are implemented only by the base class. The class type_fixup_dumper
is a class that is derived from os_Fixup_dumper for customization of the dumping
of the type type.
os_Fixup_dumper::dump_info()
void type_fixup_dumper::dump_info();
A fixup form has the following structure:
fixup id (Type) info
This function generates the info portion. The functions that generate the rest of the
fixup form are inherited from os_Fixup_dumper.
The info portion consists of ASCII from which a loader can reconstruct function
arguments. The arguments should be those required for recreation of the nonroot
portion of the object being fixed up.
See Implementing dump_info() in the Advanced C++ A P I User Guide for information
on implementing this function.
os_Fixup_dumper::duplicate()
Fixup& type_fixup_dumper::duplicate();
Allocates a copy of the this type_fixup_dumper in the specified segment. See
Implementing duplicate() in the Advanced C++ A P I User Guide for information on
implementing this function.
os_Fixup_dumper::get_number_elements()
unsigned get_number_elements () const;
If this is a fixup for an array, returns the number of elements to be fixed up. Returns
0 otherwise.
os_Fixup_dumper::get_object_to_fix()
os_Dumper_reference get_object_to_fix () const;
Returns a dumper reference to the object for which this dumps a fixup form.
Release 6.3
225
os_Fixup_dumper
os_Fixup_dumper::get_type()
os_type& get_type() const;
Returns a reference to an os_type that represents the type of the object for which
this is a fixup dumper.
Overloadings
The following overloadings are supported:
type_fixup_dumper::type_fixup_dumper (
os_Dumper_stream&,
os_Dumper&,
const os_class_type&,
const os_Dumper_reference object_to_fix,
unsigned number_of_elements = 0
);
Passes the arguments to the base type constructor:
os_Fixup_dumper (
os_Dumper_stream&,
os_Dumper&,
const os_class_type&,
const os_Dumper_reference object_to_fix,
unsigned number_of_elements = 0
);
Constructs a fixup dumper. The constructors for your customized fixup dumpers
pass arguments to this constructor.
See Implementing the Constructor in the Advanced C++ A P I User Guide for
information on implementing this function.
os_Fixup_dumper (const os_Fixup_dumper&);
Copy constructor.
os_Fixup_dumper::~os_Fixup_dumper()
virtual ~os_Fixup_dumper();
Virtual destructor.
226
C++ A P I Reference
Chapter 2: Class Library
os_function_type
class os_function_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ function
type. This class is derived from os_type.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_function_type::create()
static os_function_type& create(
os_arg_list_kind arg_list_kind,
os_List<os_type*>& args,
os_type* return_type
);
Creates an os_function_type. The type of the new function’s nth argument is the
nth element of args. The return type is return_type. The possible values of arg_
list_kind are os_function_type::Unknown, os_function_type::Variable, and
os_function_type::Known. See os_function_type::get_arg_list_kind() on
page 227.
os_function_type::equal_signature()
os_boolean equal_signature(
const os_function_type& other_func,
os_boolean check_return_type = 0
) const;
Returns nonzero (true) if the specified function types are equivalent. If check_
return_type is 0, returns nonzero if the arguments are the same.
os_function_type::get_arg_list()
os_list get_arg_list( ) const;
Returns a list of os_type*s, pointers to the argument types of the specified function
type. See os_function_type::get_arg_list_kind() on page 227.
os_function_type::get_arg_list_kind()
enum os_arg_list_kind {Unknown, Known, Variable};
os_arg_list_kind get_arg_list_kind( ) const;
Returns an enumerator indicating the type of argument list associated with the
specified function. os_function_type::Unknown indicates that the argument
profile is unknown; a call to os_function_type::get_arg_list( ) returns an
empty list. os_function_type::Variable indicates that the function accepts a
variable number of arguments; a call to os_function_type::get_arg_list( )
returns the list of known leading arguments. os_function_type::Known indicates
that the function takes a known fixed number of arguments; a call to os_function_
type::get_arg_list( ) returns the complete argument list.
Release 6.3
227
os_function_type
os_function_type::get_return_type()
os_type& get_return_type( ) const;
Returns the return type associated with the specified function.
os_function_type::set_arg_list()
void set_arg_list(os_List<os_type*>);
Specifies a list of os_type*s, pointers to the argument types of the specified function
type. See the member os_function_type::get_arg_list_kind() on page 227.
os_function_type::set_arg_list_kind()
void set_arg_list_kind(os_int32);
Specifies an enumerator indicating the type of argument list associated with the
specified function. os_function_type::Unknown indicates that the argument
profile is unknown. os_function_type::Variable indicates that the function
accepts a variable number of arguments. os_function_type::Known indicates that
the function takes a known fixed number of arguments.
os_function_type::set_return_type()
void set_return_type(os_type&);
Sets the return type associated with the specified function.
228
C++ A P I Reference
Chapter 2: Class Library
os_indirect_type
class os_indirect_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class is either an os_named_
indirect_type (typedef) or os_anonymous_indirect_type (a type with const or
volatile specifiers). This class is derived from os_class_type.
os_indirect_type::get_target_type()
const os_type& get_target_type( ) const;
Returns the type for which this is a typedef or that this qualifies with a const or
volatile specifier.
os_type& get_target_type( );
Returns the type for which this is a typedef or that this qualifies with a const or
volatile specifier.
os_indirect_type::set_target_type()
void set_target_type(os_type&);
Sets the type for which this is a typedef or that this qualifies with a const or
volatile specifier.
Release 6.3
229
os_instantiated_class_type
os_instantiated_class_type
class os_instantiated_class_type : public os_class_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents an instantiation of
a template class. This class is derived from os_class_type.
os_instantiated_class_type::create()
static os_instantiated_class_type& create(const char* name);
Creates an os_instantiated_class_type with the specified name.
Overloadings
The following overloading is supported:
static os_instantiated_class_type& create(
const char* name,
os_List<os_base_class*>&,
os_List<os_member*>&,
os_template_instantiation*,
os_boolean defines_virtual_functions
);
Creates an os_instantiated_class_type from the specified template instantiation
and with the specified name, base classes, and members.
os_instantiated_class_type::get_instantiation()
const os_template_instantiation& get_instantiation( ) const;
Returns a reference to a const os_template_instantiation that represents the
template instantiation resulting in this class.
Overloadings
The following overloading is supported:
os_template_instantiation& get_instantiation( );
Returns a reference to a non-const os_template_instantiation that represents
the template instantiation resulting in this class.
os_instantiated_class_type::set_instantiation()
void set_instantiation(os_template_instantiation&);
Sets the os_template_instantiation for the specified os_instantiated_class_
type.
230
C++ A P I Reference
Chapter 2: Class Library
os_int64
Instances of the class os_int64 represent signed 64-bit integers on any platform; the
underlying implementation varies from platform to platform. Members of this class
provide all the standard C++ operators for manipulating integers. For information
about unsigned 64-bit integers, see os_unsigned_int64 on page 446.
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_int64::os_int64()
os_int64(os_int64 num);
Constructs a copy of num.
Overloadings
The following overloadings are supported:
os_int64(os_platform_int64 num);
Constructs an instance of os_int64 based on the value of num. The os_platform_
int64 argument is an ObjectStore type definition for native 64-bit integer data types,
if there is one.
os_int64(os_int32 num);
Constructs an instance of os_int64 based on the value of num, a 32-bit integer.
os_int64(os_int32 high, os_int32 low);
Constructs an instance of os_int64 based on the values of high and low, where high
represents the upper 32 bits and low represents the lower 32 bits.
os_int64::get_high()
os_int32 get_low( );
Returns a 32-bit integer based on the upper 32 bits of the value of the object.
os_int64::get_low()
os_int32 get_low( );
Returns a 32-bit integer based on the lower 32 bits of the value of the object.
os_int64::sprint()
void sprint(char* result, os_int32 base = 10) const;
Converts the value of the object into a formatted string at the specified base and
writes the string to result. The base argument can be either 10 or 16; the default is
10.
Release 6.3
231
os_integral_type
os_integral_type
class os_integral_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ integer
type. This class is derived from os_type. Performing os_type::get_kind( ) on an
os_integral_type returns one of the following enumerators:
• os_type::Signed_char
• os_type::Unsigned_char
• os_type::Signed_short
• os_type::Unsigned_short
• os_type::Integer
• os_type::Unsigned_integer
• os_type::Signed_long
• os_type::Unsigned_long
Type definitions
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.
os_integral_type::create()
static os_integral_type& create(const char*);
Creates an os_integral_type representing the type with the specified name.
os_integral_type::create_defaulted_char()
static os_integral_type& create_defaulted_char(
os_boolean signed
);
Creates an os_integral_type representing the type char.
os_integral_type::create_int()
static os_integral_type& create_int(os_boolean signed_int);
Creates an os_integral_type. If the signed_int argument is true, the type is int.
If the signed_int argument is false, the type is unsigned int.
os_integral_type::create_long()
static os_integral_type& create_long(os_boolean signed_long);
Creates an os_integral_type. If the signed_long argument is true, the type is
long. If the signed_long argument is false, the type is unsigned long.
232
C++ A P I Reference
Chapter 2: Class Library
os_integral_type::create_short()
static os_integral_type& create_short(
os_boolean signed_short
);
Creates an os_integral_type. If the signed_short argument is true, the type is
short. If the signed_short argument is false, the type is unsigned short.
os_integral_type::create_signed_char()
static os_integral_type& create_signed_char( );
Creates an os_integral_type representing the type signed char.
os_integral_type::create_unsigned_char()
static os_integral_type& create_unsigned_char( );
Creates an os_integral_type representing the type unsigned char.
os_integral_type::is_signed()
os_boolean is_signed( ) const;
Returns 1 if and only if the specified object represents a signed type.
Release 6.3
233
os_literal
os_literal
class os_literal
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent literals that designate
values. They can be used as actual parameters of class templates.
os_literal::create_char()
static os_literal& create_char(char);
Creates a literal representing the specified char.
os_literal::create_enum_literal()
static os_literal& create_enum_literal(
os_enumerator_literal&
);
Creates a literal representing the specified enumerator.
os_literal::create_pointer_literal()
static os_literal& create_pointer_literal(
os_pointer_literal&
);
Creates a literal representing the specified pointer.
os_literal::create_signed_char()
static os_literal& create_signed_char(signed char);
Creates a literal representing the specified signed char.
os_literal::create_signed_int()
static os_literal& create_signed_int(signed int);
Creates a literal representing the specified signed int.
os_literal::create_signed_long()
static os_literal& create_signed_long(signed long);
Creates a literal representing the specified signed long.
os_literal::create_signed_short()
static os_literal& create_signed_short(signed short);
Creates a literal representing the specified signed short.
os_literal::create_unsigned_char()
static os_literal& create_unsigned_char(unsigned char);
Creates a literal representing the specified unsigned char.
234
C++ A P I Reference
Chapter 2: Class Library
os_literal::create_unsigned_int()
static os_literal& create_unsigned_int(unsigned int);
Creates a literal representing the specified unsigned int.
os_literal::create_unsigned_long()
static os_literal& create_unsigned_long(unsigned long);
Creates a literal representing the specified unsigned long.
os_literal::create_unsigned_short()
static os_literal& create_unsigned_short(unsigned short);
Creates a literal representing the specified unsigned short.
os_literal::create_wchar_t()
static os_literal& create_wchar_t(wchar_t);
Creates a literal representing the specified wchar_t.
os_literal::get_char_value()
char get_char_value( ) const;
Returns the value designated by the specified literal.
os_literal::get_enum_literal()
const os_enumerator_literal& get_enum_literal( ) const;
Returns a reference to the const os_enumerator_literal designated by the
specified literal.
Overloadings
The following overloading is supported:
os_enumerator_literal& get_enum_literal( );
Returns a reference to the os_enumerator_literal designated by the specified
literal.
os_literal::get_kind()
enum os_literal_kind {
Enumerator_literal,
Function_literal,
Function_literal_template,
Unsigned_char_literal,
Signed_char_literal,
Unsigned_short_literal,
Signed_short_literal,
Integer_literal,
Unsigned_integer_literal,
Signed_long_literal,
Unsigned_long_literal,
Char_literal,
Pointer_literal,
Release 6.3
235
os_literal
Wchar_t_literal
};
os_literal_kind get_kind( ) const;
Returns an enumerator indicating the kind of the specified literal.
os_literal::get_pointer_literal()
const os_pointer_literal& get_pointer_literal( ) const;
Returns a reference to the const os_pointer_literal designated by the specified
literal.
Overloadings
The following overloading is supported:
os_pointer_literal& get_pointer_literal( );
Returns a reference to the os_pointer_literal designated by the specified literal.
os_literal::get_signed_integral_value()
long get_signed_integral_value( ) const;
Returns the value designated by the specified literal.
os_literal::get_type()
const os_type& get_type( ) const;
Returns the type of the value designated by the specified literal.
os_literal::get_unsigned_integral_value()
long get_unsigned_integral_value( ) const;
Returns the value designated by the specified literal.
os_literal::get_wchar_t_value()
wchar_t get_wchar_t_value( ) const;
Returns the value designated by the specified literal.
236
C++ A P I Reference
Chapter 2: Class Library
os_literal_template_actual_arg
class os_literal_template_actual_arg : public os_template_actual_arg
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent values that are actual
parameters of class templates.
os_literal_template_actual_arg::create()
static os_literal_template_actual_arg& create(os_literal*);
Creates an actual parameter consisting of the specified literal.
os_literal_template_actual_arg::get_literal()
const os_literal& get_type( ) const;
Returns a reference to a const literal, the literal of which the actual parameter
consists.
Overloadings
The following is the non-const overloading of this function:
os_literal& get_literal( );
Returns a reference to a non-const literal, the literal of which the actual parameter
consists.
os_literal_template_actual_arg::set_literal()
void set_literal(os_literal&);
Sets the literal of which the actual parameter consists.
Release 6.3
237
os_lock_timeout_exception
os_lock_timeout_exception
Instances of this class contain information on the circumstances preventing
acquisition of a lock within a specified timeout period. An exception of this type can
be signaled by processes that have called the set_readlock_timeout( ) or set_
writelock_timeout( ) member of os_segment, os_database, or objectstore. A
pointer to an instance of this class can be returned by objectstore::acquire_
lock( ).
os_lock_timeout_exception is a dynamically allocated descendant of err_lock_
timeout. An exception handler that handles err_lock_timeout will normally
receive an instance of os_lock_timeout_exception.
Example
Here is a simple example of handling os_lock_timeout_exception:
TIX_HANDLE(err_lock_timeout) {
// application code
} TIX_EXCEPTION {
os_lock_timeout_exception* e =
\
tix_handler::get_exception()->get_os_lock_timeout_
exception();
if (e)
{
os_char_p *timed_out_applications =
e->get_application_names();
\
for (os_int32 i = 0; i<e->number_of_blockers(); i++)
printf("locked with %s\n", timed_out_applications[i]);
e->release_pointer();
}
} TIX_END_HANDLE
See Chapter 6, Exception Handling in the C++ A P I User Guide for more information
on handling exceptions.
Type definitions
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.
os_lock_timeout_exception::get_application_names()
os_char_p* get_application_names( );
Returns an array of strings naming the applications preventing lock acquisition. This
array is parallel to the arrays returned by get_hostnames( ) and get_pids( ); that
is, the ith element of get_application_names( ) contains information about the
same process as the ith elements of get_hostnames( ) and get_pids( ). The member
function number_of_blockers( ) returns the number of elements in these arrays.
Deleting the os_lock_timeout_exception deallocates the arrays.
os_lock_timeout_exception::get_fault_addr()
void* get_fault_addr( );
238
C++ A P I Reference
Chapter 2: Class Library
Returns the address on which ObjectStore faulted, causing the database access
leading to the attempted lock acquisition.
os_lock_timeout_exception::get_hostnames()
os_char_p* get_hostnames( );
Returns an array of strings naming the host machines running the applications
preventing lock acquisition. This array is parallel to the arrays returned by get_
application_names( ) and get_pids( ); that is, the ith element of get_
hostnames( ) contains information about the same process as the ith elements of
get_application_names( ) and get_pids( ). The member function number_of_
blockers( ) returns the number of elements in these arrays. Deleting the os_lock_
timeout_exception deallocates the arrays.
os_lock_timeout_exception::get_lock_type()
os_int32 get_lock_type( );
Returns a value (os_read_lock or os_write_lock) indicating the type of lock
ObjectStore was requesting when the timeout occurred.
os_lock_timeout_exception::get_pids()
os_unsigned_int32* get_pids( );
Returns an array of integers indicating the process IDs of the processes preventing
lock acquisition. This array is parallel to the arrays returned by get_application_
names( ) and get_hostnames( ); that is, the ith element of get_pids( ) contains
information about the same process as the ith elements of get_application_
names( ) and get_hostnames( ). The member function number_of_blockers( )
returns the number of elements in these arrays. Deleting the os_lock_timeout_
exception deallocates the arrays.
os_lock_timeout_exception::number_of_blockers()
os_int32 number_of_blockers( );
Returns the number of processes preventing lock acquisition.
Release 6.3
239
os_member
os_member
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a class member.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_member::Access_modifier
This enumerator is a possible return value from os_member::get_kind( ),
indicating an access modification to an inherited member. See os_access_modifier
on page 97.
os_member::Field_variable
This enumerator is a possible return value from os_member::get_kind( ),
indicating a bit field. See os_instantiated_class_type on page 230.
os_member::Function
This enumerator is a possible return value from os_member::get_kind( ),
indicating a member function. See os_member_function on page 244.
os_member::get_access()
int get_access( ) const;
Returns one of the following enumerators describing the access to the specified
member:
• os_member::Private
• os_member::Protected
• os_member::Public
os_member::get_defining_class()
const os_class_type& get_defining_class( ) const;
Returns a reference to a const os_class_type, the type that defines the specified
member.
Overloading
The following overloading is supported:
os_class_type& get_defining_class( );
Returns a reference to a non-const os_class_type object.
os_member::get_kind()
int get_kind( ) const;
Returns an enumerator indicating the subtype of os_member of which the specified
object is a direct instance. The possible return values are os_member::Variable, os_
member::Function, os_member::Type, os_member::Access_modifier, os_
240
C++ A P I Reference
Chapter 2: Class Library
member::Field_variable, os_member::Namespace, and os_
member::Relationship.
os_member::is_unspecified()
os_boolean is_unspecified( ) const;
Returns nonzero (true) if and only if the specified os_member is the unspecified
member. Some os_member-valued attributes in the metaobject protocol are required
to have values in a consistent schema but might lack values in the transient schema,
before schema installation or evolution is performed. The get function for such an
attribute returns a reference to an os_member. The fact that a reference rather than a
pointer is returned indicates that the value is required in a consistent schema. In the
transient schema, if such an attribute lacks a value (because you have not yet
specified it), the get function returns the unspecified member. This is the only os_
member for which is_unspecified( ) returns nonzero.
os_member::Namespace
This enumerator is a possible return value from os_member::get_kind( ),
indicating a member function. See os_member_namespace on page 248.
os_member::operator const os_access_modifier&()
operator const os_access_modifier&( ) const;
Provides for safe casts from const os_member to const os_access_modifier&. If
the cast is not permissible, err_mop_illegal_cast is signaled.
os_member::operator const os_field_member_variable&()
operator const os_field_member_variable&( ) const;
Provides for safe casts from const os_member to const os_field_member_
variable&. If the cast is not permissible, err_mop_illegal_cast is signaled.
os_member::operator const os_member_function&()
operator const os_member_function&() const;
Provides for safe casts from const os_member to const os_member_function&. If
the cast is not permissible, err_mop_illegal_cast is signaled.
os_member::operator const os_member_type&()
operator const os_member_type&() const;
Provides for safe casts from const os_member to const os_member_type&. If the
cast is not permissible, err_mop_illegal_cast is signaled.
os_member::operator const os_member_variable&()
operator const os_member_variable&() const;
Provides for safe casts from const os_member to const os_member_variable&. If
the cast is not permissible, err_mop_illegal_cast is signaled.
Release 6.3
241
os_member
os_member::operator const os_relationship_member_
variable&()
operator const os_relationship_member_variable&() const;
Provides for safe casts from const os_member to const os_relationship_member_
variable&. If the cast is not permissible, err_mop_illegal_cast is signaled.
os_member::operator os_access_modifier&()
operator os_access_modifier&();
Provides for safe casts from os_member to os_access_modifier&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_member::operator os_field_member_variable&()
operator os_field_member_variable&( );
Provides for safe casts from os_member to os_field_member_variable&. If the cast
is not permissible, err_mop_illegal_cast is signaled.
os_member::operator os_member_function&()
operator os_member_function&( );
Provides for safe casts from os_member to os_member_function&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_member::operator os_member_type&()
operator os_member_type&( );
Provides for safe casts from os_member to os_member_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_member::operator os_member_variable&()
operator os_member_variable&( );
Provides for safe casts from os_member to os_member_variable&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_member::operator os_relationship_member_variable&()
operator os_relationship_member_variable&( );
Provides for safe casts from os_member to os_relationship_member_variable&. If
the cast is not permissible, err_mop_illegal_cast is signaled.
os_member::Private
This enumerator is a possible return value from os_member::get_access( ),
indicating private access.
242
C++ A P I Reference
Chapter 2: Class Library
os_member::Protected
This enumerator is a possible return value from os_member::get_access( ),
indicating protected access.
os_member::Public
This enumerator is a possible return value from os_member::get_access( ),
indicating public access.
os_member::Relationship
This enumerator is a possible return value from os_member::get_kind( ),
indicating a relationship (inverse) member. See os_relationship_member_
variable on page 311.
os_member::set_access()
void set_access(int);
Specifies an enumerator describing access to the specified member: os_
member::Private, os_member::Protected, or os_member::Public.
os_member::Type
This enumerator is a possible return value from os_member::get_kind( ),
indicating that the specified member is a nested type definition. See os_member_
type on page 249.
os_member::Variable
This enumerator is a possible return value from os_member::get_kind( ),
indicating a data member. See os_member_variable on page 250.
Release 6.3
243
os_member_function
os_member_function
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent member functions.
os_member_function is derived from os_member.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_member_function::create()
static os_member_function& create(
const char* name,
os_function_type*func_type
);
Creates a member function with the specified name and of the specified type.
os_member_function::get_call_linkage()
os_call_linkage get_call_linkage( ) const;
Returns one of the following:
• os_member_function::No_linkage
• os_member_function::C_linkage
• os_member_function::C_plus_plus_linkage
• os_member_function::Fortran_linkage
os_member_function::get_function_kind()
enum os_function_kind {
Regular,
/* applicable only if it is a member function */
Constructor, Destructor,
Cast_op, /* the return type gives the cast type */
/* the operators that can be overloaded */
New_op, Delete_op,
Plus_op, Minus_op, Mul_op, Div_op, Mod_op,
Xor_op, And_op, Or_op, Comp_op,
Not_op, Assign_op, Lt_op, Gt_op,
Plus_assign_op, Minus_assign_op, Mul_assign_op,
Div_assign_op, Mod_assign_op,
Xor_assign_op, And_assign_op, Or_assign_op,
Lsh_op, Rsh_op,
Lsh_assign_op, Rsh_assign_op,
Eq_op, Neq_op, Le_op, Ge_op,
And_and_op, Or_or_op,
Inc_op, Dec_op, Comma_op,
Member_deref_op, Deref_op,
Paren_op, Subscript_op,
Vec_new_op, Vec_delete_op
};
244
C++ A P I Reference
Chapter 2: Class Library
os_function_kind get_function_kind( ) const;
Returns an enumerator indicating the kind of function the specified member
function is.
os_member_function::get_name()
const char *get_name( ) const;
Returns the name of the specified member.
os_member_function::get_source_position()
void get_source_position(
const char*& file,
os_unsigned_int32& line
) const;
Returns the source position associated with the specified function.
os_member_function::get_type()
const os_function_type& get_type( ) const;
Returns an os_function_type&, which contains information about the function,
including its return type and argument list.
Overloadings
The following is the non-const overloading of this function:
const os_function_type& get_type( );
os_member_function::is_const()
os_boolean is_const( ) const;
Returns nonzero if and only if the specified member function is const.
os_member_function::is_inline()
os_boolean is_inline( ) const;
Returns nonzero if and only if the specified member function is inline.
os_member_function::is_overloaded()
os_boolean is_overloaded( ) const;
Returns nonzero if and only if the specified member function is overloaded.
os_member_function::is_pure_virtual()
os_boolean is_pure_virtual( ) const;
Returns nonzero if and only if the specified member function is pure virtual.
os_member_function::is_static()
os_boolean is_static( ) const;
Returns nonzero if and only if the specified member function is static.
Release 6.3
245
os_member_function
os_member_function::is_virtual()
os_boolean is_virtual( ) const;
Returns nonzero if and only if the specified member function is virtual.
os_member_function::is_volatile()
os_boolean is_volatile( ) const;
Returns nonzero if and only if the specified member function is volatile.
os_member_function::set_call_linkage()
void set_call_linkage(os_call_linkage);
Passes one of the following:
• os_member_function::No_linkage
• os_member_function::C_linkage
• os_member_function::C_plus_plus_linkage
• os_member_function::Fortran_linkage
os_member_function::set_is_const()
void set_is_const(os_boolean);
The value 1 specifies that the member function is const; 0 specifies that it is nonconst.
os_member_function::set_is_inline()
void set_is_inline(os_boolean);
The value 1 specifies that the member function is inline; 0 specifies that it is not
inline.
os_member_function::set_is_overloaded()
void set_is_overloaded(os_boolean);
The value 1 specifies that the member function is overloaded; 0 specifies that it is not.
os_member_function::set_is_pure_virtual()
void set_is_pure_virtual(os_boolean);
The value 1 specifies that the member function is a pure virtual function; 0 specifies
that it is not.
os_member_function::set_is_static()
void set_is_static(os_boolean);
The value 1 specifies that the member function is a static function; 0 specifies that it
is not.
246
C++ A P I Reference
Chapter 2: Class Library
os_member_function::set_is_virtual()
void set_is_virtual(os_boolean);
The value 1 specifies that the member function is a virtual function; 0 specifies that
it is not.
os_member_function::set_is_volatile()
void set_is_volatile(os_boolean);
The value 1 specifies that the member function is volatile; 0 specifies that it is not.
os_member_function::set_name()
void set_name(const char* name);
Sets the name of the specified member.
os_member_function::set_source_position()
void set_source_position(
const char* file,
os_unsigned_int32 line
);
Sets the source position associated with the specified function.
os_member_function::set_type()
void set_type(os_function_type& mem_func);
Sets the return type of the specified member function.
Release 6.3
247
os_member_namespace
os_member_namespace
This class is part of the ObjectStore metaobject protocol (MOP). Because namespaces
can be enclosed in namespaces, they must occur as members of namespaces. The
class os_member_namespace is used to represent namespaces as members.
os_member_namespace::create()
static os_member_namespace& create(os_namespace* ns);
Creates a member namespace for the specified os_namespace.
os_member_namespace::get_namespace()
const os_namespace& get_namespace() const;
Returns the member namespace.
Overloadings
The following is the non-const overloading for this function:
os_namespace& get_namespace();
os_member_namespace::set_namespace()
void set_namespace(os_namespace&);
Sets the member namespace.
248
C++ A P I Reference
Chapter 2: Class Library
os_member_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a member type
definition, that is, a type definition that is nested within a class. os_member_type is
derived from os_member.
os_member_type::create()
static os_member_type& create(os_type*);
Creates a member type definition for the specified os_type.
os_member_type::get_type()
const os_type& get_type( ) const;
Returns the type defined by the specified member type definition.
Overloadings
The following is the non-const overloading of this function:
const os_type& get_type( );
os_member_type::set_type()
void set_type(os_type&);
Sets the type defined by the specified member type definition.
Release 6.3
249
os_member_variable
os_member_variable
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent data members. os_
member_variable is derived from os_member.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_member_variable::create()
static os_member_variable& create(
const char *name,
os_type* value_type
);
Creates an os_member_variable. The arguments specify the initial values for the
attributes name and value_type. The initial values for the remaining attributes are
as follows:
Attribute
Value
storage_class
os_member_variable::Regular
is_field
0
is_static
0
is_persistent
0
os_member_variable::get_name()
const char* get_name( ) const;
Returns the name of the specified member.
os_member_variable::get_offset()
os_unsigned_int32 get_offset( ) const;
Returns the offset in bytes of the specified member within its defining class. Signals
err_mop if the specified member is an os_field_member_variable or is a static or
persistent member.
os_member_variable::get_size()
os_unsigned_int32 get_size( ) const;
Returns the size in bytes occupied by the specified member. Signals err_mop if the
specified member is an os_field_member_variable.
250
C++ A P I Reference
Chapter 2: Class Library
os_member_variable::get_source_position()
void get_source_position(
const char*& file,
os_unsigned_int32& line
) const;
Returns the source position associated with the specified member.
os_member_variable::get_storage_class()
enum os_storage_class {Regular, Persistent, Static};
os_storage_class get_storage_class( ) const;
Returns one of the following enumerators, indicating the storage class of the
specified member:
• os_member_variable::Regular
• os_member_variable::Persistent
• os_member_variable::Static
os_member_variable::get_type()
const os_type& get_type( ) const;
Returns a reference to a const os_type, the value type of the specified member.
Overloadings
The following is the non-const overloading for this function:
os_type& get_type();
Returns a reference to a non-const os_type, the value type of the specified member.
os_member_variable::is_field()
os_boolean is_field( ) const;
Returns 1 if and only if the specified member is an os_field_member_variable.
os_member_variable::is_persistent()
os_boolean is_persistent( ) const;
Returns 1 if and only if the specified member is a persistent data member.
os_member_variable::is_static()
os_boolean is_static( ) const;
Returns 1 if and only if the specified member is a static data member.
Release 6.3
251
os_member_variable
os_member_variable::operator const os_field_member_
variable&()
operator const os_field_member_variable&( ) const;
Provides for safe casts from const os_member_variable to const os_field_
member_variable&. If the cast is not permissible, err_mop_illegal_cast is
signaled.
os_member_variable::operator const os_relationship_member_
variable&()
operator const os_relationship_member_variable&( ) const;
Provides for safe casts from const os_member_variable to const os_
relationship_member_variable&. If the cast is not permissible, err_mop_
illegal_cast is signaled.
os_member_variable::operator os_field_member_variable&()
operator os_field_member_variable&( );
Provides for safe casts from os_member_variable to os_field_member_
variable&. If the cast is not permissible, err_mop_illegal_cast is signaled.
os_member_variable::operator os_relationship_member_
variable&()
operator os_relationship_member_variable&( );
Provides for safe casts from os_member_variable to os_relationship_member_
variable&. If the cast is not permissible, err_mop_illegal_cast is signaled.
os_member_variable::set_name()
void set_name(const char* mem_name);
Specifies the name of the member specified by the this argument. ObjectStore
copies the character array pointed to by the argument.
os_member_variable::set_offset()
void set_offset(os_unsigned_int32 offset);
Sets the offset in bytes of the member specified by the this argument within its
defining class. Signals err_mop if the specified member is an os_field_member_
variable or is a static or persistent member.
os_member_variable::set_source_position()
void set_source_position(
const char* file,
os_unsigned_int32 line
);
Sets the source position associated with the member specified by the this argument.
252
C++ A P I Reference
Chapter 2: Class Library
os_member_variable::set_storage_class()
void set_storage_class(os_unsigned_int32);
Specifies one of the following enumerators, indicating the storage class of the
member specified by the this argument:
• os_member_variable::Regular
• os_member_variable::Persistent
• os_member_variable::Static
os_member_variable::set_type()
set_type(os_type& val_type);
Specifies the value type of the member specified by the this argument.
Release 6.3
253
os_mop
os_mop
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. The members provided concern the transient schema.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_mop::bind()
void os_mop::bind (
const char* hetero_set,
os_schema_options* schema_options,
os_boolean make_neutral_changes,
os_boolean allow_schema_reorg,
const char** neutral_output
);
Causes all classes in the transient schema to be bound for the current architecture. A
default invocation of this binding function occurs automatically when classes are
installed into a database schema. This interface allows the binding to occur
independently and allows additional functionality beyond the default behavior to be
invoked.
It is important to consider the effects of heterogeneity on schema neutralization. See
ossg Neutralization Options in Chapter 5 of Building ObjectStore C++ Applications for
detailed information.
hetero_set can specify any heterogeneity set supported for the current platform or
can be set to NULL if no heterogenity is requested.
schema_options specifies the compiler options and pragmas to be used on this and
other platforms.
make_neutral_changes controls whether os_mop modifies the schema
automatically to make it neutral. If make_neutral_changes is set to false and the
schema is not neutral, the exception err_mop_not_neutral is signaled.
allow_schema_reorg permits os_mop to make more complex modifications, to
ensure schema neutralization.
neutral_output allows the caller to receive a string containing a description of the
neutralization changes or failures encountered. The caller must delete the returned
string.
Neutralization
failures
If the schema is not neutral and cannot be made neutral for some reason, the
exception err_mop_cannot_neutralize is signaled. This could occur if
• A schema construct is used that is incompatible with a selected heterogeneity set
(such as using virtual base classes with the set1 heterogeneity set).
• You fail to specify allow_schema_reorg when necessary (virtual base classes
often require this).
• You fail to specify a schema_options argument with the necessary options.
254
C++ A P I Reference
Chapter 2: Class Library
See Building ObjectStore C++ Applications, Chapter 5, Building Applications for
Multiple Platforms, for more details on schema neutralization options and
regulations.
os_mop::copy_classes()
static void copy_classes(
const os_schema& schema,
os_const_classes& classes
);
Copies the specified classes into the transient schema. If any of the given classes is
not well formed or is not from the given schema, or the given schema is the transient
schema, an exception is raised.
os_mop::current()
static os_schema& current();
Returns the schema currently bound. The bound schema is the one in which
dynamically created types are deposited. After initialization of schema services, the
current schema is bound to the schema found in the transient database.
os_mop::find_namespace()
static os_namespace* find_namespace(const char* name);
Returns the os_namespace associated with the given name in the os_
schema denoted by os_mop::current().
os_mop::find_type()
static os_type* find_type(const char* name);
Returns a pointer to the type in the transient schema with the specified name; returns
0 if there is no such type.
os_mop::get_failure_classes()
os_classes osmop::get_failure_classes ();
Following a call to bind() and before a call to os_mop::reset() or os_database_
schema::install(), the function get_failure_classes() returns the classes for
which no valid neutralization was found.
This list should be empty except after a call to bind() that results in the exception
err_mop_cannot_neutralize. Note that the neutralization failure of a class can
hide further neutralization failures because no attempt is made to neutralize types
derived from or that embed failing classes.
os_mop::get_neutralized_classes()
os_classes osmop::get_neutralized_classes();
Following a call to os_mop::bind() and before a call to os_mop::reset() or os_
database_schema::install(), the function get_neutralized_classes()
returns the classes for which changes were required. If the previous call to os_
Release 6.3
255
os_mop
mop::bind() resulted in the exception err_mop_cannot_neutralize, this list is not
necessarily complete.
os_mop::get_transient_schema()
static os_schema& get_transient_schema( );
Returns a reference to the transient schema.
os_mop::initialize()
static void initialize( );
Must be called before you use the transient schema, that is, before you create any
schema objects and before you copy any classes into the transient schema.
os_mop::initialize_object_metadata()
static void os_mop::initialize_object_metadata(
void* obj,
const char* type_name
);
This interface initializes the compiler metadata, if any, associated with the object.
The object instance can be transient or persistent; however, the schema for its class
must be present in the application schema. If the object is transient, the type_name
argument must be non-NULL and indicate the name of the class of the object.
If the object is persistent, type_name can be NULL. If non-NULL, it must match exactly
the real type of the object; otherwise, an exception is generated. For example, names
returned by the os_types or os_mop subsystem are safe to use and will match
correctly. The best method is to pass a null type_name when the instance is
persistent.
This call must be made inside a transaction. The object pointer must be a pointer to
a valid top-level object. Pointers to embedded objects generate an exception in the
case of persistent pointers in which this case can be verified. In the case of transient
instances, no such checking is possible, and a bad initialization could result.
Top-level arrays must be initialized one element at a time. The object pointer must
point beyond any vector headers in a top-level array. Embedded arrays within
objects are initialized correctly. Also, any compiler metadata inside a union with
discriminants is not initialized. It is very difficult to arrange to call uniondiscriminant functions during this initialization.
Virtual base class pointers, vector headers, and any other compiler metadata are not
affected by this interface. It also has no effect on normal class data.
os_mop::reset()
static void reset ();
Resets the portion of schema services responsible for the access and construction of
schema types through the MOP interface. After this operation, the current schema is
empty.
256
C++ A P I Reference
Chapter 2: Class Library
os_named_indirect_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ typedef.
This class is derived from os_anonymous_indirect_type. Performing os_
anonymous_indirect_type::get_target_type( ) on an os_named_indirect_
type results in the type named by the typedef.
os_named_indirect_type::create()
static os_named_indirect_type& create(
os_type* target,
const char*
);
Creates an os_named_indirect_type.
os_named_indirect_type::get_name()
const char* get_name( ) const;
Returns the name of the specified typedef.
os_named_indirect_type::get_source_position()
void get_source_position(
const char*& file,
os_unsigned_int32& line
) const;
Returns the source position associated with the specified typedef.
os_named_indirect_type::set_name()
const char* set_name( ) const;
Sets the name of the specified typedef.
os_named_indirect_type::set_source_position()
void set_source_position(
const char* file,
os_unsigned_int32 line
);
Sets the source position associated with the specified typedef.
Release 6.3
257
os_namespace
os_namespace
This class is part of the ObjectStore metaobject protocol (MOP).
os_namespace::create()
static os_namespace& create(const char* name);
Creates a namespace for the specified name.
Overloadings
The following overloading is supported:
static os_namespace& create(
const char* name,
os_members& mems
);
Creates a namespace for the specified name and members.
os_namespace::get_enclosing_namespace()
const os_namespace* get_enclosing_namespace() const;
Returns the enclosing namespace if one exists; otherwise, returns 0.
Overloadings
The following is the non-const overloading for this function:
os_namespace* get_enclosing_namespace();
os_namespace::get_members()
os_const_members get_members() const;
Returns the members of the namespace.
Overloadings
The following is the non-const overloading for this function:
os_members get_members();
os_namespace::get_name()
const char* get_name() const;
Returns the members of the namespace.
os_namespace::set_enclosing_namespace()
const os_namespace* set_enclosing_namespace() const;
Returns the enclosing namespace if one exists; otherwise, returns 0.
Overloadings
The following is the non-const overloading for this function:
os_namespace* set_enclosing_namespace();
os_namespace::set_members()
typedef os_List<os_members*> os_members;
void set_members(os_members& mem_list);
Uses mem_list to set the members of the namespace.
258
C++ A P I Reference
Chapter 2: Class Library
os_namespace::set_name()
void set_name(const char* name);
Sets the name of the namespace.
Release 6.3
259
os_notification
os_notification
Objects of class os_notification represent notifications for sending and receiving.
A notification object embodies a database location (os_soft_pointer), a signed 32bit integer kind, and a null-terminated C string.
os_notification::assign()
void assign(
const os_soft_pointer<void>& loc,
os_int32 kind=0,
const char* string=0
);
Notifications can be reassigned using the assign member function. This is most
useful when allocating arrays of notifications.
When passing database locations to os_notification member functions, you need
not explicitly convert to os_soft_pointer.
You can retrieve the components of a notification by using the following accessor
functions.
os_notification::get_database()
os_database* get_database()const;
Retrieves the database associated with the notification.
os_notification::get_kind()
os_int32 get_kind()const;
Retrieves the kind associated with the notification.
os_notification::_get_fd()
Returns a file descriptor that can be used to detect whether any notifications exist.
The only legal operation on this file descriptor is to call select() or poll(), to
determine whether any data has been received. If data has been received, a
notification has been queued for this application. It can be retrieved using os_
notification::receive().
After retrieving a notification, you can test for further notifications again by using
select() or poll(). (That is, os_notification::receive() resets the
notification_fd to the not ready state unless further notifications are pending.)
This function is not available on all platforms and configurations because file
descriptors are not used portably on all platforms. If notifications are not delivered
using an fd mechanism, this function returns –1.
Note
260
Using this fd for any purpose other than poll() or select() could cause
unexpected application behavior. The cache manager and/or ObjectStore server
could disconnect from the client.
C++ A P I Reference
Chapter 2: Class Library
os_notification::get_location()
os_soft_pointer<void> get_location() const;
Retrieves the reference associated with the notification.
os_notification::get_string()
const char* get_string()const;
Retrieves the string associated with the notification.
The following are member functions that provide shortcuts for the static member
functions also defined for this class:
void notify_immediate();
void notify_on_commit();
A public enumeration in class os_notification represents the maximum string
length usable in notifications:
enum {maximum_string_length = 16383};
A public enumeration in class os_notification represents the maximum
notification queue size:
enum {maximum_notification_queue_length = 512};
os_notification::notify_immediate()
static void notify_immediate(
const os_soft_pointer<void>& loc,
os_int32 kind = 0,
const char* string = 0,
os_int32* n_queued = 0
);
static void notify_immediate(
const os_notification* notifications,
os_int32 n_notifications = 1,
os_int32* n_queued = 0
);
Posts a notification to the object specified by loc. The database associated with loc
must be open. The kind and string arguments are arguments sent to the receiving
process.
Note
The kind argument must be greater than or equal to 0. Negative kind arguments are
reserved for future use by ObjectStore.
If the string specified is null (0), it is received as an empty string ("").
If supplied, the n_queued argument is a signed 32-bit integer (or an array of n_
notifications integers). This integer is set to the number of receiving processes to
which notifications were queued. Note that because notifications are asynchronous,
no guarantees can be made that the process will ever receive the notification. (The
receiving process might terminate before receiving the notification, it might never
check for notifications, the ObjectStore server might crash, the cache manager might
crash, or the notification queue could overflow.)
Release 6.3
261
os_notification
In the second (array) form of notify_immediate(), the n_queued argument, if
specified, is an os_int32 array at least n_notifications long. The elements of the
array are set to the number of receiving processes for each notification specified.
Each call results in a single RPC call to each ObjectStore server. It is significantly
more efficient to make one call with an array of notifications than to make many calls,
each with its own notification.
If the caller does not require the n_queued information, it should leave n_queued
defaulted to 0. This could result in better performance in future releases.
The notify_immediate() operation is not atomic. That is, if an error is signaled, the
status of notifications is undefined. For example, notifications might have been
delivered successfully to one server before a second server signals an error with
respect to its notifications.
os_notification::notify_on_commit()
static void notify_on_commit(
const os_soft_pointer<void> &loc,
os_int32 kind = 0,
const char* string = 0
);
static void notify_on_commit(
const os_notification* notifications,
os_int32 n_notifications = 1
);
Queues a commit-time notification to the object specified by loc. The database
associated with loc must be open and there must be a transaction in progress. The
notification is delivered when, and if and only if,
• No enclosing transaction aborts.
• The enclosing top-level transaction commits. The kind and string arguments are
sent to the receiving processes after the commit completes.
If the string specified is null (0), it is received as an empty string ("").
Notification delivery and commit are an atomic operation from the perspective of the
process sending the notification. That is, if the commit succeeds, the notifications are
guaranteed to be sent, even if the sending application crashes. Note, however, that
the notifications themselves are transient and might be lost if there is a server failure,
cache manager failure, notification queue overflow, or a receiving process dies.
The notifications are matched with subscriptions immediately after the commit
succeeds. Because of this, there is no way to determine the number of processes that
have been queued to receive notifications.
If a deadlock occurs during a lexical transaction, ObjectStore aborts and
automatically restarts the transaction. In this case, because the transaction aborted,
commit-time notifications are discarded and execution resumes at the beginning of
the lexical transaction.
os_notification::notify_on_commit() does not immediately perform an RPC
call to the server. If there are any calls to os_notification::notify_on_commit()
262
C++ A P I Reference
Chapter 2: Class Library
during a top-level transaction and the transaction commits, there is one additional
RPC call to each server at commit time.
In some read-only transactions, the ObjectStore client does not normally have to
communicate with servers. If os_notification::notify_on_commit() is called
during such a read-only transaction, the server must be contacted during the
commit.
If a database is closed after a notify_on_commit() but before committing the
transaction, the notification is still delivered on successful commit. The database
must be open when notify_on_commit() is called.
os_notification::os_notification()
os_notification(
const os_soft_pointer<void>& loc,
os_int32 kind=0,
const char* string=0
);
Notifications can be created using a constructor that specifies all these elements. The
os_notification object copies its string argument when the object is created and
deletes the storage for the string copy when it is deleted.
Overloadings
The following overloading is supported:
os_notification();
Notifications can also be allocated in arrays (see os_subscription on page 396). The
default constructor for os_notification produces an uninitialized notification.
os_notification::queue_status()
static void queue_status(
os_unsigned_int32& queue_size,
os_unsigned_int32& count_pending_notifications,
os_unsigned_int32& count_queue_overflows
);
Returns information on the notification queue for the current process. If count_
pending_notifications is greater than 0, notifications are pending. This function
can be used as a polling function to determine whether there are notifications
without actually retrieving them. It does not lock out other ObjectStore operations in
other threads.
Generally, applications should call this at least once after each notification is
retrieved to ensure that there are no queue overflows and to perform appropriate
actions if there are.
Release 6.3
263
os_notification
Values returned are as follows:
Return Values
Meaning
queue_size
The size of the notification queue, as set by os_
notification::set_queue_size(), OS_
NOTIFICATION_QUEUE_SIZE, or defaulted.
count_pending_
notifications
The number of notifications currently in the queue,
that is, notifications that have not yet been received
by the process using os_
notification::receive().
count_queue_overflows
The number of notifications discarded since the
process started. A value of 0 indicates that no
notifications have been discarded since this process
began.
os_notification::receive()
static os_boolean receive(
os_notification*& notification,
os_int32 timeout = -1
);
Gets the next notification from the notification queue, if available. If a notification is
available, it returns true and places the notification in the first argument. Otherwise,
it returns false and the first argument is unmodified.
If the notification queue is currently empty, the function waits as specified by the
timeout argument. A value of –1 means to wait forever until a notification is
received. A value of 0 means to return false immediately. A positive integer means
to wait the specified number of milliseconds. On some platforms, this value is
rounded up to the next higher number of seconds.
The notification returned is allocated dynamically in transient storage. When the
application finishes using it, it can be deleted using the C++ delete operator. (This
causes the notification string to be deleted as well.)
os_notification::receive() uses operating system primitives for waiting; it
does not spin, polling for notifications. Users normally call this function in a separate
thread that exists specifically to receive notifications.
Only one thread can call os_notification::receive() at any one time. It is an
error to call os_notification::receive() in multiple threads simultaneously.
Only os_notification::receive() and os_notification::queue_status()
can be called asynchronously with other ObjectStore operations. All other APIs,
including the os_notification accessors, are subject to normal thread-locking
rules. This means that the retrieved notifications cannot be accessed in concurrent
threads without locking out ObjectStore threads.
If os_notification::receive() is called before you subscribe to notifications, it
returns false immediately, regardless of the timeout argument. This is to avoid
deadlocks in some situations involving multiple threads. To avoid this, ensure that
264
C++ A P I Reference
Chapter 2: Class Library
os_notification::subscribe() or os_notification::_get_fd() is called
before calling os_notification::receive() or before launching a thread that calls
os_notification::receive().
With long strings, os_notification::receive() might have to wait slightly for the
entire string, even if timeout==0 is specified.
os_notification::set_queue_size()
static void set_queue_size(
os_unsigned_int32 queue_size
);
Sets the size of the notification queue for a process. It must be called before os_
notification::subscribe() or os_notification::_get_fd(). If this function is
not called, the queue size is determined by the value of the OS_NOTIFICATION_
QUEUE_SIZE environment variable. If the environment variable is not set, the queue
size is set to a default value, currently 50.
A public enumeration in class os_notification represents the maximum
notification queue size:
enum {maximum_notification_queue_length = 16384};
Notification queues are part of the ObjectStore cache manager process.
os_notification::subscribe()
static void subscribe(
const os_subscription* sub,
os_int32 number_of_elements = 1
);
Subscribes to one or more os_subscription objects that were created to perform
subscribe operations while using the notifications API. If sub is an array, number_
of_elements must be greater than 1.
The database must be open. Closing the database immediately unsubscribes all
locations in the database.
If a database location is subscribed more than once, the notification system behaves
as if there were only one subscription on the location. That is, except for the first, all
subscriptions to the same location are ignored.
Each call results in a single RPC call to each ObjectStore server. It is significantly
more efficient to make one call with an array of subscriptions than to make many
calls, one with each subscription.
The subscription operation is not atomic. That is, if an error is
signaled, the status of subscriptions is undefined. For example,
subscriptions might have succeeded on one server before a second
server signals an error with respect to its subscriptions.
Overloadings
Release 6.3
The following overloadings subscribe to receive notifications in a database, a
segment, a cluster, or an address range. A subscription in a database, segment, or
cluster applies to all addresses in the database, segment, or cluster—even addresses
not yet allocated.
265
os_notification
static void subscribe(
const os_database* db
);
static void subscribe(
const os_segment* seg
);
static void subscribe(
const os_cluster* clstr
);
static void subscribe(
const os_soft_pointer<void>& addr_range,
os_int32 number_of_bytes = 1
);
os_notification::unsubscribe()
static void unsubscribe(
const os_subscription* sub,
os_int32 number_of_elements = 1
);
Unsubscribes to one or more os_subscription objects that were created to perform
subscribe operations while using the notifications API. If sub is an array, number_
of_elements must be greater than 1.
Closing a database automatically unsubscribes all notifications for the database.
Because notifications are processed asynchronously, an application might continue
to receive notifications after having unsubscribed.
Each call results in a single RPC call to each ObjectStore server. It is much more
efficient to make one call with an array of subscriptions than to make many calls, one
with each subscription.
The unsubscription operation is not atomic. That is, if an error is signaled, the status
of unsubscriptions is undefined. For example, unsubscriptions might have
succeeded on one server before a second server signals an error with respect to its
unsubscription.
Overloadings
The following overloadings unsubscribe to notifications in a database, a segment, a
cluster, or an address range:
static void unsubscribe(
const os_database* db
);
static void unsubscribe(
const os_segment* seg
);
static void unsubscribe(
const os_cluster* clstr
);
static void unsubscribe(
const os_soft_pointer<void>& addr_range,
os_int32 number_of_bytes = 1
);
266
C++ A P I Reference
Chapter 2: Class Library
If a subscription was made on an entire database, the only way to remove it is to
unsubscribe the entire database; you cannot selectively unsubscribe segments or
database locations.
If a subscription was made on an entire segment, the only way to remove it is to
unsubscribe the entire database or unsubscribe the entire segment. You cannot
selectively unsubscribe database locations within the segment.
If a subscription was made on a cluster or address range, ranges can be selectively
unsubscribed within the original cluster or range.
Notes
• If os_notification::queue_status() is called before os_
notification::subscribe() or os_notification::_get_fd(), all values
returned are 0.
• n_queued can sometimes be larger than queue size.
• In general, queue_status() should be called in the same thread as os_
notification::receive().
• If queue_status() is called in another thread while os_
notification::receive() is in process,
- os_notification::receive() might not actually retrieve a notification.
- n_queued might not actually reflect the receipt of this notification.
• If n_queued is nonzero, os_notification::receive() might still sometimes
return 0 (false), particularly if receive() is called with a zero timeout. This
happens if the cache manager cannot empty its queue as fast as the receiving
process is calling os_notification::receive().
Network service
When an ObjectStore application uses notifications, it automatically establishes a
second network connection to the cache manager daemon on the local host. The
application uses this connection to receive and acknowledge the receipt of incoming
notifications from the cache manager. (Outgoing notifications are sent to the server,
not the cache manager.) For more information, see Managing ObjectStore.
Notification
errors
The notification APIs do not do complete validation of the arguments passed to
them. Malformed arguments can therefore cause segmentation violations or other
undefined behavior. See General ObjectStore Exceptions on page 501 for details.
Utilities
ossvrstat currently prints statistics on the number of notifications received and
sent by the server.
oscmstat prints information on notifications queued for clients. This is useful in
debugging applications that use notifications.
For more information on these user interfaces, see Managing ObjectStore.
Release 6.3
267
os_object_cursor
os_object_cursor
An object cursor allows retrieval of the objects stored in a specified cluster or
segment, one object at a time, in an arbitrary order. This order is stable across
traversals of the cluster or segment, as long as no objects are created or deleted and
no reorganization is performed (using schema evolution or compaction). Operations
are provided for creating a cursor, advancing a cursor, and for testing whether a
cursor is currently positioned at an object (or has run off the end of the cluster or
segment). It is also possible to position a cursor at a specified object.
In addition, an operation is provided for retrieving the object at which a cursor is
positioned, together with an os_type representing the type of the object, and, for an
object that is an array, a number indicating how many elements it has.
os_object_cursor::current()
os_boolean current(
void*& p,
const os_type*& type,
os_int32& count
) const;
If the cursor is positioned at an object, returns nonzero (true), sets p to refer to the
address of the object, and sets type to refer to an os_type representing the object’s
type. If the object is an array, count is set to refer to the number of elements it has; if
the object is not an array, count is set to 0. If the cursor is not positioned at an object,
0 (false) is returned, and all three arguments are set to refer to 0.
os_object_cursor::first()
void first( );
Positions the cursor at the first object in the cursor’s associated cluster or segment.
The object is first in an arbitrary order that is stable across traversals of the cluster or
segment, as long as no objects are created or deleted and no reorganization is
performed (using schema evolution or compaction). If there are no objects in the
cursor’s associated cluster or segment, the cursor is positioned at no object.
os_object_cursor::more()
os_boolean more( ) const;
Returns nonzero (true) if the cursor is positioned at an object. Returns 0 (false)
otherwise.
os_object_cursor::next()
void next( );
Positions the cursor at the next object in the cursor’s associated cluster or segment.
The object is next in an arbitrary order that is stable across traversals of the cluster or
segment, as long as no objects are created or deleted and no reorganization is
performed (using schema evolution or compaction). If the cursor is positioned at no
268
C++ A P I Reference
Chapter 2: Class Library
object, err_cursor_at_end is signaled. Otherwise, if there is no next object, the
cursor is positioned at no object.
os_object_cursor::os_object_cursor()
os_object_cursor(const os_cluster* clstr);
os_object_cursor(const os_segment* seg);
Creates a new os_object_cursor associated with the specified cluster or segment.
If the cluster or segment is empty, the cursor is positioned at no object; otherwise, it
is positioned at the first object in the cursor’s associated cluster or segment. The
object is first in an arbitrary order that is stable across traversals of the cluster or
segment, as long as no objects are created or deleted and no reorganization is
performed (using schema evolution or compaction).
os_object_cursor::release_address_space()
void release_address_space();
Release the entire persistent address space while preserving the state of this object
cursor only.
Overloading
The following overloading is supported:
void release_address_space(
os_address_space_marker& marker,
os_boolean unmap_all_fast = 0);
Release address space by calling marker.release() while preserving the state of
this object cursor only.
If the unmap_all_fast argument is nonzero (true), ObjectStore unmaps the entire
PSR. Such an operation takes less time than unmapping only the marked pages.
Note, however, that setting unmap_all_fast to true can decrease performance by
causing the application to take more page faults after releasing the marker. The
default — unmap_all_fast is set to 0 (false) — is to unmap only the marked pages.
If you use the unmap_all_fast argument, you should set it to true only when you
are sure that the application will no longer need to access the unmapped pages or is
near the end of a transaction, when all pages in the PSR will be unmapped anyway.
os_object_cursor::reset()
void reset(const void* p);
Moves the cursor to the object at the address p. If p points to deleted space, the cursor
is positioned at the object immediately after that address. If there is no object after
the deleted space, err_cursor_not_at_object is signaled.
Release 6.3
269
os_object_cursor
os_object_cursor::set()
void set(const void* p);
Positions the cursor at the object containing the address p. If p is not an address in
the specified cursor’s associated cluster or segment, signals err_cursor_not_at_
object. If p is in the cursor’s associated cluster or segment but within unallocated
space, the cursor is positioned at no object or is arbitrarily positioned at an object in
the cluster or segment.
os_object_cursor::~os_object_cursor()
~os_object_cursor( );
Performs internal maintenance associated with os_object_cursor deallocation.
270
C++ A P I Reference
Chapter 2: Class Library
os_path_to_data
An os_path_to_data object denotes an unambiguous path to a base class or a data
member of a class. Because there may be a number of possible paths to a component
of a virtual base class, paths to virtual base class components merit special attention.
All virtual base classes are treated as though they are immediate base classes of the
root class of the path. This rule permits an unambiguous specification of a path that
traverses a virtual base class.
The os_path_to_data object is used by user-defined untranslatable pointer
handlers during schema evolution. (For more information about untranslatable
pointer handlers, see os_untranslatable_pointer_handler on page 448).
The os_path_to_data class is part of the ObjectStore metaobject protocol (MOP).
os_path_to_data::add()
Methods for building up a path by adding components. In the case of a virtual base
class, the base class must be the one that represents the actual allocated storage.
There are three overloadings:
void add(const os_base_class& b);
Adds a base class component.
void add(const os_member_variable& m);
Adds a simple member selection component.
void add(
const os_member_variable& m,
os_unsigned_int32 subscript);
Adds a subscripted member component.
os_path_to_data::bit_offset()
os_unsigned_int32 bit_offset() const;
Returns the offset in bits to the datum at the end of the path, starting from the root
class.
os_path_to_data::byte_offset();
os_unsigned_int32 byte_offset() const;
Returns the offset in bytes to the datum at the end of the path starting from the root
class. Wrong if not byte-aligned.
os_path_to_data::get_root()
const os_class_type& get_root() const;
Returns the class in which the path is rooted.
Release 6.3
271
os_path_to_data
os_path_to_data::get_total_number_of_elements()
os_unsigned_int32 get_total_number_of_elements() const;
Gets the total number of elements (for example, array[2][2] returns 4) for the path
to a member with arrayness. An assertion violation occurs if to_subscript() ==
false.
os_path_to_data::has_array_components()
os_boolean has_array_components() const;
Returns true if there are any array components in the path.
os_path_to_data::is_base_path ()
os_boolean is_base_path() const;
Returns true if this is a path to a base class component.
os_path_to_data::is_member_variable_path()
os_boolean is_member_variable_path() const;
Returns true if path can be interpreted to a data member.
os_path_to_data::local_path()
os_path_to_data* local_path() const;
Returns the path relative to the most derived enclosing class along the path,
stripping off all preceding member selections, if any.
os_path_to_data::make()
There are two overloadings:
static os_path_to_data* make(const os_class_type& root_class);
Constructs a path that consists of just the class root_class.
static os_path_to_data* make(
const os_path_to_data& other_path);
Constructs a path that is a copy of another path. You can call pop() and add() to
make adjustments to the copy.
os_path_to_data::minor_subscript()
os_unsigned_int32 minor_subscript() const;
Gets the minor subscript associated with the path. It assumes to_subscript() ==
true.
os_path_to_data::name()
char *name() const;
Returns a unique string suitable for printing associated with the path. The caller
must free the string when done with it.
272
C++ A P I Reference
Chapter 2: Class Library
os_path_to_data::outer_collocated_path()
os_path_to_data* outer_collocated_path() const;
Returns a path to the outermost base class or member located at exactly the same
address as the object at the end of the current path.
os_path_to_data::outer_path()
os_path_to_data& outer_path(
os_boolean remove_indexing = false) const;
Returns a simple path to the outermost base class, member, or dope relative to the
root class. If remove_indexing is true, outermost member subscripts and union
member offsets are converted to ordinary members.
os_path_to_data::pop()
void pop();
Removes and deletes the last component in the path.
os_path_to_data::to_bit_field()
os_boolean to_bit_field() const;
Returns true if it is a path to a bit field.
os_path_to_data::to_dope()
os_boolean to_dope() const;
Returns true if it is a path to internal representation dope.
os_path_to_data::to_static_member()
os_boolean to_static_member() const;
Returns true if it is a path to a static data member.
os_path_to_data::to_subscript()
os_boolean to_subscript() const;
Returns true if it is a path to a member with arrayness.
os_path_to_data::type()
os_type* type() const;
The type of the datum at the end of the path. Return NULL when there is no type that
can be associated with the path. This can happen in one of two ways:
• There are multiple possible types, since it ends in a union offset component.
• The path leads to internal dope.
os_path_to_data::unique_name()
char *unique_name() const;
Release 6.3
273
os_path_to_data
A truly unique string suitable for printing associated with the path. The caller must
free the string when done with it.
274
C++ A P I Reference
Chapter 2: Class Library
os_pathname_and_segment_number
This class is used by the compactor API to identify segments; see os_
compact::compact() on page 142. For information about identifying a cluster for
compaction, see os_pathname_segment_cluster on page 276.
Required
header file
Programs using this function must include <ostore/compact.hh>.
os_pathname_and_segment_number::database_pathname
const char* database_pathname;
The value of this member is the path name of the database containing the segment
identified by the specified os_pathname_and_segment_number.
os_pathname_and_segment_number::os_pathname_and_
segment_number()
os_pathname_and_segment_number(
const char* db,
os_unsigned_int32 seg_num
);
The constructor takes two arguments. The db argument initializes the member
database_pathname, and the seg_num argument initializes the member segment_
number.
os_pathname_and_segment_number::segment_number
os_unsigned_int32 segment_number;
The value of this member is the segment number of the segment identified by the
specified os_pathname_and_segment_number. The segment number of a specified
segment can be obtained using os_segment::get_number() on page 357.
Release 6.3
275
os_pathname_segment_cluster
os_pathname_segment_cluster
This class is used by the compactor API to identify clusters; see os_
compact::compact() on page 142. For information about identifying a segment for
compaction, see os_pathname_and_segment_number on page 275.
Required
header file
Programs using this function must include <ostore/compact.hh>.
os_pathname_segment_cluster::database_pathname
const char* database_pathname;
The value of this member is the path name of the database containing the segment
identified by the os_pathname_segment_cluster object.
os_pathname_segment_cluster::os_pathname_segment_
cluster()
os_pathname_segment_cluster(
const char* db,
os_unsigned_int32 seg_num
os_unsigned_int32 clstr_num
);
The constructor takes three arguments. The db argument initializes the member
database_pathname, seg_num initializes the member segment_number, and clstr_
num initializes the member cluster_number.
os_pathname_segment_cluster::cluster_number
os_unsigned_int32 cluster_number;
The value of this member is the number of the cluster identified by the os_
pathname_segment_cluster object. For information about obtaining the number of
a cluster, see os_cluster::get_number() on page 133.
os_pathname_segment_cluster::segment_number
os_unsigned_int32 segment_number;
The value of this member is the number of the segment identified by the os_
pathname_segment_cluster object. For information about obtaining the number of
a segment, see os_segment::get_number() on page 357.
276
C++ A P I Reference
Chapter 2: Class Library
os_persistent_to_transient_pointer_manager
The os_persistent_to_transient_pointer_manager class is an abstract base
class from which you derive a concrete class for managing persistent pointers to
transient objects.
os_persistent_to_transient_pointer_manager::release()
virtual void release(void* p) = 0;
Your concrete class must define a release() function to be called by ObjectStore in
response to an application call to objectstore::release_cleared_persistent_
to_transient_pointers(). This function is responsible for handling applicationspecific details of the persistent-to-transient connection. For example, the release()
function could decrement a use count on the transient object and delete the object
when appropriate.
The release() function runs without holding the session lock.
The application should not delete the user-defined manager while there is any
possibility that ObjectStore retains a pointer to it
For more information on persistent pointers to transient objects, see:
• objectstore::change_type()
• objectstore::release_cleared_persistent_to_transient_pointers()
• objectstore::set_persistent_to_transient_pointer()
• Persistent Pointers to Transient Objects on page 32 in the Advanced C++ A P I User
Guide.
Release 6.3
277
os_Planning_action
os_Planning_action
This class is part of the dump/load facility and is used by implementers of
customized dump and load utilities. It is an abstract base class that specifies the
protocol for a user-defined class derived from it. The derived class handles dump
planning, including the identification of objects for which object forms should not be
generated.
See Chapter 6, Dump/Load Facility, in the Advanced C++ A P I User Guide for
information on customizing the dumping and loading of ObjectStore databases.
This section describes the behavior, if implemented correctly, of the members of os_
Planning_action that can be implemented in the derived class. The class type_
planner is a class that is derived from os_Planning_action for customization of the
dumping of the type type.
os_Planning_action::operator ()()
void type_planner::operator () (
const os_type& actual_type,
void* obj
)
Marks the objects that should be skipped during the generation of object forms. (The
objects should be skipped because they will be created during the fixup of other
objects.)
See Implementing operator ()() in the Advanced C++ A P I User Guide for information
on implementing this function.
278
C++ A P I Reference
Chapter 2: Class Library
os_pointer_literal
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ pointer
literal.
Type definitions
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.
os_pointer_literal::create()
static os_pointer_literal& create(
const char* name,
os_pointer_type*
);
Creates an os_pointer_literal of the specified name and type.
os_pointer_literal::get_name()
const char* get_name( ) const;
Returns the name of the specified literal.
os_pointer_literal::get_type()
os_pointer_type& get_type( ) const;
Returns the type of the specified pointer.
os_pointer_literal::set_name()
void set_name(const char*);
Sets the name of the specified literal.
os_pointer_literal::set_type()
void set_type(os_pointer_type&);
Sets the type of the specified pointer.
Release 6.3
279
os_pointer_to_member_type
os_pointer_to_member_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ pointer-tomember type. This class is derived from os_pointer_type.
os_pointer_to_member_type::create()
static os_pointer_to_member_type& create(
os_type* target,
os_class_type*
);
The argument is used to initialize target_class and target_type.
os_pointer_to_member_type::get_target_class()
const os_class_type& get_target_class( ) const;
Returns the class associated with the specified pointer-to-member.
Overloadings
The following is the non-const overloading of this function:
os_class_type& get_target_class( );
os_pointer_to_member_type::set_target_class()
void set_target_class(os_class_type&);
Sets the class associated with the specified pointer-to-member.
280
C++ A P I Reference
Chapter 2: Class Library
os_pointer_type
class os_pointer_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ pointer
type. This class is derived from os_type.
os_pointer_type::create()
static os_pointer_type& create(os_type* target);
The argument is used to initialize the attribute target_type.
os_pointer_type::get_target_type()
const os_type& get_target_type( ) const;
Returns the type of object pointed to by instances of the specified pointer type.
os_pointer_type::set_target_type()
void set_target_type(os_type&);
Sets the type of object pointed to by instances of the specified pointer type.
Release 6.3
281
os_pragma
os_pragma
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ pragma.
os_pragma::create()
static os_pragma& create(const char*);
Creates a new pragma and associates the specified string with it.
os_pragma::get_string()
const char* get_string( ) const;
Returns the string associated with the specified pragma.
os_pragma::is_recognized()
os_boolean is_recognized( ) const;
Returns nonzero if the specified pragma is recognized.
282
C++ A P I Reference
Chapter 2: Class Library
os_rawfs_entry
The functions os_dbutil:stat( ) and os_dbutil::list_directory( ) return
pointers to instances of this class. Each os_rawfs_entry represents a rawfs
directory, database, or link.
os_rawfs_entry::get_abs_path()
const char* get_abs_path( ) const;
Returns the absolute path name for the specified entry.
os_rawfs_entry::get_creation_time()
os_unixtime_t get_creation_time( ) const;
Returns the creation time for the specified entry.
os_rawfs_entry::get_group_name()
const char* get_group_name( ) const;
Returns the name of the primary group for the specified entry.
os_rawfs_entry::get_link_host()
const char* get_link_host( ) const;
Returns the name of the host for the target of the link represented by the specified
entry. If the entry does not represent a link, 0 is returned.
os_rawfs_entry::get_link_path()
const char* get_link_path( ) const;
Returns the path name of the target of the link represented by the specified entry. If
the entry does not represent a link, 0 is returned.
os_rawfs_entry::get_n_sectors()
os_unsigned_int32 get_n_sectors( ) const;
Returns the number of sectors in the specified entry.
os_rawfs_entry::get_name()
const char* get_name( ) const;
Returns the terminal component of the path name for the specified entry.
os_rawfs_entry::get_permission()
os_unsigned_int32 get_permission( ) const;
Returns a bit-wise disjunction representing the permissions on the specified entry.
Release 6.3
283
os_rawfs_entry
os_rawfs_entry::get_server_host()
const char* get_server_host( ) const;
Returns the name of the host for the specified entry.
os_rawfs_entry::get_type()
os_int32 get_type( ) const;
Returns an enumerator indicating whether the specified entry represents a directory,
database, or link. One of the following enumerators is returned:
• os_rawfs_entry::OSU_DIRECTORY
• os_rawfs_entry::OSU_DATABASE
• os_rawfs_entry::OSU_LINK
os_rawfs_entry::get_user_name()
const char* get_user_name( ) const;
Returns the name of the user for the specified entry.
os_rawfs_entry::is_db()
os_boolean is_db( ) const;
Returns nonzero if the specified entry represents a database; returns 0 otherwise.
os_rawfs_entry::is_dir()
os_boolean is_dir( ) const;
Returns nonzero if the specified entry represents a directory; returns 0 otherwise.
os_rawfs_entry::is_link()
os_boolean is_link( ) const;
Returns nonzero if the specified entry represents a link; returns 0 otherwise.
os_rawfs_entry::operator =()
os_rawfs_entry& operator =(const os_rawfs_entry&);
Modifies the left operand so that it is a copy of the right operand. The copy behaves
like the original with respect to the member functions of os_rawfs_entry.
os_rawfs_entry::os_rawfs_entry()
os_rawfs_entry(const os_rawfs_entry&);
Creates an os_rawfs_entry that is a copy of the specified os_rawfs_entry. The
copy behaves like the original with respect to the member functions of the class os_
rawfs_entry.
284
C++ A P I Reference
Chapter 2: Class Library
os_rawfs_entry::~os_rawfs_entry()
~os_rawfs_entry( );
Frees storage associated with the specified os_rawfs_entry.
os_rawfs_entry::OSU_DATABASE
Enumerator used as possible return value for os_rawfs_entry::get_type( ),
indicating that the specified os_rawfs_entry represents a database.
os_rawfs_entry::OSU_DIRECTORY
Enumerator used as possible return value for os_rawfs_entry::get_type( ),
indicating that the specified os_rawfs_entry represents a directory.
os_rawfs_entry::OSU_LINK
Enumerator used as possible return value for os_rawfs_entry::get_type( ),
indicating that the specified os_rawfs_entry represents a link.
Release 6.3
285
os_real_type
os_real_type
class os_real_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ floating
type. This class is derived from os_type.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_real_type::create()
static os_real_type& create(const char*);
Creates an os_real_type representing the type with the specified name.
os_real_type::create_double()
static os_real_type& create_double( );
Creates an os_real_type representing the type double.
os_real_type::create_float()
static os_real_type& create_float( );
Creates an os_real_type representing the type float.
os_real_type::create_long_double()
static os_real_type& create_long_double( );
Creates an os_real_type representing the type long double.
286
C++ A P I Reference
Chapter 2: Class Library
os_recover
The os_recover class provides the means to perform a database recovery from an
ObjectStore application. The ObjectStore application recovers the database from an
archive image that you create with the osarchiv utility or with an ObjectStore
application that uses methods of the os_archive classes.
For more information on using a command-line utility to recover databases, see
osrecovr in Managing ObjectStore.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/dbutil.hh>.
os_recover::os_recover()
os_recover(const char* recover_ID)
Constructs the necessary class for recovering databases. The recover_ID argument
should be a unique character string identifying this recovery process in the backrest
log, as described in os_dbutil::start_backrest_logging() on page 191.
os_recover::~os_recover()
~os_recover();
Performs internal cleanup of the recovery process. Calling ~os_recover() while the
recovery process is running will abort the recovery.
os_recover::get_status()
os_int32 get_status();
Returns the current status of the recovery process. The possible return values are:
Return Value Meaning
-1
The recovery process is still running.
0
The recovery process has either completed successfully or has not
yet started.
1
The recovery process has failed. Check the backrest log for
additional information.
os_recover::start_and_run_recover()
os_boolean start_and_run_recover(
os_recover_options & options);
Starts and runs the recovery process to completion. The options calling argument
should have the necessary data members set. A return code of zero indicates the
restore process successfully completed. For a non-zero return code, check the
backrest log for further information. For information about the options you can use,
see os_recover_options on page 289.
Release 6.3
287
os_recover
os_recover::start_recover()
void start_recover(os_recover_options & options);
Starts the recovery process in a separate thread and then returns immediately. The
options calling argument should have the necessary data members set. After calling
start_recover(), call os_recover::get_status() to determine when recovery is
complete.
For information about the options you can use, see os_recover_options on
page 289.
os_recover::stop_recover()
void stop_recover();
Stops the recovery process by waiting for the recover to complete before returning.
After calling stop_recover(), call os_recover::get_status() to verify that the
recovery was successful.
288
C++ A P I Reference
Chapter 2: Class Library
os_recover_options
The os_recover_options class specifies data members that must be set in order for
an instance of the os_recover class to recover ObjectStore databases. An instance of
the os_recover_options class is used as an argument when starting the recovery
process. See also os_recover on page 287 for more information on the os_recover
class.
For more information on using a command-line utility to recover databases, see
osrecovr in Managing ObjectStore.
Required
header files
Programs using the os_recover_options class must include <ostore/ostore.hh>,
followed by <ostore/dbutil.hh>.
Public data
members
The os_recover_options class has the following public data members:
os_boolean flag_auto_commits;
os_boolean flag_no_recursive;
os_boolean flag_list_contents;
os_boolean flag_permissions;
os_unsigned_int32 network_timeout;
os_unsigned_int32 send_buffer_size_in_KB;
os_unsigned_int32 n_archive_files;
os_unsigned_int32 n_translate_pairs;
os_backrest_verification_hook verification_hook;
void * verification_hook_context;
const char* import_file;
const char* recover_date;
const char* recover_time;
const char** archive_files;
const char** translate_paths;
The following describes the public data members:
flag_auto_commits
When true, applies each archive log snapshot and
each backup image in its own transaction.
Default is false, all changes are applied in a single
transaction.
flag_no_recursive
If a directory is specified as a target for a recover
operation, setting this to true limits the recover
operation to databases contained in the named
directory.
Default is false; all databases in the directory and
its subdirectory will be recovered.
flag_list_contents
Setting this to true will only display all databases
contained in the specified archive files when
restore is started.
Default is false.
flag_permissions
Setting this to true causes recover to restore
database permissions for the rawfs stored in the
archive log file for the database being recovered.
Default is false.
Release 6.3
289
os_recover_options
network_timeout
Sets the timeout value in seconds that the
recovery process will wait for osserver to
respond.
Default is 10 hours.
send_buffer_size_in_KB
Specifies the buffer size in kilobytes when
sending recovered data to osserver. The
maximum value is 1024KB
Default is 512KB, which is also the minimum
value.
n_archive_files
Specifies the number of archive log files listed in
the archive_files array.
Default is zero; the import_file option must be
set instead.
n_translate_pairs
Specifies the number of pairs of database paths
listed in the translate_paths array.
Default is zero
verification_hook
Specifies a pointer to a user defined function in
the format:
os_boolean my_function(
const char * previous_image,
const char * current_image,
void* context)
where previous_image is the ID from the
previous backup image applied to the archive set,
current_image is the ID from the current archive
image, and context is user-specified data (see
the verification_hook_context option,
below).
This function is called to ensure that the previous
image has been applied before proceeding with
the current image. For example, the current
archive image is based on a previous backup
image that should be restored before running
recovery on the current image.
The format of the images are:
current_image "ID:
20021105135832.[2158298816,349722884,207
3045581].osarchiv"
previous_image "ID:
20021105135831.[2158298816,349657348,207
3045217].0.osbackup"
If the previous image has been applied, the
function should return 0 to continue processing.
A return of -1 will abort recovery.
Default is NULL, no function defined. The
verification message is sent to stdout.
290
C++ A P I Reference
Chapter 2: Class Library
verification_hook_context
The value of this pointer is passed to
verification_hook through the context calling
argument. This data member should point to any
user data that will be needed within the hook.
Default is NULL.
import_file
Specifies the name of a file that contains a list of
archive files or backup images from which to
recover specified databases. If you specify a
hyphen (-) as the import_file name, the list
read from standard input.
Default is NULL.
recover_date
Specifies a date in the current locale — for
example, mm/dd/yy in the United States.
Recovery rolls forward all database changes
committed before or on this date
Default is NULL; roll forward to the last snapshot
taken.
recover_time
Specifies a recover-to time in HH:MM:SS format.
Recovery rolls forward all database changes
committed before or at this time.
Default is NULL; roll forward to the last snapshot
taken.
archive_files
Specifies an array of archive log files from which
to recover committed database changes made
since the last backup. The number of archive_files
must correspond to the number specified in n_
archive_files.
Default is NULL and the import_file option
must be set instead.
translate_paths
Specifies an array of pairs of path names. The first
path name in the pair indicates the source of the
database as recorded in the archive log or backup
image. The second path name indicates the
target; that is, the path name for the database
after it is recovered. Each path name can be a
directory or a single database. However, you
cannot specify a directory as the source and a
database as the target. The number of
translate_paths pairs must correspond to the
number of pairs specified in n_translate_
pairs.
Default is NULL.
Member
functions
Release 6.3
The following functions are public members of the os_recover_options class:
291
os_recover_options
os_recover_options::os_recover_options()
os_recover_options();
Constructs the os_recover_options class and sets all options to their default
values.
os_recover_options::~os_recover_options()
~os_replicator_options() {}
Performs internal cleanup.
os_recover_options::reset()
void reset();
Resets all options back to their default values.
292
C++ A P I Reference
Chapter 2: Class Library
os_Reference<T>
template <class T>
class os_Reference : public os_reference_internal
ObjectStore references provide an alternative to using regular pointers to persistent
memory. Like soft pointers, references reduce address space usage by deferring the
reservation of address space for the reference’s referent until the reference is
dereferenced. See Controlling Address Space Reservation in Chapter 1 of the
Advanced C++ A P I User Guide.
Use soft pointers instead of ObjectStore references if possible. Use instances of os_
Reference<T> only in place of top-level pointers or pointers in top-level arrays.
References are implemented in terms of soft pointers. See Using ObjectStore Soft
Pointers in Chapter 1 of the Advanced C++ A P I User Guide.
os_Reference<T> defines constructors, assignment and conversion operators,
operator ->(), resolve(), and get_os_typespec(). Other operations are
inherited from the base class; see os_reference_internal on page 301.
The template parameter is the referent type — the type of object referred to by the
reference.
If you use a reference type whose referent type is not a class, you must call the macro
OS_REFERENCE_NOCLASS() on page 484, passing the referent type.
If a reference refers to an object in a database that is not open, ObjectStore opens the
database automatically when the object is accessed (unless the autoopen mode is
auto_open_disable). The mode in which the database is opened is determined by
the value of objectstore::get_auto_open_mode().
In some cases, comparing two references has a result different from comparing the
corresponding pointers. See basic_undo on page 52 for more information.
os_Reference<T>::get_os_typespec()
static os_typespec* get_os_typespec( );
Returns an os_typespec* for the class os_Reference.
Release 6.3
293
os_Reference<T>
os_Reference<T>::operator =()
os_Reference<T>& operator =(
const os_Reference<T>&
);
Establishes the referent of the right operand as the referent of the left operand.
os_Reference<T> &operator =(const T*);
Establishes the object pointed to by the right operand as the referent of the left
operand. If the right operand is 0, the left operand becomes a null reference.
os_Reference<T>::operator !()
os_boolean operator ! () const;
Returns nonzero if the reference is NULL— that is, has no current referent.
os_Reference<T>::operator T*()
operator T*( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
os_Reference<T>::operator –>()
T* operator –>( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
os_Reference<T>::os_Reference()
os_Reference();
Constructs a null reference.
os_Reference(T* hard_ptr);
Constructs a reference with the same referent as the specified hard pointer. If hard_
ptr is 0, constructs a null reference.
os_Reference(os_Reference<T> const& ref);
Constructs a reference with the same referent as the specified reference. If the
specified reference is NULL, constructs a null reference.
os_Reference<T>::resolve()
T* resolve( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
294
C++ A P I Reference
Chapter 2: Class Library
os_Reference_cross_session<T>
template <class T>
class os_Reference_cross_session : public os_reference_cross_session
Instances of the class os_Reference_cross_session<T> can be used to reference
persistent data across sessions. Cross-session references are valid under a wider
array of circumstances than are pointers to persistent storage and are always valid
across transaction boundaries.
Once the object referred to by a cross-session reference is deleted, use of the reference
accesses arbitrary data and might cause a segmentation violation.
The template parameter is the referent type — the type of object referred to by the
reference.
If you use a reference type whose referent type is not a class, you must call the macro
OS_REFERENCE_NOCLASS() on page 484, passing the referent type.
os_Reference_cross_session<T> defines constructors, assignment and
conversion operators, operator ->(), resolve(), and get_os_typespec(). Other
operations are inherited from the base class; see os_reference_cross_session on
page 297.
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_Reference_cross_session<T>::get_os_typespec()
static os_typespec* get_os_typespec( );
Returns an os_typespec* for the class os_Reference_cross_session.
os_Reference_cross_session<T>::operator =()
os_Reference_cross_session<T>& operator =(
const os_Reference_cross_session<T>& right_arg);
Establishes right_arg as the referent of the left operand.
Overloadings
os_Reference_cross_session<T> &operator =(const T* right_arg);
os_Reference_cross_session<T> &operator =(
const os_soft_pointer<void>& right_arg);
os_Reference_cross_session<T>::operator T*()
operator T*( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
Release 6.3
295
os_Reference_cross_session<T>
os_Reference_cross_session<T>::operator –>()
T* operator –>( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
os_Reference_cross_session<T>::os_Reference_cross_session()
os_Reference_cross_session();
Constructs a null reference.
os_Reference_cross_session(T* hard_ptr);
Constructs a reference with the same referent as the specified hard pointer. If hard_
ptr is 0, constructs a null reference.
os_Reference_cross_session(os_Reference_cross_session<T> const&
ref);
Constructs a reference with the same referent as the specified reference. If the
specified reference is NULL, constructs a null reference.
os_Reference_cross_session<T>::resolve()
T* resolve( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
296
C++ A P I Reference
Chapter 2: Class Library
os_reference_cross_session
This class serves as base class to os_Reference_cross_session<T>. It defines
comparison operators and hash, dump, and load functions. See os_Reference_
cross_session<T> on page 295 for more information.
Note
The os_reference_cross_session class is internal and should not be instantiated.
It is described here for documentation purposes only.
Cross-session references are valid under a wider array of circumstances than are
pointers to persistent storage and are always valid across transaction boundaries.
Once the object referred to by a cross-session reference is deleted, use of the reference
accesses arbitrary data and might cause a segmentation violation.
You can create a cross-session reference by initializing a variable of type os_
Reference_cross_session<T> with the pointer or by assigning the pointer to a
variable of types os_Reference_cross_session<T> (implicitly invoking the
conversion constructor os_Reference_cross_session::os_Reference_cross_
session(void*)). In general a pointer can be used anywhere an os_Reference_
cross_session is expected, and the conversion constructor will be invoked.
part* p = . . .;
os_reference_cross_session part_ref = a_part;
When an os_Reference_cross_session<T> is cast to a pointer-to-referent_type
(that is, pointer to the type of object referenced by the os_Reference_cross_
session<T>), os_Reference_cross_session::operator void*() is implicitly
invoked, returning a valid pointer to the object referenced by the os_Reference_
cross_session<T>.
printf("%d\n", (part*)(part_ref)->part_id);
In some cases, comparing two cross-session references has a different result from
comparing the corresponding pointers. Consider, for example, == comparisons of
hard pointers, where the referent type of one operand is a base class of the referent
type of the other operand. Even though the hard pointers might have different
values, the result is nevertheless always 1 because of the pointer adjustment
described in Section 10.3c of Ellis and Stroustrup’s Annotated C++ Reference Manual.
In contrast, for such an == comparison of references, the result might not be 1
because ObjectStore does not perform the pointer adjustment described in Section
10.3c of the C++ Annotated Reference Manual.
Each instance of os_Reference_cross_session stores a relative pathname to
identify the referent database. The pathname is relative to the lowest common
directory in the pathnames of the referent database and the database containing the
reference. For example, if a reference stored in /A/B/C/db1 refers to data in
/A/B/D/db2, the lowest common directory is A/B, so the relative pathname
../../D/db2 is used.
Type definitions
Release 6.3
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.
297
os_reference_cross_session
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_reference_cross_session::dump()
char* dump() const;
Returns a heap-allocated text string representing the specified reference.
os_reference_cross_session::get_database()
os_database* get_database( ) const;
Returns a pointer to the database containing the referent of this.
os_reference_cross_session::load()
void load(const char* dump_str);
The dump_str argument is assumed to be the result of a call to a compatible dump
function.
The exception err_reference_syntax is signaled if dump_str is not in the expected
format.
os_reference_cross_session::operator =()
os_reference_cross_session& operator =(
const os_reference_cross_session& right_arg);
Establishes right_arg as the referent of the left operand.
Overloadings
os_reference_cross_session& operator =(
const void* right_arg);
os_reference_cross_session& operator =(
os_soft_pointer<void>& right_arg);
os_reference_cross_session::operator ==()
os_boolean operator ==(
os_reference_cross_session const& right_arg) const;
Returns 1 if the this argument and right_arg have the same referent; returns 0
otherwise.
os_reference_cross_session::operator !()
os_boolean operator !=(
os_reference_cross_session const& right_arg) const;
Returns 1 if right_arg is pointing to NULL; returns 0 otherwise.
os_reference_cross_session::operator !=()
os_boolean operator !=(
os_reference_cross_session const& right_arg) const;
Returns 1 if the this argument and right_arg have different referents; returns 0
otherwise.
298
C++ A P I Reference
Chapter 2: Class Library
os_reference_cross_session::operator <()
os_boolean operator <(
os_reference_cross_session const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes the referent of right_arg, and a return value of 0 indicates that
it does not. Otherwise, the results are undefined.
os_reference_cross_session::operator >()
os_boolean operator >(
os_reference_cross_session const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows the referent of right_arg, and a return value of 0 indicates that it
does not. Otherwise, the results are undefined.
os_reference_cross_session::operator <=()
os_boolean operator <=(
os_reference_cross_session const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes or is the same as the referent of right_arg, and a return value of
0 indicates that it does not precede it or is not the same. Otherwise, the results are
undefined.
os_reference_cross_session::operator >=()
os_boolean operator >=(
os_reference_cross_session const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows or is the same as the referent of right_arg, and a return value of
0 indicates that it does not follow it or is not the same. Otherwise, the results are
undefined.
os_reference_cross_session::os_reference_cross_session()
os_reference_cross_session(void* ptr);
Constructs a cross-session reference to substitute for ptr.
os_reference_cross_session::~os_reference_cross_session()
~os_reference_cross_session();
Cleans up internal data structures.
Release 6.3
299
os_reference_cross_session
os_reference_cross_session::resolve()
void* resolve( ) const;
Returns a hard pointer with the same referent as this reference. Returns 0 if this is
a null reference.
err_reference_not_found is signaled if the referent has been deleted.
300
C++ A P I Reference
Chapter 2: Class Library
os_reference_internal
This class serves as the base class to os_Reference<T>. It defines comparison
operators, and hash, dump, and load functions. See os_Reference<T> on page 293
for more information.
Note
The os_reference_internal class is internal and should not be instantiated. It is
described here for documentation purposes only.
In some cases, comparing two references has a different result from comparing the
corresponding pointers. Consider, for example, == comparisons of hard pointers, in
which the referent type of one operand is a base class of the referent type of the other
operand. Even though the hard pointers might have different values, the result is
nevertheless always 1 because of the pointer adjustment described in Section 10.3c
of Ellis and Stroustrup’s Annotated C++ Reference Manual. In contrast, for such an ==
comparison of references, the result might not be 1 because ObjectStore does not
perform the pointer adjustment described in Section 10.3c of the C++ Annotated
Reference Manual.
os_reference_internal::dump()
char* dump() const;
Returns a heap-allocated text string representing the specified reference.
Overloading
The following overloading is supported:
char* dump(const char* db_str) const;
Returns a heap-allocated text string representing the specified reference. However,
unlike the string returned by the char * os_reference_internal::dump(void)
function, this string does not contain an absolute database path. The returned string
is intended to be used as the dump_str argument of a reference load function of the
form load(const char* dump_str, os_database* db). It is the responsibility of
the caller of load() to ensure that the db argument passed to the load function is the
same as the database of the dumped reference. It is the user’s responsibility to delete
the returned string when it is no longer needed.
This operation is useful in those applications in which you do not want the overhead
of storing the absolute database path in the dumped strings.
os_reference_internal::get_database()
os_database* get_database( ) const;
Returns a pointer to the database containing the referent of this.
os_reference_internal::get_database_key()
char* get_database_key(const char* dump_str);
Returns a heap-allocated string containing the database_key component of the
string dump_str. The dump_str argument must have been generated using the dump
Release 6.3
301
os_reference_internal
operation. Otherwise, the exception err_reference_syntax is signaled. It is the
user’s responsibility to delete the returned string when it is no longer needed.
os_reference_internal::hash()
os_unsigned_int32 hash( ) const;
Returns an integer suitable for use as a hash table key. If two references refer to the
same object, hash() performed on one reference returns the same value as hash
performed on the other reference. In other words, hash() ensures that coreferential
references hash to the same value.
os_reference_internal::load()
void load(const char* dump_str);
The dump_str argument is assumed to be the result of a call to a compatible dump
function.
void load(const char* dump_str, const os_database* db);
The dump_str argument is assumed to be the result of a call to a compatible dump
function. It is the responsibility of the caller of load() to ensure that the db argument
passed to the load function is the same as the database of the originally dumped
reference.
The loaded reference refers to the same object as the reference used to dump the
string as long as the db argument is the same as the database of the dumped
reference.
The exception err_reference_syntax is signaled if dump_str is not in the expected
format.
os_reference_internal::operator ==()
os_boolean operator ==(os_reference_internal const&) const;
Returns 1 if the arguments have the same referent; returns 0 otherwise.
os_reference_internal::operator !()
os_boolean operator !(os_reference_internal const&) const;
Returns 1 if the argument is a null reference; returns 0 otherwise.
os_reference_internal::operator !=()
os_boolean operator !=(os_reference_internal const&) const;
Returns 1 if the arguments have different referents; returns 0 otherwise.
os_reference_internal::operator <()
os_boolean operator <(os_reference_internal const&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
302
C++ A P I Reference
Chapter 2: Class Library
argument precedes the referent of the second, and a return value of 0 indicates that
it does not. Otherwise, the results are undefined.
os_reference_internal::operator >()
os_boolean operator >(os_reference_internal const&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
argument follows the referent of the second, and a return value of 0 indicates that it
does not. Otherwise, the results are undefined.
os_reference_internal::operator <=()
os_boolean operator <=(os_reference_internal const&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
argument precedes or is the same as the referent of the second, and a return value of
0 indicates that it does not precede it or is not the same. Otherwise, the results are
undefined.
os_reference_internal::operator >=()
os_boolean operator >=(os_reference_internal const&) const;
If the first argument and second argument refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the first
argument follows or is the same as the referent of the second, and a return value of
0 indicates that it does not follow it or is not the same. Otherwise, the results are
undefined.
os_reference_internal::~os_reference_internal()
~os_reference_internal();
Cleans up internal data structures.
os_reference_internal::resolve()
void* resolve( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
Release 6.3
303
os_Reference_protected<T>
os_Reference_protected<T>
template <class T>
class os_Reference_protected : public os_reference_protected_internal
ObjectStore references support referential integrity. They provide an alternative to
using regular pointers to persistent memory. If you attempt to dereference a
protected reference and the referent has been deleted, err_reference_not_found is
thrown.
Like soft pointers, protected references reduce address space usage by deferring the
reservation of address space for the reference’s referent until the reference is
dereferenced. See Controlling Address Space Reservation in Chapter 1 of the
Advanced C++ A P I User Guide.
os_Reference_protected<T> defines constructors, assignment and conversion
operators, operator ->(), resolve(), and get_os_typespec(). Other operations
are inherited from the base class; see os_reference_protected_internal on
page 306.
The referent type parameter (T) indicates the type of the object referred to by a
reference. If you use a protected reference type whose referent type is not a class, you
must call the macro OS_REFERENCE_PROTECTED_NOCLASS() on page 485, passing the
referent type.
If a reference refers to an object in a database that is not open, ObjectStore opens the
database automatically when the object is accessed (unless the autoopen mode is
auto_open_disable). The mode in which the database is opened is determined by
the value of objectstore::get_auto_open_mode().
In some cases, comparing two references has a result different from comparing the
corresponding pointers. See os_reference_protected_internal on page 306 for
more information.
os_Reference_protected<T>::get_os_typespec()
static os_typespec* get_os_typespec( );
Returns an os_typespec* for the class os_Reference_protected<T>.
os_Reference_protected<T>::operator =()
os_Reference_protected<T>& operator =(
const os_Reference_protected<T>&
);
Establishes the referent of the right operand as the referent of the left operand.
Overloadings
The following overloading is supported:
os_Reference_protected<T>& operator =(const T*);
Establishes the object pointed to by the right operand as the referent of the left
operand. If the right operand is 0, the left operand becomes a null reference.
304
C++ A P I Reference
Chapter 2: Class Library
os_Reference_protected<T>::operator T*()
operator T*( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
err_reference_not_found is signaled if the referent has been deleted.
os_Reference_protected<T>::operator –>()
T* operator –>( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
err_reference_not_found is signaled if the referent has been deleted.
os_Reference_protected<T>::os_Reference_protected()
os_Reference_protected();
Constructs a null reference.
Overloadings
The following overloadings are supported:
os_Reference_protected(T* hard_ptr);
Constructs a reference with the same referent as the specified hard pointer. If hard_
ptr is 0, constructs a null reference.
os_Reference_protected(os_Reference_protected<T> const& ref);
Constructs a reference with the same referent as the specified reference. If the
specified reference is NULL, constructs a null reference.
os_Reference_protected<T>::resolve()
T* resolve( ) const;
Returns a hard pointer with the same referent as the this reference. Returns 0 if this
is a null reference.
err_reference_not_found is signaled if the referent has been deleted.
Release 6.3
305
os_reference_protected_internal
os_reference_protected_internal
This class serves as base class to os_Reference_protected<T>. It defines
comparison operators and hash, dump, and load functions. See os_Reference_
protected<T> on page 304 for more information.
Note
The os_reference_protected_internal class is internal and should not be
instantiated. It is described here for documentation purposes only.
In some cases, comparing two references has a different result from comparing the
corresponding pointers. Consider, for example, == comparisons of hard pointers,
where the referent type of one operand is a base class of the referent type of the other
operand. Even though the hard pointers might have different values, the result is
nevertheless always 1 because of the pointer adjustment described in Section 10.3c
of Ellis and Stroustrup’s C++ Annotated Reference Manual. In contrast, for such an ==
comparison of references, the result might not be 1 because ObjectStore does not
perform the pointer adjustment described in Section 10.3c of the C++ Annotated
Reference Manual.
os_reference_protected_internal::deleted()
os_boolean deleted() const;
Returns nonzero if the referent of this has been deleted. Returns 0 otherwise.
os_reference_protected_internal::dump()
char* dump() const;
Returns a heap-allocated text string representing the specified reference.
Overloading
The following overloading is supported:
char* dump(const char* db_str) const;
Returns a heap-allocated text string representing the specified reference. However,
unlike the string returned by the char* os_reference_protected_
internal::dump(void) function, this string does not contain an absolute database
path. The returned string is intended to be used as the dump_str argument of a
reference load function of the form load(const char* dump_str, os_database*
db). It is the responsibility of the caller of load() to ensure that the db argument
passed to the load function is the same as the database of the dumped reference. It is
the user’s responsibility to delete the returned string when it is no longer needed.
This overloading is useful in applications for which you do not want the overhead of
storing the absolute database path in the dumped strings.
os_reference_protected_internal::get_database()
os_database* get_database( ) const;
Returns a pointer to the database containing the referent of this.
306
C++ A P I Reference
Chapter 2: Class Library
os_reference_protected_internal::get_database_key()
char* get_database_key(const char* dump_str);
Returns a heap-allocated string containing the database_key component of the
string dump_str. The dump_str argument must have been generated using the dump
operation. Otherwise, the exception err_reference_syntax is signaled. It is the
user’s responsibility to delete the returned string when it is no longer needed.
os_reference_protected_internal::hash()
os_unsigned_int32 hash( ) const;
Returns an integer suitable for use as a hash table key. If two references refer to the
same object, hash() performed on one reference returns the same value that hash()
performed on the other reference. In other words, hash() ensures that coreferential
references hash to the same value.
os_reference_protected_internal::load()
void load(const char* dump_str);
The dump_str argument is assumed to be the result of a call to a compatible dump
function.
Overloadings
The following overloading is supported:
void load(const char* dump_str, const os_database* db);
The dump_str argument is assumed to be the result of a call to a compatible dump
function. It is the responsibility of the caller of load() to ensure that the db argument
passed to the load function is the same as the database of the originally dumped
reference.
The loaded reference refers to the same object as the reference used to dump the
string if the db argument is the same as the database of the dumped reference.
The exception err_reference_syntax is signaled if dump_str is not in the expected
format.
os_reference_protected_internal::operator ==()
os_boolean operator ==(
os_reference_protected_internal const& right_arg) const;
Returns 1 if the this argument and right_arg have the same referent; returns 0
otherwise.
os_reference_protected_internal::operator !()
os_boolean operator !(
os_reference_protected_internal const& arg) const;
Returns 1 if the argument is a null reference; returns 0 otherwise.
os_reference_protected_internal::operator !=()
os_boolean operator !=(
Release 6.3
307
os_reference_protected_internal
os_reference_protected_internal const& right_arg) const;
Returns 1 if the this argument and right_arg have different referents; returns 0
otherwise.
os_reference_protected_internal::operator <()
os_boolean operator <(
os_reference_protected_internal const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes the referent of right_arg, and a return value of 0 indicates that
it does not. Otherwise, the results are undefined.
os_reference_protected_internal::operator >()
os_boolean operator >(
os_reference_protected_internal const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows the referent of right_arg, and a return value of 0 indicates that it
does not. Otherwise, the results are undefined.
os_reference_protected_internal::operator <=()
os_boolean operator <=(
os_reference_protected_internal const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes or is the same as the referent of right_arg, and a return value of
0 indicates that it does not precede it or is not the same. Otherwise, the results are
undefined.
os_reference_protected_internal::operator >=()
os_boolean operator >=(
os_reference_protected_internal const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows or is the same as the referent of right_arg, and a return value of
0 indicates that it does not follow it or is not the same. Otherwise, the results are
undefined.
os_reference_protected_internal::~os_reference_protected_
internal()
~os_reference_protected_internal();
Cleans up internal data structures.
308
C++ A P I Reference
Chapter 2: Class Library
os_reference_protected_internal::resolve()
void* resolve( ) const;
Returns a hard pointer with the same referent as this reference. Returns 0 if this is
a null reference.
err_reference_not_found is signaled if the referent has been deleted.
Release 6.3
309
os_reference_type
os_reference_type
class os_reference_type : public os_pointer_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a C++ reference
type. This class is derived from os_pointer_type. Performing os_pointer_
type::get_target_type( ) on an os_reference_type results in the reference
type’s target type.
os_reference_type::create()
static os_reference_type& create(os_type* target);
The argument initializes the attribute target.
310
C++ A P I Reference
Chapter 2: Class Library
os_relationship_member_variable
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a relationship
(inverse) member. This class is derived from os_member_variable.
os_relationship_member_variable::get_related_class()
const os_class_type&get_related_class( ) const;
Returns the class at the target end of the relationship.
Overloadings
The following is the non-const overloading of this function:
os_class_type& get_related_class( );
os_relationship_member_variable::get_related_member()
const os_relationship_member_variable& get_related_member( ) const;
Returns the inverse of the specified relationship member.
Overloadings
The following is the non-const overloading of this function:
os_relationship_member_variable& get_related_member( );
Release 6.3
311
os_release_cluster_pointer
os_release_cluster_pointer
The os_release_cluster_pointer class enables you to release pointers to objects
of the class os_cluster. To do so, declare an automatic variable of the class os_
release_cluster_pointer, giving its constructor a pointer to an os_cluster
object. When the variable goes out of scope, its destructor releases the pointer.
For information about releasing pointers to os_cluster objects, see os_
cluster::release_pointer() on page 133 and the C++ A P I User Guide.
312
C++ A P I Reference
Chapter 2: Class Library
os_release_database_pointer
The os_release_database_pointer class enables you to release pointers to objects
of the class os_database. To do so, declare an automatic variable of the class os_
release_database_pointer, giving its constructor a pointer to an os_database
object. When the variable goes out of scope, its destructor releases the pointer.
For information about releasing pointers to os_database objects, see os_
database::release_pointer() on page 166 and the C++ A P I User Guide.
Release 6.3
313
os_release_root_pointer
os_release_root_pointer
The os_release_root_pointer class enables you to release pointers to objects of
the class os_database_root. To do so, declare an automatic variable of the class os_
release_root_pointer, giving its constructor a pointer to an os_database_root
object. When the variable goes out of scope, its destructor releases the pointer.
For information about releasing pointers to os_database_root objects, see os_
database_root::release_pointer() on page 173 and the C++ A P I User Guide.
314
C++ A P I Reference
Chapter 2: Class Library
os_release_segment_pointer
The os_release_segment_pointer class enables you to release pointers to objects
of the class os_segment. To do so, declare an automatic variable of the class os_
release_segment_pointer, giving its constructor a pointer to an os_segment
object. When the variable goes out of scope, its destructor releases the pointer.
For information about releasing pointers to os_segment objects, see os_
segment::release_pointer() on page 358 and the C++ A P I User Guide.
Release 6.3
315
os_replicator
os_replicator
The os_replicator class provides the means to control database replication from an
application. Replica databases are continuously updated MVCC copies of
ObjectStore databases. When updating the replica databases, the os_replicator
copies only changed data.
For more information on replicating databases, see osreplic in Managing
ObjectStore.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/dbutil.hh>.
os_replicator::os_replicator()
os_replicator(const char* replica_ID)
Constructs an os_replicator. The unique string identifies this replica during
logging operations, as described in os_dbutil::start_backrest_logging() on
page 191.
os_replicator::~os_replicator()
~os_replicator();
Destructor function.
os_replicator::change_time_interval()
void change_time_interval(os_unsigned_int32 n_seconds);
Change the time between snapshots where time is in seconds.
os_replicator::get_statistics()
void get_statistics(os_replicator_statistic_info & info);
Returns replication statistics in the form of an instance of the os_replicator_
statistic_info class. See os_replicator_statistic_info on page 321 for more
information on the os_replicator_statistic_info class.
316
C++ A P I Reference
Chapter 2: Class Library
os_replicator::get_status()
os_int32 os_replicator::get_status()
Returns the current status of the replica. The possible return values are:
Return Value Meaning
-1
The replication process is still running.
0
The replication process has either completed successfully or has
not yet started.
1
The replication process has failed. Check the backrest log for
additional information.
os_replicator::reset_statistics()
void reset_statistics();
Resets the meters used for statistics. Replication must be stopped before calling this
function.
os_replicator::start_replicator()
void start_replicator(os_replicator_options & options);
Starts the os_replicator using the specified os_replicator_options. For
information about the options you can use, see os_replicator_options on
page 318.
os_replicator::stop_replicator()
void stop_replicator();
Stop replication after completing current replication.
Release 6.3
317
os_replicator_options
os_replicator_options
The os_replicator_options class specifies how the os_replicator copies
ObjectStore databases. An instance of the os_replicator_options class is used as
an argument to the replicator’s start_replicator() function. See also os_
replicator on page 316 for more information on the os_replicator class.
For more information on using a command-line utility to replicate databases, see
osreplic in Managing ObjectStore.
Required
header files
Programs using the os_replicator_options class must include
<ostore/ostore.hh>, followed by <ostore/dbutil.hh>.
Public data
members
The os_replicator_options class has the following public data members:
os_boolean flag_permissions;
os_boolean flag_recursive;
os_boolean flag_verbose;
os_boolean flag_exclusive;
os_boolean flag_compression;
os_unsigned_int32 server_buf_size_in_KB;
os_unsigned_int32 send_buf_size_in_KB;
os_unsigned_int32 receive_buf_size_in_KB;
os_unsigned_int32 time_interval;
os_unsigned_int32 network_timeout;
os_unsigned_int32 n_rep_db_pairs;
const char * import_file;
const char * archive_record_file;
const char ** source_pathnames;
const char ** target_pathnames;
Deleting all char* options is the caller’s responsibility.
Each pathname in the source_pathname array must correspond to the pathname in
the target_pathname array.
The following describes the public data members:
flag_permissions
Setting this option to true causes the replication
process to copy database permissions to the target
rawfs databases.
Default is false; permissions are not copied.
flag_recursive
Instructs the replication process to descend into any
rawfs directories specified in the source_pathnames
array, adding all rawfs databases found to the list of
databases to be replicated. This option has no effect
when replicating file databases; you must explicitly
specify each file database.
Default is false; only databases in the specified
directory will be replicated.
flag_verbose
Setting this option to true enables verbose output.
Default is false; verbose output is disable.
318
C++ A P I Reference
Chapter 2: Class Library
flag_exclusive
Setting this option to true opens the target database
in exclusive mode, which prohibits clients from
using the target databases until the replicator process
is stopped.
Default is false; databases are opened in nonexclusive mode.
flag_compression
Setting this option to true compresses the replicated
data from osserver; this reduces the amount of data
transferred to the replication application.
Default is false; no compression takes place.
server_buf_size_in_KB
Specifies the size of the buffer used by the ossevers
contacted by the replicator process.
Default is 1204KB.
send_buf_size_in_KB
Specifies the buffer size in kilobytes when sending
replicated data to osserver. The maximum value is
1024KB and the minimum value is 512KB.
Default is 512KB.
receive_buf_size_in_KB
Specifies the buffer size in kilobytes when receiving
replicated data from osserver. The maximum value
is 102400KB and the minimum value is 256KB.
Default is 256KB.
time_interval
Specifies in seconds an integer used by the replicator
process as the interval between snapshots. Setting
this option to 0 (zero) results in the replication of one
snapshot after which the replicator process stops.
Default is 600 seconds.
network_timeout
Specifies the timeout value in seconds that the
replicator process will wait for osserver to respond.
Default is 10 hours.
n_rep_db_pairs
Specifies the number of pairs in the source_
pathnames and target_pathnames arrays.
Default is 0 (zero); the import_file option must be
set instead.
import_file
Specifies the name of an input file containing
databases and directories to be replicated. Each line
in the input file must consist of a source path
followed by a target path. If a directory is specified,
its contents are added to the source set.
Default is NULL.
archive_record_file
Release 6.3
Required. This specifies the archive record file, a file
that contains information about those databases that
have been replicated and when they were replicated.
This information is used to determine the clusters
within a database that have been modified since the
last time replication ran; only modified clusters are
replicated.
319
os_replicator_options
source_pathnames
Specifies an array of source database pathnames to
be replicated. Entries in this array must have a
corresponding entry in the target_pathnames array.
Default is NULL; the import_file option must be set
instead.
target_pathnames
Specifies an array of target database pathnames.
Entries in this array must correspond to the entries in
the source_pathnames array.
Default is NULL; the import_file option must be set
instead.
os_replicator_options::os_replicator_options()
os_replicator_options();
Constructs the os_replicator_options class and sets all options to their default
values.
os_replicator_options::~os_replicator_options()
~os_replicator_options() { }
Destructor function for os_replicator_options.
os_replicator_options::reset()
void reset();
Resets all options back to their default values.
320
C++ A P I Reference
Chapter 2: Class Library
os_replicator_statistic_info
The os_replicator_statistic_info class contains information about an os_
replicator. For more information about the os_replicator class, see os_
replicator on page 316.
For more information on using a command-line utility to replicate databases, see
osreplic in Managing ObjectStore.
Required
header files
Programs using the os_replicator_statistic_info class must include
<ostore/ostore.hh>, followed by <ostore/dbutil.hh>.
Public data
members
The os_replicator_statistic_info class has the following public data members:
float compress_decrease_percent;
os_unsigned_int32 n_snapshots;
os_unsigned_int32 n_snapshots_with_data;
os_unixtime_t time_last_snapshot;
os_unsigned_int32 n_KB_last_snapshot;
os_unsigned_int32 snapshot_time;
os_unsigned_int32 average_KB_per_snapshot;
os_unsigned_int32 average_time;
os_unsigned_int32 n_snapshot_resets;
os_unsigned_int32 n_backup_and_restore_overlaps;
The public data members are described as follows:
compress_decrease_percent
Decrease percentage from data compression.
n_snapshots
Number of snapshots taken.
n_snapshots_with_data
Number of snapshots that data was replicated.
time_last_snapshot
Time of last snapshot, regardless if data was
replicated (UTC).
n_KB_last_snapshot
Last snapshot with replication, number of KB
replicated.
snapshot_time
How many seconds last snapshot with replication
took.
average_KB_per_snapshot
Average amount of KB processed per snapshot.
average_time
In seconds, average amount of time per snapshot.
n_snapshot_resets
Number of times the backup was restarted by
osserver.
n_backup_and_restore_
overlaps
Number of overlaps where the backup started
before restore completed. - This can indicate that
snapshot interval is too low.
os_replicator_statistic_info::os_replicator_statistic_info()
os_replicator_statistic_info();
The constructor function for the os_replicator_statistic_info class.
Release 6.3
321
os_replicator_statistic_info
os_replicator_statistic_info::~os_replicator_statistic_info()
~os_replicator_statistic_info();
The destructor function for the os_replicator_statistic_info class.
os_replicator_statistic_info::format_and_print_statistics()
void format_and_print_statistics();
Format and print statistic information.
os_replicator_statistic_info::format_statistics()
char * format_statistics();
Statistic information is returned in a formatted string which is the caller’s
responsibility to delete.
os_replicator_statistic_info::get_replica_ID()
const char * get_replica_ID();
Returns the replica ID for which the statistics were accumulated.
322
C++ A P I Reference
Chapter 2: Class Library
os_restore
The os_restore class provides the means to perform restoration of databases from
an ObjectStore application. The ObjectStore application restores the databases from
a backup image that you create with the osbackup utility or with an ObjectStore
application that uses methods of the os_backup classes.
For more information on using a command-line utility to restore databases, see
osrestore in Managing ObjectStore.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/dbutil.hh>.
os_restore::os_restore()
os_restore(const char* restore_ID)
Constructs the necessary class for restoring databases. The restore_ID argument
should be a unique character string identifying this restore process in the backrest
log, as described in os_dbutil::start_backrest_logging() on page 191.
os_restore::~os_restore()
~os_restore();
Performs internal cleanup of the restore process. Calling ~os_restore() while the
restore process is running will abort the restore.
os_restore::get_status()
os_int32 get_status();
Returns the current status of the restore process. The possible return values are:
• -1 indicates the restore process is still running
• 0 indicates the restore process has completed successfully or has not yet started.
• 1 indicates the restore process has failed. Check the backrest log for additional
information.
Release 6.3
323
os_restore
os_restore::start_and_run_restore()
os_boolean start_and_run_restore(
os_restore_options & options);
Starts and runs the restore process to completion. The options calling argument
should have the necessary data members set. A return code of zero indicates the
restore process successfully completed. For a non-zero return code, check the
backrest log for further information. For information about the options you can use,
see os_restore_options on page 325.
os_restore::start_restore()
void start_restore(os_restore_options * options);
Starts the restore process in a separate thread and then return immediately. The
options calling argument should have the necessary data members set. After calling
start_restore() call os_restore::get_status() to determine when the restore
process is complete. For information about the options you can use, see os_restore_
options on page 325.
os_restore::stop_restore()
void stop_restore();
Stops the restore process by waiting for the restore to complete before returning.
After calling stop_restore() call os_restore::get_status() to verify that the
restore was successful.
324
C++ A P I Reference
Chapter 2: Class Library
os_restore_options
The os_restore_options class specifies data members that must be set in order for
an instance of the os_restore class to restore ObjectStore databases. An instance of
the os_restore_options class is used as an argument when starting the restore
process. See also os_restore on page 323 for more information.
For more information on a command-line utility to restore databases, see osrestore
in Managing ObjectStore.
Required
header files
Programs using the os_restore_options class must include <ostore/ostore.hh>,
followed by <ostore/dbutil.hh>.
Public data
members
The os_restore_options class has the following public data members:
os_boolean flag_no_recursive;
os_boolean flag_list_contents;
os_boolean flag_permissions;
os_unsigned_int32 network_timeout;
os_unsigned_int32 send_buffer_size_in_KB;
os_unsigned_int32 block_factor;
os_unsigned_int32 n_backup_files;
os_unsigned_int32 n_translate_pairs;
os_restore_switch_volume_hook switch_volume_hook;
void * switch_volume_hook_context;
const char * switch_volume_command;
const char ** backup_files;
const char ** translate_paths;
const char * translation_import_file;
The public data members are described as follows
flag_no_recursive
If a directory is specified as a target for restore,
setting this to true limits the restore operation to
databases contained in the named directory.
Default is false; all databases in the directory and
its subdirectory will be restored.
flag_list_contents
Setting this to true will only display all databases
contained in the specified archive files when
restore is started.
Default is false.
flag_permissions
Setting this to true causes restore to restore
database permissions for the rawfs stored in the
archive log file for the database being restored.
Default is false.
network_timeout
Sets the timeout value in seconds that restore
will wait for osserver to respond.
Default is 10 hours.
Release 6.3
325
os_restore_options
send_buffer_size_in_KB
Specifies the buffer size in kilobytes when
sending restored data to osserver. The
maximum value is 1024KB
Default is 512KB, which is also the minimum
value.
block_factor
Specifies a blocking factor to use for tape input
and output. This option applies only when you
are restoring data from a tape. The blocking
factor is in units of 512-byte blocks. The
maximum blocking factor is 512 blocks.
Default on UNIX is 126 blocks.
n_backup_files
Specifies the number of backup image files listed
in the backup_files array.
Default is zero; The import_file option must be
set instead.
n_translate_pairs
Specifies the number of pairs of database paths
listed in the translate_paths array.
switch_volume_hook
Specifies a pointer to a user-defined function in
the format:
os_boolean my_function(
os_unsigned_int32 vol_number,
void* context)
where vol_number indicates the next volume
number, and context is user-specified data (see
the switch_volume_hook_context option,
below).
This function will be called when os_restore
reaches the end of the media. The function
should signal that the next volume is needed and
return after the volume has been mounted. The
return code should be 0 to continue processing
or 1 to abort the restore.
Default is NULL; no function defined. If switch_
volume_command is not set, the prompt is
processed through stdin/stdout.
switch_volume_hook_context The value of this pointer is passed to switch_
volume_hook through the context calling
argument. This data member should point to any
user data that will be needed within the hook.
Default is NULL.
326
C++ A P I Reference
Chapter 2: Class Library
switch_volume_command
Specifies the path of a command to be executed
when the restore reaches the end of the media.
This command should mount the next volume
before returning. The exit status from this
command must be 0 or the restore operation
aborts.
Default is NULL. If switch_volume_hook is not
defined, the prompt is processed through
stdin/stdout.
backup_files
Required. Specifies an array of files or tape
devices that contains backup images from which
to restore databases. The number of backup_files
must correspond to the number specified in n_
backup_files.
translate_paths
Specifies an array of pairs of path names. The
first path name in the pair indicates the source of
the database as recorded in the backup image.
The second path name indicates the target; that
is, the path name for the database after it is
restored. Each path name can be a directory or a
single database. However, you cannot specify a
directory as the source and a database as the
target. The number of translate_paths pairs
must correspond to the number of pairs specified
in n_translate_pairs.
Default is NULL.
translation_import_file
Release 6.3
Specifies the name of a file that contains a list of
pathname pairs for translation. The first
pathname is the source database as recorded in
the backup image. The second pathname is the
target — that is, the pathname for the database
after it is restored. Each pathname can be a
directory or a single database. However, you
cannot specify a directory as the source and a
database as the target. Each line in the file should
contain one pathname only; a translation pair
should occupy two lines in the file.
327
os_restore_options
Member
functions
The following functions are public members of the os_restore_options class:
os_restore_options::os_restore_options()
os_restore_options();
Constructs the os_restore_options class and sets all options to their default
values.
os_restore_options::~os_restore_options()
~os_replicator_options() {}
Performs internal cleanup.
os_restore_options::reset()
void reset();
Resets all options back to their default values.
328
C++ A P I Reference
Chapter 2: Class Library
os_retain_address
The class os_retain_address allows an application to specify that certain address
ranges be kept assigned across calls to objectstore::release_persistent_
addresses() and top-level transactions. The os_retain_address constructor takes
a pointer to a transient pointer that the application wants to remain assigned.
A single os_retain_address instance can track modifications made to a pointer.
When the client releases address space, it iterates through all os_retain_address
instances and dereferences their ptr_to_ptrs to determine those address ranges
that should be retained. There are no error states: if ptr_to_ptr is 0 or if it points to
a pointer that does not point into persistent space, no error is signaled and no
address range is retained by the os_retain_address instance. Because address
space is reserved in 64 KB units, the amount of address space reserved by a single
os_retain_address is some multiple of 64 KB. Typically, for objects 64 KB or less,
it is just 64 KB.
os_retain_address inherits from basic_undo, so all instances must be on the stack
(correspond to automatic C++ variables). When an instance of os_retain_address
is deleted, it is removed from consideration by the client.
More than one instance of os_retain_address can refer to the same persistent
address. As long as at least one instance of os_retain_address refers to a persistent
address when the client releases addresses, that persistent address is retained.
os_retain_address::os_retain_address()
os_retain_address::os_retain_address(void** ptr_to_ptr);
Creates an os_retain_address object. The argument ptr_to_ptr is an address of a
pointer you want to retain.
os_retain_address::release()
void os_retain_address::release();
Releases the retained address specified by the this argument, allowing the os_
retain_address object to retain other addresses.
os_retain_address::retaining()
void* os_retain_address::retaining() const;
If the retained pointer points to a persistent object, this function returns the address
of the object. If the retained pointer does not point to a persistent object, this function
returns 0.
os_retain_address::set_retain()
void os_retain_address::set_retain(void** ptr_to_ptr);
Sets ptr_to_ptr to be the retained address, replacing the previously retained
address.
Release 6.3
329
os_schema
os_schema
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this abstract base class represents a
schema. The classes os_comp_schema, os_app_schema, and os_database_schema
are derived from os_schema.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_schema::find_type()
const os_type* find_type(const char *typename) const;
Returns a pointer to the type with the specified name in the specified schema. The
name can designate a class or any C++ fundamental type. All pointer types are
treated identically and result in the type for void*’s being returned. If there is no
type with the specified name, 0 is returned. For nested classes, the name must be a
fully qualified name that describes the path to the nested class, for example,
outer::inner.
os_schema::get_classes()
os_collection get_classes( ) const;
Returns a collection of the classes in the schema. Each element of the returned
collection points to a const os_class_type.
os_schema::get_kind()
enum os_schema_kind {
Compilation_schema,
Application_schema,
Database_schema
};
os_schema_kind get_kind( ) const;
Returns an enumerator indicating the kind of the specified schema.
os_schema::operator const os_app_schema&()
operator const os_app_schema&( ) const;
Provides safe conversion to const os_app_schema&. If the conversion is not
permissible, err_mop_illegal_cast is signaled.
os_schema::operator const os_comp_schema&()
operator const os_comp_schema&( ) const;
Provides safe conversion to const os_comp_schema&. If the conversion is not
permissible, err_mop_illegal_cast is signaled.
330
C++ A P I Reference
Chapter 2: Class Library
os_schema::operator const os_database_schema&()
operator const os_database_schema&( ) const;
Provides safe conversion to const os_database_schema&. If the conversion is not
permissible, err_mop_illegal_cast is signaled.
os_schema::operator os_app_schema&()
operator os_app_schema&( );
Provides safe conversion to os_app_schema&. If the conversion is not permissible,
err_mop_illegal_cast is signaled.
os_schema::operator os_comp_schema&()
operator os_comp_schema&( );
Provides safe conversion to os_comp_schema&. If the conversion is not permissible,
err_mop_illegal_cast is signaled.
os_schema::operator os_database_schema&()
operator os_database_schema&( );
Provides safe conversion to os_database_schema&. If the conversion is not
permissible, err_mop_illegal_cast is signaled.
Release 6.3
331
os_schema_evolution
os_schema_evolution
This class provides the user interface to the ObjectStore schema evolution facility.
Schema evolution refers to the changes undergone by a database’s schema during the
course of the database’s existence. It refers especially to schema changes that
potentially require changing the representation of objects already stored in the
database.
The schema evolution process has two phases:
• Schema modification: Modification of the schema information associated with the
databases being evolved
• Instance migration: Modification of any existing instances of the modified classes
Instance migration itself has two phases:
• Instance initialization
• Instance transformation
Instance initialization modifies existing instances of modified classes so their
representations conform to the new class definitions. This might involve adding or
deleting fields or subobjects, changing the type of a field, or deleting entire objects.
This phase of migration also initializes any storage components that have been
added or that have changed type.
In most cases, new fields are initialized with zeros. There is one useful exception to
this, however. In the case in which a field has changed type, and the old and new
types are assignment compatible, the new field is initialized by assignment from the
old field value. See os_schema_evolution::evolve() on page 337 for the
initialization rules.
During the initialization phase, the address of objects generally change. Even objects
whose classes are not being evolved can move, typically because a preceding object
in the same cluster changed size because its class evolved. The object will be in the
same cluster but its offsets within the cluster will be different. If the size of a top-level
object changes from less than 64 KB to 64 KB or greater, the object will be moved to
a new cluster in the same segment.
Because of these address changes, the schema evolution facility automatically
modifies all pointers to the instance so that they point to the new instance. This is
done for all pointers in the databases being evolved, including pointers contained in
instances of unmodified classes, cross-database pointers, and pointers to subobjects
of migrated instances.
During this process of adjusting pointers, ObjectStore might detect various kinds of
untranslatable pointers (see os_schema_evolution::evolve() on page 337). For
example, it might detect a pointer to the value of a data member that has been
removed in the new schema. Because the data member has been removed, the
subobject serving as value of that data member is deleted as part of instance
initialization. Any pointer to such a deleted subobject is untranslatable and is
detected by ObjectStore.
332
C++ A P I Reference
Chapter 2: Class Library
In such a case, you can provide a special handler object (see os_schema_
evolution::set_untranslatable_pointer_handler() on page 345) to process
the untranslatable pointer (for example, by changing it to NULL or simply reporting
its presence). Each time an untranslatable pointer is detected, the handler function is
executed on the pointer, and schema evolution is resumed. If you do not provide a
handler function, an exception is signaled when an untranslatable pointer is
encountered.
C++ references are treated as a kind of pointer. References to moved instances are
adjusted as described previously. Untranslatable references are detected and you
can provide a handler object to process them (see os_schema_evolution::set_
untranslatable_pointer_handler() on page 345).
Just as some pointers and references become obsolete after schema evolution, so do
some indexes and persistently stored queries. For example, the selection criterion of
a query or the path of an index might reference a removed data member. ObjectStore
detects all obsolete queries and indexes. As with untranslatable pointers, you can
handle obsolete queries or indexes by providing special handler functions for each
purpose. An obsolete index handler, for example, might create a new index by using
a path that is valid under the new schema.
If you do not supply handlers, ObjectStore signals an exception when it detects an
obsolete query or index. If you supply an obsolete query handler function that allows
the schema evolution to continue when it encounters an obsolete query, ObjectStore
internally marks the query so that subsequent attempts to use it result in the
exception err_os_query_evaluation_error.
For more information on these handlers, see os_schema_evolution::set_
obsolete_query_handler() on page 343 and os_schema_evolution::set_
obsolete_index_handler() on page 343.
Instance
transformation
phase
For some schema changes, the instance initialization phase is all that is needed. In
other cases, however, further modification of class instances or associated data
structures is required to complete the schema evolution. This further modification
generally is application dependent, so ObjectStore allows you to define your own
functions, transformer functions, to perform the task (see os_schema_
evolution::augment_pre_evol_transformers() on page 336and os_schema_
evolution::augment_post_evol_transformers() on page 336).
You associate exactly one transformer with each class whose instances you want to
be transformed. During the transformation phase of instance migration, the schema
evolution facility invokes each transformer function on each instance of the
function’s associated class, including instances that are subobjects of other objects.
Transformers are useful for updating data structures that depend on the addresses
of instances. A hash table, for example, that hashes on addresses should be rebuilt by
using a transformer. Note that you need not rebuild a data structure if the position
of an entry in the structure does not depend on the address of an object pointed to
by the entry but depends, instead, for example, on the value of some field of the
object pointed to. Such data structures are still correct after the instance initialization
phase.
Release 6.3
333
os_schema_evolution
To help you get an overall picture of the operations involved in instance initialization
for a particular evolution, the schema evolution facility allows you to obtain a task
list describing the process. The task list consists of function definitions indicating
how the instances of each class are initialized. You can generate this list without
actually invoking evolution, so you can verify your expectations concerning a
particular schema change before migrating the data (see os_schema_
evolution::task_list() on page 346).
To perform schema evolution, you make and execute an application that does the
following:
1 Calls os_schema_evolution::initialize( ). This initializes the schema
evolution facility by setting the number of threads to be used by the application,
the amount of persistent pages to prefetch, and the size of virtual address space to
use for secondary sessions.
The default number of threads is 1.5 times the number of CPUs in the system
(rounded up). You might need to decrease the number of threads when running
on a system with lots of processors but a small persistent storage region (PSR) size.
Using too many threads can cause the PSR size for the main thread to be too small,
causing address space exhaustion. It is acceptable to restart an interrupted schema
evolution while specifying a different number of threads. You can increase the
address space available to the main thread by decreasing the number of threads,
by decreasing the address_space_release_interval, or by setting the
environment variable OS_AS_SIZE to a larger number.
2 Sets various parameters if necessary by calling the os_schema_evolution::set_
xxx functions that are appropriate for your schema evolution. Examples are set_
maplet_size() and set_untranslatable_pointer_handler().
3 Specifies the name of the application schema, if necessary. This is the new schema
and is specified by making a call to os_schema_evolution::set_evolved_
schema_db_name() and/or os_schema_evolution::augment_dll_schema_db_
names(). If you do not call either of these functions, the application schema used
is the application schema of the schema evolution application itself.
4 Calls os_schema_evolution::evolve( ) or os_schema_evolution::task_
list( ).
5 Calls os_schema_evolution::shutdown( ).
The schema evolution application should not use objectstore::initialize() or
objectstore::shutdown(). The os_schema_evolution::evolve( ) function
should not be called inside a transaction.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/schmevol.hh>.
334
C++ A P I Reference
Chapter 2: Class Library
os_schema_evolution::augment_classes_to_be_removed()
static void augment_classes_to_be_removed(
const char* class_name
);
Adds the class with the specified name to the set of classes to be removed from the
schema during subsequent evolutions. This applies to evolutions initiated in the
current process. If the indicated class is actually part of the new schema, err_se_
cannot_delete_class is signaled. Note that when you remove a class, C, you must
also remove or modify any class that mentions C in its definition. Otherwise, err_
se_cannot_delete_class is signaled.
Overloadings
The following overloading is supported:
static void augment_classes_to_be_removed(
const os_collection& class_names
);
Adds the classes named by the elements of the specified collection to the set of classes
to be removed from the schema during schema evolution. This applies to evolutions
initiated during the current process after the call to this function. If the indicated
class is actually part of the new schema, err_se_cannot_delete_class is signaled.
Note that when you remove a class, C, you must also remove or modify any class that
mentions C in its definition. Otherwise, err_se_cannot_delete_class is signaled.
os_schema_evolution::augment_cluster_split_avoidance()
static void augment_cluster_split_avoidance(
const char* class_name)
This function specifies that any cluster containing objects of class_name will not be
split when the cluster size exceeds set_maximum_cluster_size(). This is useful
when a cluster contains user defined data that should not be split across clusters. For
more information on maximum cluster size, see os_schema_evolution::set_
maximum_cluster_size() on page 343.
os_schema_evolution::augment_dll_schema_db_names()
static void augment_dll_schema_db_names(const char* name);
Adds a component schema to the previously specified schema during schema
evolution. The name of the component schema is specified by name. After this
function has been called, the effective schema is the union of the component schema
and the application schema.
Overloadings
The following overloading is supported:
static void augment_dll_schema_db_names(
const os_charp_collection& dll_schema_db_names
);
Adds a list of component schemas to the previously specified schema during schema
evolution. The dll_schema_db_names argument is a collection of component
schema names — each member of the collection is a const char*. After this function
has been called, the effective schema is the union of the collection of component
Release 6.3
335
os_schema_evolution
schemas and the application schema. This function is useful when you are
performing schema evolution on a database that has multiple component schemas
and you want to avoid having to perform multiple evolutions.
os_schema_evolution::augment_optional classes()
static void augment_optional_classes(const char*);
Specifies that the class identified by the specified string is an optional class. In
schema evolution programs, you can write transformer functions for optional classes
even when instances of those classes are not in the database being evolved. This is
useful when performing incremental schema installation. Classes can be in the
application schema but not in the database schema. This occurs when persistent
instances of these classes have not yet been created.
Overloadings
The following overload is supported:
static void augment_optional_classes(
const os_Collection<const char*>&);
Use this overload to pass more than one class name at a time.
If you want to be able to define transformer functions for all classes in the application
schema, regardless of whether there are instances of these classes in the databases,
use os_schema_evolution::set_disable_transformer_class_checks().
os_schema_evolution::augment_pre_evol_transformers()
static void augment_pre_evol_transformers(
const os_transformer_binding&
);
Adds the specified transformer binding to the set of transformer bindings to be used
during subsequent evolutions. This applies to evolutions initiated in the current
process. A transformer binding associates a class with a function so that the function
is executed on each instance of the class before any object is moved or evolved. See
os_transformer_binding on page 417.
Overloadings
The following overloading is supported:
static void augment_pre_evol_transformers(
const os_Collection<os_transformer_binding*>&
);
Adds the elements of the specified collection to the set of transformer bindings to be
used during subsequent evolutions. This applies to evolutions initiated in the
current process. A transformer binding associates a class with a function so that the
function is executed on each instance of the class before any object is moved or
evolved. See os_transformer_binding on page 417.
os_schema_evolution::augment_post_evol_transformers()
static void augment_post_evol_transformers(
const os_transformer_binding&
);
336
C++ A P I Reference
Chapter 2: Class Library
Adds the specified transformer binding to the set of transformer bindings to be used
during subsequent evolutions. This applies to evolutions initiated in the current
process. A transformer binding associates a class with a function so that the function
is executed on each instance of the class after all objects are moved and evolved. See
os_transformer_binding on page 417.
Overloadings
The following overloading is supported:
static void augment_post_evol_transformers(
const os_Collection<os_transformer_binding*>&
);
Adds the elements of the specified collection to the set of transformer bindings to be
used during subsequent evolutions. This applies to evolutions initiated in the
current process. A transformer binding associates a class with a function so that the
function is executed on each instance of the class after all objects are moved and
evolved. See os_transformer_binding on page 417.
os_schema_evolution::evolve()
static void evolve(
const char* work_db_name,
const char* db_to_evolve
);
Invokes schema evolution on the database named by db_to_evolve. The function
must be called outside the dynamic scope of a transaction. If no database is named
by work_db_name, one with that name is created and used as the work database. If a
database is named by work_db_name, it must be a work database from a prior
interrupted evolution performed on the database named by db_to_evolve. In this
case, evolution resumes from the most recent consistent state before the last
interruption.
The new schema is determined by the schema of the database being evolved together
with the modification schema.
The modification schema is the compilation or application schema database
specified in the most recent call in the current process to os_schema_
evolution::set_evolved_schema_db_name( ) along with any schema specified in
a call to os_schema_evolution::augment_dll_schema_db_names(). If there are
no prior calls to set_evolved_schema_db_name( ) or augment_dll_schema_db_
names(), the modification schema is the schema for the application calling
evolve( ).
The new schema is the result of merging the schema of the databases being evolved
with the modification schema; that is, the new schema is the union of the old schema
and the modification schema, minus the definitions in the old schema of classes that
are also defined in the modification schema.
If any classes are present in the old schema but not in the new schema, they must be
specified before the call to evolve( ) by using os_schema_evolution::augment_
classes_to_be_removed( ).
Release 6.3
337
os_schema_evolution
During the instance initialization phase, the instances of modified classes are
modified to conform to the layouts imposed by the new classes.
Data members whose value type has changed are initialized by assignment with the
old data member value if old and new value types are assignment compatible. That
is, ObjectStore assigns the value of the old data member to the storage associated
with the new member, applying only standard conversions defined by the C++
language.
In some cases, schema evolution considers types assignment compatible when C++
would not. For example, if D is derived from B, schema evolution assigns a B* to a
D* if it knows that the B is also an instance of D.
If the new and old value types are not assignment compatible and the new value type
is a class, the new members are initialized as if by a constructor that sets each field to
the appropriate representation of 0. If the new value type is not a class, the new
members are initialized with the appropriate representation of 0.
Data members added to the schema whose value type is a class are initialized as if
by a constructor that sets each field to 0. Other new data members are initialized with
0.
Array-valued members are initialized using the rules outlined earlier, as if the ith
array element were a separate data member corresponding to the ith element of the
old data member value. If there is no ith element of the old data member value (either
because the old value is not an array or because the old value is an array but does not
have an ith element), the new element is initialized as if by a constructor that sets each
field to 0, or with 0.
Very large
databases
See Advanced C++ A P I User Guide, Evolving or Compacting Very Large Databases.
Note
Bit fields are evolved according to the default signed or unsigned rules of the
implementation that built the evolution application. This can lead to unexpected
results when an evolution application built with one default rule evolves a database
originally populated by an application built by an implementation whose default
rule differs. The unexpected results occur when the evolution application attempts
to increase the width of a bit field.
Schema evolution cannot evolve a pointer-to-member that points to a member in a
virtual base class.
When a class is modified to inherit from a base class, subobjects corresponding to the
base class are initialized as if by a constructor that sets each field to 0.
Subobjects corresponding to removed data members or base classes are deleted, as
are instances of classes removed from the schema.
Changing inheritance from virtual to nonvirtual is treated as removal of the virtual
base class and addition of nonvirtual base classes. Changing inheritance from
nonvirtual to virtual is treated as removal of the nonvirtual base classes and addition
of a virtual base class. In each case, subobjects corresponding to the added classes are
initialized as if by a constructor that sets each field to 0.
338
C++ A P I Reference
Chapter 2: Class Library
Untranslatable pointers and references can be processed by an untranslatablepointer handler supplied by the user (see os_schema_evolution::set_
untranslatable_pointer_handler() on page 345).
Untranslatable pointers and C++ references for which there is no handler signal the
exception err_se_illegal_pointer or one of its child exceptions.
When the selection criterion of a query or the path of an index references a removed
class or data member or makes incorrect type assumptions in light of a schema
change, the query or index becomes obsolete. ObjectStore detects all obsolete queries
and indexes.
As with untranslatable pointers, you can handle obsolete queries and indexes by
providing a special handler function for each purpose. Each obsolete index handled
by such a function is dropped automatically after the function returns. If you do not
supply handlers, ObjectStore signals err_schema_evolution when an obsolete
query or index is detected. If you supply an obsolete query handler function that
allows the schema evolution to continue when it encounters an obsolete query,
ObjectStore marks the query internally so that subsequent attempts to use it result in
the signaling of the exception err_os_query_evaluation_error. See os_schema_
evolution::set_obsolete_index_handler() on page 343 and os_schema_
evolution::set_obsolete_query_handler() on page 343.
Subsequent to instance initialization, each transformer function (see os_schema_
evolution::augment_post_evol_transformers() on page 336) is executed on
each instance of its associated class. The order of execution of transformers on
embedded objects follows the same pattern that constructors follow. When the
transformer for a given class is invoked, the transformers for base classes of the given
class are executed first (in declaration order), followed by the transformers for classvalued members of the given class (in declaration order), after which the transformer
for the given class itself is executed.
Overloadings
The following overloadings are supported:
static void evolve(
const char* work_db_name,
const os_Collection<const char*>& dbs_to_evolve
);
Invokes schema evolution on the databases named by the elements of dbs_to_
evolve. The rest of the behavior for this function is as described for the previous
overloading of evolve( ).
static void evolve(
const char* work_db_name,
const os_Collection<const char*>& dbs_to_evolve,
os_schema& new_schema
);
Invokes schema evolution on the databases named by the elements of dbs_to_
evolve. The rest of the behavior for this function is as described for the first
overloading of evolve( ) earlier in this section, except that the modification schema
is specified by new_schema.
static void evolve(
Release 6.3
339
os_schema_evolution
const char* work_db_name,
const char* db_to_evolve,
os_schema& new_schema
);
Invokes schema evolution on the database specified by db_to_evolve. The rest of
the behavior for this function is as described for the first overloading of evolve( )
previously, except that the modification schema is specified by new_schema.
os_schema_evolution::get_enclosing_object()
static os_typed_pointer_void get_enclosing_object(const void*);
Returns the top-level persistent object that encloses the specified address. This
function can be useful in transformer functions.
os_schema_evolution::get_evolved_schema()
static const os_schema& get_evolved_schema();
Returns the evolved schema. This schema is in transient memory.
os_schema_evolution::get_evolved_schema_db_name()
static const char* get_evolved_schema_db_name();
Returns the name of the evolved application schema database.
os_schema_evolution::get_explanation_level()
static os_int32 get_explanation_level();
Returns the level of debugging information that is output during schema evolution.
The return value is one of the following enumerators:
Enumerator
Meaning
silent
Do not output any debugging information. This is the default.
phase_level
Output information about the phases of schema evolution for
each cluster, segment, and database.
type_level
Output information about all types in the database.
object_level
Output information about all objects in the database.
verbose
Output information about all pointers in the database.
Note that the levels are accumulative; that is, each level includes information that is
output at the previous levels. See also os_schema_evolution::set_explanation_
level().
os_schema_evolution::get_path_to_member()
static os_path_to_data* get_path_to_member(const void*);
Returns the path from the enclosing top-level persistent object to the innermost data
member that encloses the specified address. If the top-level object is a primitive type,
the result is null. The caller must delete the returned path object.
340
C++ A P I Reference
Chapter 2: Class Library
os_schema_evolution::get_unevolved_schema()
static const os_schema& get_unevolved_schema();
Returns the unevolved schema. This schema is in transient memory.
os_schema_evolution::get_work_database()
static os_database* get_work_database( );
This function returns a pointer to the work database for the current evolution.
os_schema_evolution::initialize()
static void initialize(
os_unsigned_int32 n_threads,
os_unsigned_int32 prefetch_KB,
os_ptr_val secondary_psr_size);
n_threads specifies number of threads to use for schema evolution. The default
value is 1.5 times the number of CPUs in the system (rounded up). The default
should provide good performance on most hardware if there is no other significant
load on the system.
prefetch_KB specifies the size in KB of persistent pages to prefetch at one time. The
default is 1024 KB which should provide good performance on most hardware.
secondary_psr_size specifies the size in MB of virtual address space for secondary
sessions. The default is 16 MB. Increase this value in the unlikely event that your
application runs out of address space, for example, because of an extremely large
schema.
Specifying zero for the arguments to initialize() sets them to the current default
values. It is possible that the defaults listed here will change in future releases of
ObjectStore.
os_schema_evolution::set_address_space_release_interval()
static void set_address_space_release_interval(
os_unsigned_int32 interval);
Specifies the frequency of address space releases, where interval is in units of bytes
and controls the frequency. Specify a smaller value for more frequent releases, a
larger value for less frequent. The default value is 1 MB.
os_schema_evolution::set_avoid_page_boundary()
static void set_avoid_page_boundary(
os_unsigned_int32 max_bytes_wasted);
Specifies that you want schema evolution to avoid placing objects across page
boundaries in the evolved database. This applies to objects that have evolved and
objects that have moved because of other evolved objects. The default is that schema
evolution does not avoid page boundaries when moving objects. When schema
evolution avoids a page boundary, it inserts a free region and leaves some bytes on
the page unused.
Release 6.3
341
os_schema_evolution
The max_bytes_wasted argument specifies the maximum bytes that can be wasted
when page boundaries are avoided. If trying to avoid a page boundary would cause
more than max_bytes_wasted bytes to be wasted, schema evolution does not avoid
placing that object across the page boundary.
The value of max_bytes_wasted can be any value from 0 through 4095. A value of
0 disables the feature.
Note: In the context of this function, all pages are server pages, which are always 4K
in size. It does not matter what platform the server is running on.
os_schema_evolution::set_disable_transformer_class_checks()
static void os_set_disable_transformer_class_checks(os_boolean);
Allows a schema evolution program to define transformer functions for classes for
which there are no instances in the database being evolved. This is useful when
performing incremental schema installation. Classes can be in the application
schema but not in the database schema. This occurs when persistent instances of
these classes have not yet been created.
To specify one or more particular classes for which there are no instances in the
database but for which you want to define transformer functions, see os_schema_
evolution::augment_optional classes().
os_schema_evolution::set_evolved_schema_db_name()
static void set_evolved_schema_db_name(const char*);
Specifies the name of an application schema database used to determine the new
schema in subsequent evolutions during the current process.
os_schema_evolution::set_explanation_level()
static void set_explanation_level(os_unsigned_int32 level);
Specifies the level of debugging information that is output during schema evolution.
The level argument can be one of the following enumerators:
Enumerator
Meaning
silent
Do not output any debugging information. This is the default.
phase_level
Output information about the phases of schema evolution for
each cluster, segment, and database.
type_level
Output information about all types in the database.
object_level
Output information about all objects in the database.
verbose
Output information about all pointers in the database.
Note that the levels are accumulative; that is, each level includes information that is
output at the previous levels. See also os_schema_evolution::get_explanation_
level().
342
C++ A P I Reference
Chapter 2: Class Library
os_schema_evolution::set_malloc_size()
static void set_malloc_size(os_unsigned_int32);
Sets the relocation map malloc size in bytes. The default is 0x100000 bytes (1024 KB).
os_schema_evolution::set_maplet_size()
static void set_maplet_size(os_unsigned_int32);
Sets the relocation map maplet size in bytes.; the value must be a power of 2. The
default is 64 bytes. You should change this value only if you fully understand the
performance characteristics of your CPU and all its levels of cache.
os_schema_evolution::set_maximum_cluster_size()
static void set_maximum_cluster_size(
os_unsigned_int32 max_cluster_size_in_bytes)
During schema evolution clusters larger than max_cluster_size_in_bytes are
split into multiple clusters. This function specifies the size of max_cluster_size_
in_bytes. The value of max_cluster_size_in_bytes is rounded up to the next
multiple of 64 KB. The default is to split any cluster that exceeds 1600 MB. See os_
schema_evolution::augment_cluster_split_avoidance() on page 335 for
information about how to prevent schema evolution from splitting some clusters.
Note that some ObjectStore collections manage an internal cluster which will not be
split because the internal clusters maintain data structures that cannot be split across
multiple clusters. Examples of collections that maintain internal clusters are os_set,
os_Set, os_bag, os_Bag, os_Dictionary, and indexes.
os_schema_evolution::set_maximum_memory_size()
static void set_maximum_memory_size(os_ptr_val);
Sets the maximum memory to use for pointer relocation maps in bytes. The default
is one-half the main memory size or one-half the size of virtual memory, whichever
is less.
os_schema_evolution::set_obsolete_index_handler()
static void set_obsolete_index_handler(
void (*func)(const os_collection&, const char* path_string)
);
Specifies func as the handler function for obsolete indexes. Applies to evolutions
initiated in the current process after the call to this function. The function func must
be defined by the user. The os_collection& is a reference to the collection whose
index is obsolete, and the char* points to a string expressing the index’s path (key).
os_schema_evolution::set_obsolete_query_handler()
static void set_obsolete_query_handler(
void (*func)(os_coll_query_r, os_char_const_p query_string)
);
Release 6.3
343
os_schema_evolution
Specifies func as the handler function for obsolete queries. Applies to evolutions
initiated in the current process after the call to this function. The function func must
be defined by the user. The os_coll_query_r is a reference to the obsolete query,
and the os_char_const_p points to a string expressing the query’s selection
criterion.
344
C++ A P I Reference
Chapter 2: Class Library
os_schema_evolution::set_optimize_checkpoints()
static void set_optimize_checkpoints(os_boolean);
Specifies that schema evolution will use an optimization that does not checkpoint
each phase. By default, this optimization is off. Use this option with caution, since
misuse could result in excessive page replacement and/or potential VM thrashing.
os_schema_evolution::set_pre_evolution_setup_hook()
static void set_pre_evolution_setup_hook(
os_se_hook_function_void);
Specifies the hook function that will get called for setting up things in a context
where schema validation is disabled.
os_schema_evolution::set_resolve_ambiguous_void_pointers()
static void set_resolve_ambiguous_void_pointers(os_boolean);
If the argument is set to true (nonzero), specifies that, if an ambiguous void pointer
is encountered during schema evolution, it should be resolved to the outermost
enclosing collocated object. A void* pointer is ambiguous if schema evolution
cannot determine whether it points to an object or to the first data member within the
object. By default (false or 0), schema evolution signals an exception if it encounters
an ambiguous void pointer. In this case, the user can provide an untranslatablepointer handler that would be invoked by the exception.
os_schema_evolution::set_task_list_file_name()
static void set_task_list_file_name(const char* file_name);
Specifies the file named file_name as the file to which a task list should be sent.
Applies to task lists generated in the current process after the call to this function.
os_schema_evolution::set_untranslatable_pointer_handler()
static void set_untranslatable_pointer_handler(
os_untranslatable_pointer_handler*);
Specifies the handler for pointers that cannot be translated. set_untranslatable_
pointer_handler() will adopt its argument and delete it when its use has ended.
See os_untranslatable_pointer_handler on page 448 for information about the
os_untranslatable_pointer_handler class.
os_schema_evolution::shutdown()
static void shutdown();
Cleans up ObjectStore resources after schema evolution is completed.
Release 6.3
345
os_schema_evolution
os_schema_evolution::task_list()
static void task_list(
const char* work_db_name,
const char* db_to_evolve
);
Generates a task list for the evolution that would have taken place had evolve( )
been called with the same arguments. The task list is sent to the file specified by the
most recent call to os_schema_evolution::set_task_list_file_name( ) or, if
there is no such call, to standard output. After the task list is generated, this function
exits, terminating the current process.
The task list contains a function definition for each class whose instances will be
migrated. Each function has a name of the form
class-name@[1]::initializer( )
where class-name names the function’s associated class. Each classname@[1]::initializer( ) function definition contains a statement or comment for
each data member of its associated class. For a member with value type T, this
statement or comment is one of the following:
• Assignment statement
• Call to T@[1]::copy_initializer( )
• Call to T@[2]::construct_initializer( )
• Call to T@[1]::_initializer( )
• Comment indicating that the field will be zero initialized
An assignment statement is used when the old and new value types of the member
are assignment compatible. T@[1]::copy_initializer( ) is used when the
member has not been modified by the schema change and the new value can be
copied bit by bit from the old value. T@[2]::construct_initializer( ) is used
when the value type has been modified and the new value type is a class. T@[1]::_
initializer( ) is used when the member has not been modified by the schema
change but instances of the value type of the member will be migrated. Definitions
for all these functions appear in the task list.
Overloading
The following overloading is supported:
static void task_list (
const char* work_db_name,
const os_Collection<const char*>& dbs_to_evolve
);
Generates a task list for the evolution that would have taken place had evolve( )
been called with the same arguments. The task list is sent to the file specified by the
most recent call to os_schema_evolution::set_task_list_file_name( ). The
contents of the task list are as described for the preceding overloading of task_
list( ).
346
C++ A P I Reference
Chapter 2: Class Library
os_schema_handle
This transient class represents a reference or handle to a component (DLL) schema
or an application schema. A schema handle is different from a schema in that the
handle can exist before the schema has been loaded from its schema database. Also,
the handle remains valid across transactions, while a pointer to the schema is valid
for only one transaction.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/nreloc/schftyps.hh>.
os_schema_handle::DLL_unloaded()
void DLL_unloaded();
If the component schema is loaded, marks it for unloading; otherwise, does nothing
and signals no error. The actual unloading, reconstruction of process type tables, and
deletion of the os_schema_handle occurs later (at the end of the transaction).
Unloading a DLL calls DLL_unloaded() from the DLL’s termination function and
then unloads the DLL. If the rest of the transaction tries to do anything that requires
the DLL, or if the transaction is aborted and retried and the retry does not load the
DLL, a fatal error is likely to occur.
It is an error to call this function with the os_schema_handle for an application
schema. This signals the exception err_invalid_for_application_schema.
os_schema_handle::get()
const os_app_schema& get() const;
Gets a C++ reference to an application or DLL program schema when given its os_
schema_handle. The schema must be loaded.
If the schema is not loaded or has been unloaded, an err_schema_not_loaded
exception is signaled. This function can be called only while a transaction is in
progress, and the result is valid only for the duration of that transaction.
os_schema_handle::get_all()
static os_schema_handle** get_all(
osbool to_load = false
);
With an argument of 0 (false, the default), this function returns a null-terminated
array of pointers to os_schema_handle instances that are loaded and are not queued
to unload. This set corresponds to the current complete program schema.
With a nonzero (true) argument, this function returns a null-terminated array of
pointers to the os_schema_handle instances that are queued to load.
The caller must deallocate the array.
Release 6.3
347
os_schema_handle
os_schema_handle::get_application_schema_handle()
static os_schema_handle* get_application_schema_handle();
Returns a pointer to the os_schema_handle for the application schema. If the session
has no application schema, this returns a pointer to a handle for a dummy schema
that contains only ObjectStore’s built-in types (essentially the boot schema). This
function should be called only after ObjectStore has been initialized.
os_schema_handle::get_DLL_identifiers()
const char* const* get_DLL_identifiers(
os_unsigned_int32& count
) const;
Returns an array of pointers to DLL identifiers and the number of elements in the
array, given an os_schema_handle. The caller must not modify or deallocate the
strings or the array. If the this argument designates an application schema, the
result is NULL and count is set to 0.
os_schema_handle::get_schema_database()
os_database& get_schema_database() const;
Gets the os_database for the application or component schema database.
os_schema_handle::get_schema_database_pathname()
const char* get_schema_database_pathname() const;
Gets the application or component schema database path name.
See objectstore::get_application_schema_pathname() on page 64.
os_schema_handle::get_schema_info()
os_schema_info& get_schema_info() const;
Returns the os_schema_info that contains the DLL identifiers and schema path
name for the schema for which this is the handle.
os_schema_handle::get_status()
os_schema_handle_status get_status() const;
Returns the loaded or unloaded status of an os_schema_handle. The status is one
of the following four symbolic constants:
• os_schema_handle_unloaded
• os_schema_handle_loaded
• os_schema_handle_queued_to_load
• os_schema_handle_queued_to_unload
The unloaded status exists only for an os_schema_handle that has never been
loaded. After an os_schema_handle leaves the os_schema_handle_queued_to_
unload status and becomes unloaded, it is deleted.
348
C++ A P I Reference
Chapter 2: Class Library
os_schema_handle::insert_required_DLL_identifiers()
void insert_required_DLL_identifiers(
os_database& db
);
Records all DLL identifiers that belong to this os_schema_handle into the database’s
required DLL set. This function can be called only in an update transaction with the
database open for write.
os_schema_handle::set_schema_database_pathname()
void set_schema_database_pathname (const char* path);
Sets the application or component schema database path name. To be effective, this
function must be called before the schema is loaded.
Like objectstore::set_application_schema_pathname(), this has a 255character limit and copies over the existing path name.
os_schema_handle::os_schema_handle_status
This enumeration type is the type of the status of an os_schema_handle. The status
can be one of the following:
• loaded
• unloaded
• queued_to_load
• queued_to_unload
Release 6.3
349
os_schema_info
os_schema_info
This is the common base class for os_application_schema_info and os_DLL_
schema_info. It is designed for use with component schemas and application
schemas; for more information, see os_application_schema_info on page 103 and
os_DLL_schema_info on page 206.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/nreloc/schftyps.hh>.
os_schema_info::get()
os_schema_handle& get();
Given an os_schema_info, this function finds the corresponding os_schema_
handle. Signals an err_misc exception if this is an os_DLL_schema_info and os_
DLL_schema_info::DLL_loaded() has not been called, or if this is an os_
application_schema_info and the initialization that loads the application schema
has not yet run.
os_schema_info::get_DLL_identifiers()
const char* const* get_DLL_identifiers(
os_unsigned_int32& count
) const;
Returns an array of pointers to DLL identifiers and the number of elements in the
array, given an os_schema_info. The caller must not modify or deallocate the
strings or the array. If the this argument designates an application schema, the
result is NULL and count is set to 0.
os_schema_info::get_schema_database_pathname()
const char* get_schema_database_pathname() const;
Returns the schema database path name.
os_schema_info::set_schema_database_pathname()
void set_schema_database_pathname(const char* new_pathname);
Sets the schema database path name. This has no useful effect if the schema has
already been loaded.
Like objectstore::set_application_schema_pathname(), this has a 255character limit and copies over the existing path name.
350
C++ A P I Reference
Chapter 2: Class Library
os_schema_install_options
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_schema_install_options::get_copy_member_functions()
os_boolean get_copy_member_functions() const;
This member function returns a Boolean value that indicates whether the member
function information (if present) is to be copied and installed into the schema during
schema installation.
os_schema_install_options::os_schema_install_options()
os_schema_install_options();
This function is the constructor for this class. The default behavior given to the class
is not to copy the member function into the schema.
os_schema_install_options::set_copy_member_functions()
void set_copy_member_functions(os_boolean_copy);
This member function is used to specify whether the member function information
(if present) should be copied and installed into the schema during installation.
Release 6.3
351
os_segment
os_segment
ObjectStore databases are divided into segments. Each segment can be used as a unit
of transfer to and from persistent storage. Every database is created with an initial
segment, the default segment, in which new objects are allocated by default.
Databases whose schema is not stored remotely have an additional initial segment,
the schema segment, which contains schema information used internally by
ObjectStore and all the database’s roots. More segments can be added by the user at
any time.
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_segment::create_cluster()
os_cluster* os_segment::create_cluster();
Creates a cluster in the specified segment and returns a pointer to an instance of the
class os_cluster (see os_cluster on page 131). Call this function within a
transaction. The return value points to a transient object representing the new
cluster. Note that because it points to transient memory, the return value of this
function cannot be stored persistently. This function signals err_segment_
transient if it is invoked on a transient database.
os_segment::database_of()
os_database* database_of( );
Returns a pointer to the database in which the specified segment resides. The
transient database is returned if the transient segment is specified.
os_segment::destroy()
void destroy( );
Deletes the segment for which the function is called. When a segment is destroyed,
all data it contains is permanently destroyed and pointers into the segment become
invalid. Any subsequent use of the destroyed segment (such as an attempt to allocate
memory within it) is an error. Invoking destroy() on a destroyed segment results
in the err_segment_is_deleted exception.
os_segment::get_access_control()
os_segment_access* get_access_control( ) const;
Returns a pointer to the segment’s associated os_segment_access, which indicates
the segment’s primary group and permissions.
352
C++ A P I Reference
Chapter 2: Class Library
os_segment::get_all_clusters()
void get_all_clusters(
os_int32 max_clusters,
os_cluster_p* cluster_array,
os_int32& n_clusters
) const;
Provides access to all clusters in the specified segment. os_cluster_p* is an array of
pointers to segments. This array must be allocated by the user. The function os_
segment::get_n_clusters() can be used to determine the size array to allocate;
see os_segment::get_n_clusters() on page 356. The max_clusters argument
specifies the maximum number of elements the array is to have. The n_clusters
argument refers to the actual number of cluster pointers returned.
os_segment::get_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
os_allocation_strategy get_allocation_strategy(void) const;
Returns the current strategy to use when ObjectStore allocates storage for an object
in a cluster in the specified segment. For information about the return values, see
objectstore::get_allocation_strategy() on page 62. For information about
specifying the allocation strategy in a segment, see os_segment::set_allocation_
strategy() on page 359.
os_segment::get_application_info()
void* get_application_info( ) const;
Returns a pointer to the object pointed to by the pointer last passed, during the
current session, to os_segment::set_application_info( ) for the specified
segment.
If set_application_info( ) has not been called for the specified segment during
the current session, 0 is returned.
os_segment::get_cluster()
os_cluster* get_cluster(os_unsigned_int32 clstr_num) const;
Returns a pointer to the cluster in the specified segment with the specified cluster
number. See os_cluster::get_number() on page 133.
Release 6.3
353
os_segment
os_segment::get_clusters()
void get_clusters(
os_unsigned_int32 first_cluster_num,
os_unsigned_int32 max_clusters,
os_cluster_p* clstrs,
os_unsigned_int32& n_clusters,
os_boolean& b_more
) const;
Returns a maximum number of clusters, as specified in max_clusters. The first_
cluster_num argument specifies the number of the first cluster in the range. The
clusters are returned in clstrs, which must be allocated by the user. The n_
clusters argument contains the number of clusters actually returned, and b_more
is nonzero (true) if there are more clusters to retrieve.
You can use get_clusters() to write your own cluster iterator, or you can use the
ObjectStore iterator class; see os_cluster_cursor on page 138.
os_segment::get_comment()
char* get_comment( ) const;
Returns a transient copy of the string associated by means of os_segment::set_
comment( ) with the specified segment. If set_comment( ) has not been called for the
specified segment, a zero-length string is returned. The user is responsible for
deleting the returned string.
os_segment::get_default_cluster()
os_cluster* get_default_cluster() const;
Returns a pointer to the default cluster of the specified segment. The default cluster
is the cluster in which persistent memory is allocated by default when new is called
with only an os_segment* argument. A session can change the default at any time
(see os_segment::set_default_cluster() on page 360), but the change remains
in effect only for the duration of the session and is invisible to other sessions.
Simple ObjectStore applications need not create any clusters; all the segment's
persistent data can be stored in the initial cluster, subject to size limitations. If more
sophisticated clustering is required, however, the application can create new clusters
in the database, and it might be convenient to make one of these the default.
354
C++ A P I Reference
Chapter 2: Class Library
os_segment::get_export_ids()
void get_export_ids(
const os_export_id& last_export_id,
os_unsigned_int32 max_export_ids,
os_export_id* p_export_ids,
os_unsigned_int32& n_export_ids,
os_boolean& b_more
) const;
Fills in the element of p_export_ids with export IDs for the this segment.
The last_export_id argument indicates where in the list of export IDs defined for
the segment to start returning values. If the null export ID is passed in, the export IDs
at the start of the list are returned. If last_export_id is not the null export ID, the
export IDs immediately following the specified export ID are returned.
max_export_ids specifies the maximum number of export IDs to return using the
argument.
p_export_ids must point to an array at least max_export_ids in length, or
unpredictable results can occur.
n_export_ids is updated to indicated the number of export IDs filled in. The first n_
export_ids elements of p_export_ids are filled in with the returned export IDs.
b_more is nonzero (true) if a subsequent call to get_export_ids(), with last_
export_id being the last export ID returned by this call, would return at least one
export ID.
The returned export IDs are not guaranteed to be in any particular order, except that
the last one returned in the p_export_ids array has the largest numerical value (see
os_export_id::get_value() on page 219) of any returned in this call. If you pass
the last export ID to last_export_id in a subsequent call to this function, the
method does not return any of the export ID values returned in the prior call.
os_segment::get_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
void get_fetch_policy(
os_fetch_policy& policy,
os_int32& bytes
) const;
Retrieves the segment’s current fetch policy. An enumerator of type os_fetch_
policy is returned in policy, and the fetch quantum is returned in bytes. For
information about the arguments, see objectstore::get_fetch_policy() on
page 66. For information about setting the fetch policy on a segment, see os_
segment::set_fetch_policy() on page 360.
Release 6.3
355
os_segment
os_segment::get_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
objectstore_lock_option get_lock_option() const;
Returns the locking behavior currently in effect for the specified segment.
For information about the return value, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
• objectstore::own_page_write on page 79
For information about setting the lock option, see os_segment::set_lock_
option() on page 361.
os_segment::get_n_clusters()
os_int32 get_n_clusters() const;
Returns the number of clusters in the specified segment.
os_segment::get_null_illegal_pointers()
os_boolean get_null_illegal_pointers( );
If the specified segment is in null_illegal_pointers mode, the function returns
nonzero (true); otherwise, it returns 0 (false). See os_segment::set_null_illegal_
pointers() on page 361.
356
C++ A P I Reference
Chapter 2: Class Library
os_segment::get_number()
os_unsigned_int32 get_number( ) const;
Returns the segment number of the specified segment. This number is suitable for
passing to the os_pathname_and_segment_number constructor.
os_segment::get_segment_reference_policy()
objectstore::segment_reference_policy
os_segment::get_segment_reference_policy() const;
Gets the reference policy for the this segment. See os_database::create_
segment() on page 152.
os_segment::get_transient_segment()
static os_segment* const get_transient_segment( );
Returns a pointer to the transient segment, which can be used as an argument to
::operator new() to request transient allocation. For information about
::operator new(), see ::operator new() on page 459.
os_segment::is_deleted()
os_boolean is_deleted( );
Returns a nonzero os_boolean (true) if the specified os_segment has been deleted;
returns 0 (false) otherwise.
os_segment::is_empty()
os_boolean is_empty( );
Returns a nonzero os_boolean (true) if the specified os_segment contains no
nondeleted objects; returns 0 (false) otherwise.
os_segment::is_transient_segment()
os_boolean is_transient_segment() const;
Returns nonzero (true) if the specified segment is transient; returns 0 (false) if
persistent.
os_segment::of()
static os_segment* of(void* location);
Returns a pointer to the segment in which the specified object resides. If the specified
void* is 0 or points to transient memory, a pointer to the transient segment is
returned. See os_segment::get_transient_segment() on page 357.
Release 6.3
357
os_segment
os_segment::release_pointer()
void release_pointer();
Releases the pointer specified by the implicit this argument.
When an application calls a function that returns an os_segment pointer, ObjectStore
increments a use count of the number of times it has returned a pointer to the same
object. The use count thus represents the number of pointers to the same object that
are currently in use.
When the application calls release_pointer(), ObjectStore decrements the use
count for an ObjectStore object. When the last pointer is released, the count reaches
0 and the os_segment object is deleted.
See the following for related information:
• The C++ A P I User Guide discusses how to release pointers.
• You can also release os_segment pointers when they go out of scope; see os_
release_segment_pointer on page 315.
• See os_segment::retain_pointer() on page 358 for information about
retaining os_segment pointers.
os_segment::resolve_export_id()
void* resolve_export_id(const os_export_id& export_id) const;
Returns a pointer to the object in the this segment with the specified export ID. If
the object is an array, the returned value points at the array’s first element (rather
than the beginning of the vector header, if there is one).
An exception is signaled if the object with the specified export ID is in a closed
database that cannot be autoopened.
An exception is signaled if there is no object in the this segment with the specified
export ID.
os_segment::retain_pointer()
void retain_pointer();
Retains the pointer specified by the this argument.
When an application calls a function that returns an os_segment pointer, ObjectStore
increments a use count of the number of times it has returned a pointer to the same
object. The use count thus represents the number of pointers to the same object that
are currently in use. The application calls os_segment::release_pointer() when
it no longer needs the pointer, thus releasing it and decrementing the use count.
When the application calls retain_pointer(), ObjectStore increments the use count
for an os_segment object. Calling retain_pointer() ensures that the pointer is
retained, even when another part of the application releases it.
For information about using retain_pointer(), see the C++ A P I User Guide. See
also os_segment::release_pointer() on page 358.
358
C++ A P I Reference
Chapter 2: Class Library
os_segment::return_memory()
void return_memory(os_boolean evict_now);
Same as objectstore::return_memory() on page 81, except that it acts on a
specified segment rather than on a specified range of addresses.
os_segment::session_of()
os_session* session_of() const;
Returns the os_session object for the session in which the specified os_segment*
was retrieved.
This function can be used with os_session::set_current() to enable a thread to
join the session associated with an os_segment object. For example, if seg_ptr
references an os_segment object, then the statement
os_session::set_current(seg_ptr->session_of());
enables the currently executing thread to access the object by setting the thread’s
current session to the session associated with seg_ptr.
os_segment::set_access_control()
void set_access_control(const os_segment_access* new_access);
Associates the specified os_segment_access with the specified segment. The os_
segment_access determines the primary group and permissions for the os_
segment. The caller must be the owner of the database containing the specified
segment.
os_segment::set_allocation_strategy()
enum os_allocation_strategy {
os_allocation_strategy_least_space,
os_allocation_strategy_least_wait,
};
void set_allocation_strategy(os_allocation_strategy);
Sets the strategy to use when looking for space to allocate for an object in clusters in
the specified segment. This strategy applies to all clusters in the segment unless it is
overridden by subsequent calls to
• objectstore::set_allocation_strategy() on page 82
• os_cluster::set_allocation_strategy() on page 135
• os_database::set_allocation_strategy() on page 168
• os_segment::set_allocation_strategy() on page 359
For information about the meaning of the os_allocation_strategy enumerators
that can be used as arguments, see objectstore::get_allocation_strategy() on
page 62.
Release 6.3
359
os_segment
os_segment::set_application_info()
void set_application_info(void* info);
Associates the specified object with the specified segment for the current session. The
argument info must point to a transient object. See os_segment::get_
application_info() on page 353.
os_segment::set_comment()
void set_comment(const char* info);
Associates a persistent copy of the specified string with the specified segment. There
is no practical limit to the length of the string that info points to. The utility ossize
prints the comment, if set, when displaying information about the segment; see
Managing ObjectStore. For information about retrieving a comment, see os_
segment::get_comment() on page 354.
os_segment::set_default_cluster()
void set_default_cluster(os_cluster* clstr);
Sets the default cluster for the specified segment. The default cluster is the cluster in
which persistent memory is allocated by default when new is called with only an os_
segment* or os_database* argument. Changing the default cluster remains in effect
only for the duration of the session and is invisible to other sessions.
Simple ObjectStore applications need not create any clusters; all the segment's
persistent data can be stored in the initial cluster, subject to size limitations. If you
need more control over clustering, however, your application can create new clusters
in the database and make one of them the default.
os_segment::set_fetch_policy()
enum os_fetch_policy {
os_fetch_page,
os_fetch_stream,
os_fetch_cluster
};
void set_fetch_policy(os_fetch_policy policy, os_int32 bytes);
Specifies the fetch policy for the specified segment. The default for the policy
argument is os_fetch_page. For information about the arguments, see
objectstore::get_fetch_policy() on page 66.
The fetch policy established with set_fetch_policy() remains in effect only until
the end of the session making the function call. Moreover, set_fetch_policy()
affects only those transfers made by this session. Other concurrent sessions can use
a different fetch policy for the same segment.
For information about retrieving the fetch policy for a segment, see os_
segment::get_fetch_policy() on page 355.
360
C++ A P I Reference
Chapter 2: Class Library
os_segment::set_lock_option()
enum objectstore_lock_option {
lock_as_used,
lock_page_write,
lock_segment_read,
lock_segment_write,
lock_cluster_read,
lock_cluster_write,
lock_database_read,
lock_database_write,
own_page_write
};
void set_lock_option(objectstore_lock_option lock_behavior);
Sets the locking behavior for the specified segment, including all clusters in the
segment.
For information about the argument, see
• objectstore::lock_as_used on page 76
• objectstore::lock_cluster_read on page 77
• objectstore::lock_cluster_write on page 77
• objectstore::lock_database_read on page 77
• objectstore::lock_database_write on page 77
• objectstore::lock_page_write on page 78
• objectstore::lock_segment_read on page 78
• objectstore::lock_segment_write on page 78
• objectstore::own_page_write on page 79
os_segment::set_null_illegal_pointers()
void set_null_illegal_pointers(os_boolean);
By default, ObjectStore signals a run-time error when it detects an illegal pointer. If
you pass 1 (true) to this function, ObjectStore changes the illegal pointer to 0 (null).
You can specify the default behavior by passing 0 (false) to this function. The results
of using this function do not remain in effect after the current session ends, and they
are invisible to other sessions.
os_segment::size()
os_unsigned_int64 size( os_boolean b_lock_segment = 1);
Returns the total size in bytes of all clusters in the specified segment. If b_lock_
segment is nonzero (true, the default), the function waits until the specified segment
is read locked before returning its size. If b_lock_segment is 0 (false), the function
returns the segment’s size without waiting. The reported size is more accurate if the
segment is locked instead of unlocked.
Release 6.3
361
os_segment_access
os_segment_access
Instances of the class os_segment_access serve to associate zero or more access
types with a group of a specified name, as well as with the default group.
By associating an os_segment_access with a segment (using os_segment::set_
access_control( )), you specify both the segment’s associated primary group and
its permissions.
The owner of a segment always has both read and write access to it.
The possible combinations of access types are represented by the following
enumerators:
• os_segment_access::no_access
• os_segment_access::read_access
• os_segment_access::read_write_access
Note that write access without read access cannot be specified.
These enumerators are used as arguments to certain members of os_segment_
access.
You must be the owner of a database to set the permissions on its segments. If you
are not the owner of a database but nevertheless have write access to it, you have the
ability to create a segment in the database but not to modify its permissions. Because
newly created segments allow all types of access to all categories of users, segments
created by nonowners necessarily have a period of vulnerability between creation
time and the time at which the owner restricts access with os_segment::set_
access_control( ).
For information about controlling segment-level access, see the C++ A P I User Guide.
os_segment_access::get_default()
os_int32 get_default( ) const;
Returns the types of access associated with the default group for the os_segment_
access.
os_segment_access::get_primary_group()
os_int32 get_primary_group(
os_char_const_p* group_name = 0
) const;
Returns the types of access associated with the primary group of the os_segment_
access. The function sets group_name, if supplied, to point to the name of that
group.
os_segment_access::no_access
This is one of three enumerators used to specify combinations of access types. They
are used as arguments to certain members of os_segment_access.
362
C++ A P I Reference
Chapter 2: Class Library
os_segment_access::operator =()
os_segment_access& operator =(
const os_segment_access& source
);
Modifies the os_segment_access pointed to by this so that it is a copy of source.
That is, it stores the same group name as source and associates the same
combinations of access types with the same groups. It returns a reference to the
modified os_segment_access.
os_segment_access::os_segment_access()
os_segment_access( );
Creates an os_segment_access that associates no_access with both the default
group and the group named group_name.
os_segment_access(
const char* primary_group,
os_int32 primary_group_access_type,
os_int32 default_access_type
);
Creates an instance of os_segment_access that associates primary_group_access_
type with the group named primary_group and associates default_access_type
with the default group. primary_group_access_type and default_access_type
are each one of the following:
• os_segment_access::no_access
• os_segment_access::read_access
• os_segment_access::read_write_access.
Overloadings
The following overloading is supported:
os_segment_access(
const os_segment_access& source
);
Creates a copy of source. That is, it creates an os_segment_access that stores the
same group name and associates the same combinations of access types with the
same groups.
os_segment_access::read_access
This is one of three enumerators used to specify combinations of access types. They
are used as arguments to certain members of os_segment_access.
os_segment_access::read_write_access
This is one of three enumerators used to specify combinations of access types. They
are used as arguments to certain members of os_segment_access.
Release 6.3
363
os_segment_access
os_segment_access::set_default()
void set_default(
os_int32 access_type
);
Associates a specified combination of access types with the default group. The value
of access_type can be one of the following:
• os_segment_access::no_access
• os_segment_access::read_access
• os_segment_access::read_write_access
os_segment_access::set_primary_group()
void set_primary_group(
const char* group_name,
os_int32 access_type
);
Associates a specified combination of access types with a group of a specified name.
The group_name argument is the name of the group. The access_type argument can
be one of the following:
• os_segment_access::no_access
• os_segment_access::read_access
• os_segment_access::read_write_access
Overloading
The following overloading is supported:
void set_primary_group(
os_int32 access_type
);
Associates a specified combination of access types with a group of an unspecified
name. The value of access_type can be one of the following:
• os_segment_access::no_access
• os_segment_access::read_access
• os_segment_access::read_write_access
os_segment_access::~os_segment_access()
The destructor frees memory associated with the deleted instance of os_segment_
access.
364
C++ A P I Reference
Chapter 2: Class Library
os_segment_cursor
Instances of the class os_segment_cursor can be used to iterate over segments in a
database.
Type definitions
The types os_int32 and os_boolean, used throughout this document, are each
defined as a signed 32-bit integer type. The type os_unsigned_int32 is defined as
an unsigned 32-bit integer type.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_segment_cursor::os_segment_cursor()
os_segment_cursor(
const os_database* db,
os_unsigned_int32 max_n_segments_at_a_time = 100
);
Constructs an instance of os_segment_cursor for iterating over the segments in db.
The max_n_segments_at_a_time argument sets the number of segments that can be
maintained on the client concurrently without returning to the ObjectStore server for
another group. The constructor allocates a buffer large enough to hold the segments.
After constructing os_segment_cursor, call os_segment_cursor::next() to
position os_segment_cursor at the first cluster in the segment.
os_segment_cursor::get_current()
os_segment* get_current() const;
If os_segment_cursor is positioned at a segment, returns a pointer to that segment.
If os_segment_cursor is not positioned at a segment, it returns NULL. To position
os_segment_cursor at a segment, call os_segment_cursor::next().
os_segment_cursor::next()
os_segment* next();
Advances to the next segment and returns a pointer to that segment. If next() is
called immediately after os_segment_cursor is created, next() positions os_
segment_cursor at the first segment in the database and returns a pointer to that
segment. If next() advances beyond the last segment in the database, it returns
NULL.
Release 6.3
365
os_segment_cursor
os_segment_cursor::reset()
void reset();
Resets os_segment_cursor to its initial state; you must call os_segment_
cursor::next() to position os_segment_cursor at the first segment.
Overloadings
The following overloadings are supported:
void reset(os_unsigned_int32 seg_num);
Positions os_segment_cursor at the specified segment. If the segment at seg_num
does not exist, os_segment_cursor::get_current() returns NULL. The value
returned by os_segment_cursor::get_number() is suitable for seg_num.
void reset(const os_database* db);
If db is specified, os_segment_cursor can be used to iterate over the segments in db.
You must call os_segment_cursor::next() to position os_segment_cursor at the
first segment in db.
366
C++ A P I Reference
Chapter 2: Class Library
os_server
Instances of the class os_server represent ObjectStore servers. This class is useful
for handling err_broken_server_connection.
You get pointers to all the servers currently known to the client by calling
objectstore::get_all_servers( ). Following is an example of a handler for err_
broken_server_connection:
Example
TIX_HANDLE (err_broken_server_connection) {
/* code that could encounter broken connection */
}
TIX_EXCEPTION {
tix_exception *cur = tix_handler::get_exception();
/* It might be necessary to abort a transaction in
progress. This is a tricky situation because
under some circumstances it is not needed, and
in others it is. */
if (objectstore::abort_in_progress())
os_transaction::abort_top_level();
/* Here is how the application can find the lost servers. */
os_int32 nservers = objectstore::get_n_servers();
os_server **svrlist = new os_server * [nservers];
char *svr_name = NULL;
os_int32 ignore;
objectstore::get_all_servers(nservers, svrlist, ignore);
for (os_int32 i = 0; i<nservers; ++i) {
if (svrlist[i]->connection_is_broken()) {
svr_name = svrlist[i]->get_host_name();
printf("lost server %s\n", svr_name);
delete [] svr_name;
}
}
delete [] svrlist;
} TIX_END_HANDLE;
When handling err_broken_server_connection, call os_transaction::abort_
top_level( ) if objectstore::abort_in_progress( ) returns nonzero. If you do
not abort the transaction, attempts to proceed might cause err_broken_server_
connection to be reraised.
When ObjectStore raises err_broken_server_connection, it immediately aborts
all transactions. Any databases currently open on the lost server are considered by
ObjectStore to remain open. Subsequent uses of these databases (or others managed
by that server) cause ObjectStore to attempt to reconnect with the server.
os_server::connection_is_broken()
os_boolean connection_is_broken( ) const = 0;
Returns nonzero if the connection with the specified ObjectStore server is currently
lost; otherwise, returns 0.
Release 6.3
367
os_server
os_server::disconnect()
void disconnect( );
Disconnects the specified ObjectStore server. Call this function outside any
transaction; otherwise err_trans is signaled. It is harmless to call this member if the
connection has already been lost for any reason. The result of this call is very much
like the result of unintentionally losing a connection. The client retains all its
information about the server and its databases but marks them as having lost the
connection. An attempt to access a database on the server causes ObjectStore to
attempt to reconnect to the server. You can also call os_server::reconnect( ) on
the server.
os_server::get_databases()
void get_databases(
os_int32 max_to_return,
os_database_p* dbs,
os_int32& n_returned
) const = 0;
Provides access to all databases associated with the specified ObjectStore server,
whether open or closed. The os_database_p* is an array of pointers to os_database
objects. This array must be allocated by the user. The function os_server::get_n_
databases( ) can be used to determine the size of an array to allocate. max_to_
return is specified by the user and represents the maximum number of elements the
array is to have. The n_returned argument is set by os_server::get_databases()
and represents the actual number of elements in the array.
os_server::get_host_name()
char* get_host_name( ) const;
Returns the name of the host of the specified ObjectStore server. It is the caller’s
responsibility to deallocate the string when it is no longer needed.
Overloading
The following is the non-const overloading of this function:
char* get_host_name();
For failover ObjectStore servers, this function returns the logical failover server host
name. Note that the logical server name is not always identical to the server name for
the machine providing access to the database. The caller should delete the returned
value. See os_failover_server::get_online_server_hostname() on page 222.
os_server::get_n_databases()
os_int32 get_n_databases( ) const = 0;
Returns the number of databases associated with the specified ObjectStore server,
whether open or closed.
368
C++ A P I Reference
Chapter 2: Class Library
os_server::is_failover()
os_boolean is_failover() const;
Returns nonzero (true) if, and only if, the os_server* is also an os_failover_
server. This function can be used to identify the os_failover_server in the list of
ObjectStore servers returned by objectstore::get_all_servers(). For more
information, see objectstore::get_all_servers() on page 62 and os_failover_
server on page 222.
os_server::reconnect()
void reconnect( );
Causes ObjectStore to attempt to reconnect to the specified ObjectStore server
immediately. Note that exceptions, such as err_server_refused_connection,
might result. Calling this function has no effect if the connection is not currently
broken.
Release 6.3
369
os_session
os_session
Instances of this class enable you to work with multiple sessions. For information
about using the os_session class and its function members, see Chapter 3,
Multithread and Multisession Applications, of the Advanced C++ A P I User Guide.
os_session::create()
static os_session* create(const char *name);
Creates a session with the specified name. See os_session::get_name() on
page 371.
When the session is initialized (see os_session::force_full_initialization()),
err_address_space_full is signaled if the session’s address space partition is too
small or if the partition size is too large to fit in any portion of free space in the
process-wide persistent storage region.
You are responsible for deleting the created session object when it is no longer
needed.
err_misc is signaled if the sessions facility has not been initialized for multisession
use.
os_session::force_full_initialization()
void force_full_initialization();
By default, a session‘s cache and address space partition are initialized when a
thread in that session first accesses a database. You can use os_session::force_
full_initialization() to override the default behavior and force initialization of
a session’s cache and partition. If the specified session has already been fully
initialized, calling this function has no effect.
err_address_space_full is signaled if the session’s address space partition is too
small or if the partition size is too large to fit in any portion of free space in the
process-wide persistent storage region.
os_session::get_all_sessions()
static os_session** get_all_sessions(
os_unsigned_int32& n_sessions
);
Returns a pointer to an array of os_session*s. After the function returns, n_
sessions refers to the number of elements in the array.
If the sessions facility has not been initialized for multisession use (see
objectstore::initialize_for_sessions() on page 73), the function returns a
pointer to an array whose only element points to a session named Global Session.
os_session::get_current()
static os_session* get_current();
370
C++ A P I Reference
Chapter 2: Class Library
Returns a pointer to the current session.
If the sessions facility has not been initialized for multisession use (see
objectstore::initialize_for_sessions() on page 73), the function returns a
pointer to an array whose only element points to a session named Global Session.
err_no_session is signaled if there is no current session.
os_session::get_n_sessions()
static os_unsigned_int32 get_n_sessions();
If ObjectStore has been initialized for multiple session use, returns the number of
sessions that have been created with os_session::create() and are currently
active.
Returns 0 if neither objectstore::initialize() nor objectstore::initialize_
for_sessions() has been called. Returns 1 if objectstore::initialize() has
been called and objectstore::initialize_for_sessions() has not.
See also objectstore::initialize_for_sessions() on page 73.
os_session::get_name()
const char* get_name() const;
Returns the name of this as specified by os_session::create(). If the sessions
facility has not been initialized for multisession use (see
objectstore::initialize_for_sessions() on page 73), the name of the current
session is Global Session.
os_session::get_thread_absorption()
os_boolean get_thread_absorption();
Returns nonzero if thread absorption is allowed; returns 0 if thread absorption is
disallowed.
See also os_session::set_thread_absorption() on page 372.
os_session::of()
static os_session* of(void const* addr);
Returns a pointer to the session in which the specified pointer (addr) was retrieved.
This is the session into whose address space partition the pointer is mapped. If the
sessions facility has not been initialized for multisession use (see
objectstore::initialize_for_sessions() on page 73), the function returns a
pointer to a session named Global Session. If addr is not in any session (for
example, it points to a transient object), the function returns 0.
os_session::operator delete()
void operator delete(void* p);
Release 6.3
371
os_session
Deletes the specified session and its associated transient objects (such as associated
instances of os_database). If you use transient objects associated with a deleted
session, dangling pointer errors can result. objectstore::shutdown() deletes all
sessions and their associated transient objects.
os_session::set_current()
static os_session* set_current(
os_session* new_current_session
);
Establishes new_current_session as the current session for the calling thread. If
new_current_session is 0, this function removes the thread from the current
session so that there is no current session when the function returns.
A pointer to the previously current session is returned. If there is no current session
before the call, new_current_session is established as the current session for the
calling thread, and 0 is returned.
os_session::set_thread_absorption()
void set_thread_absorption(os_boolean allowed);
Specifies whether thread absorption is allowed or disallowed. Thread absorption is
allowed by default. This allows threads to be absorbed into the current session.
Specifying 0 prevents threads from being absorbed into the session. An error, err_
absorption_not_allowed, is signaled if the following are are all true:
• The thread attempts to dereference an unmapped pointer to persistent memory
• The thread has no current session
• The pointer is retrieved in a session that disallows thread absorption
See also Thread Absorption in the Advanced C++ A P I User Guide.
os_session::unuse_DLL()
void os_session::unuse_DLL(const char* DLL_identifier);
Takes the component schema out of use in the current session.
os_session::use_DLL()
static os_DLL_handle os_session::use_DLL(
const char* DLL_identifier,
os_boolean error_if_not_found
);
Puts the specified component schema in use for the current session.
There is no need to call os_session::use_DLL() if the DLL is already loaded by
means of objectstore::load_DLL() or by means of an operating-system DLL load
API.
If the DLL is not yet loaded, this function attempts to load the specified DLL. The
component schema is put in use for the current session only.
372
C++ A P I Reference
Chapter 2: Class Library
os_soft_pointer32_base
This class serves as base class to os_soft_pointer32<T>. It defines comparison
operators, and decache(), hash(), dump(), and load() functions. See os_soft_
pointer32<T> on page 381 for more information.
In some cases, comparing two hard pointers has a different result from comparing
the corresponding soft pointers. Consider, for example, using the == operator to
compare hard pointers, where the referent type of one operand is a non-leftmost base
class of the referent type of the other operand, as in the following example:
class A { /* ... */};
class B { /* ... */};
class C : public A, public B { /* ... */};
C* pc = new C; // pc points to the beginning of C object
B* pb = pc; // pb points to the beginning of B part of C object
if (pc == pb)
cout << "true\n"; // will always execute
Given this coding, the compiler will evaluate the comparison pc == pb as true, even
though pb and pb point to different memory locations, because it treats the
comparison as if it were (B*)pc == pb and adjusts the pointers accordingly.
However, when the corresponding soft pointers are compared, no pointer
adjustment occurs; and, accordingly, the comparison evalutes to false.
For more information, see Ellis and Stroustrup, The Annotated C++ Reference Manual,
section 10.3c.
os_soft_pointer32_base::decache()
void decache( );
Causes the specified soft pointer to store its underlying value in unresolved format.
This affects only performance and address space release. Calling this function on a
soft pointer might slow the next resolution of the pointer but might hasten release of
the address space reserved for the pointer’s referent.
os_soft_pointer32_base::dump()
char* dump() const;
Returns a heap-allocated text string representing the specified soft pointer.
Overloading
The following overloading is supported:
char* dump(const char* db_str) const;
Returns a heap-allocated text string representing the specified soft pointer.
However, unlike the string returned by the char* os_soft_pointer32_
base::dump(void) function, this string does not contain an absolute database path.
The returned string is intended to be used as the dump_str argument of a soft pointer
load function of the form load(const char* dump_str, os_database* db). It is
the responsibility of the caller of load() to ensure that the db argument passed to the
Release 6.3
373
os_soft_pointer32_base
load function is the same as the database of the dumped soft pointer. It is the user’s
responsibility to delete the returned string when it is no longer needed.
This operation is useful in those applications in which you do not want the overhead
of storing the absolute database path in the dumped strings.
os_soft_pointer32_base::get_database()
os_database* get_database( ) const;
Returns a pointer to the database containing the referent of this.
os_soft_pointer32_base::get_database_key()
char* get_database_key(const char* dump_str);
Returns a heap-allocated string containing the database_key component of the
string dump_str. The dump_str argument must have been generated using the dump
operation. Otherwise, the exception err_reference_syntax is signaled. It is the
user’s responsibility to delete the returned string when it is no longer needed.
os_soft_pointer32_base::get_open_database()
os_database* get_open_database( ) const;
Returns a pointer to the database containing the referent of this. Opens the
database.
os_soft_pointer32_base::hash()
os_unsigned_int32 hash( ) const;
Returns an integer suitable for use as a hash table key. If two soft pointers refer to the
same object, hash() performed on one soft pointer returns the same value as hash
performed on the other soft pointer. In other words, hash() ensures that
coreferential soft pointers hash to the same value.
os_soft_pointer32_base::load()
void load(const char* dump_str);
The dump_str argument is assumed to be the result of a call to a compatible dump
function.
Overloading
The following overloading is supported:
void load(const char* dump_str, const os_database* db);
The dump_str argument is assumed to be the result of a call to a compatible dump
function. It is the responsibility of the caller of load() to ensure that the db argument
passed to the load function is the same as the database of the originally dumped soft
pointer.
The loaded soft pointer refers to the same object as the soft pointer used to dump the
string as long as the db argument is the same as the database of the dumped soft
pointer.
374
C++ A P I Reference
Chapter 2: Class Library
The exception err_reference_syntax is signaled if dump_str is not in the expected
format.
os_soft_pointer32_base::operator ==()
os_boolean operator ==(void const* right_arg) const;
os_boolean operator ==(
os_soft_pointer32_base const& right_arg) const;
os_boolean operator ==(
os_soft_pointer64_base const& right_arg) const;
Returns 1 if the this argument and right_arg have the same referent; returns 0
otherwise.
os_soft_pointer32_base::operator !()
os_boolean operator !(void const* arg) const;
os_boolean operator !(
os_soft_pointer32_base const& arg) const;
os_boolean operator !(
os_soft_pointer64_base const& arg) const;
Returns 1 if the argument is a null soft pointer; returns 0 otherwise.
os_soft_pointer32_base::operator !=()
os_boolean operator !=(void const* right_arg) const;
os_boolean operator !=(
os_soft_pointer32_base const& right_arg) const;
os_boolean operator !=(
os_soft_pointer64_base const& right_arg) const;
Returns 1 if the this argument and right_arg have different referents; returns 0
otherwise.
os_soft_pointer32_base::operator <()
os_boolean operator <(void const* right_arg) const;
os_boolean operator <(
os_soft_pointer32_base const& right_arg) const;
os_boolean operator <(
os_soft_pointer64_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes the referent of right_arg, and a return value of 0 indicates that
it does not. Otherwise, the results are undefined.
os_soft_pointer32_base::operator >()
os_boolean operator >(void const* right_arg) const;
os_boolean operator >(
os_soft_pointer32_base const& right_arg) const;
Release 6.3
375
os_soft_pointer32_base
os_boolean operator >(
os_soft_pointer64_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows the referent of right_arg, and a return value of 0 indicates that it
does not. Otherwise, the results are undefined.
os_soft_pointer32_base::operator <=()
os_boolean operator <=(void const* right_arg) const;
os_boolean operator <=(
os_soft_pointer32_base const& right_arg) const;
os_boolean operator <=(
os_soft_pointer64_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes or is the same as the referent of right_arg, and a return value of
0 indicates that it does not precede it or is not the same. Otherwise, the results are
undefined.
os_soft_pointer32_base::operator >=()
os_boolean operator >=(void const* right_arg) const;
os_boolean operator >=(
os_soft_pointer32_base const& right_arg) const;
os_boolean operator >=(
os_soft_pointer64_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows or is the same as the referent of right_arg, and a return value of
0 indicates that it does not follow it or is not the same. Otherwise, the results are
undefined.
os_soft_pointer32_base::~os_soft_pointer32_base()
~os_soft_pointer32();
Cleans up internal data structures.
os_soft_pointer32_base::resolve()
void* resolve( ) const;
Returns a hard pointer with the same referent as this soft pointer. Returns 0 if this
is a null soft pointer.
376
C++ A P I Reference
Chapter 2: Class Library
os_soft_pointer64_base
This class serves as base class to os_soft_pointer64<T>. It defines comparison
operators, and decache(), hash(), dump(), and load() functions. See os_soft_
pointer64<T> on page 384 for more information.
In some cases, comparing two hard pointers has a different result from comparing
the corresponding soft pointers. Consider, for example, using the == operator to
compare hard pointers, where the referent type of one operand is a non-leftmost base
class of the referent type of the other operand, as in the following example:
class A { /* ... */};
class B { /* ... */};
class C : public A, public B { /* ... */};
C* pc = new C; // pc points to the beginning of C object
B* pb = pc; // pb points to the beginning of B part of C object
if (pc == pb)
cout << "true\n"; // will always execute
Given this coding, the compiler will evaluate the comparison pc == pb as true, even
though pb and pb point to different memory locations, because it treats the
comparison as if it were (B*)pc == pb and adjusts the pointers accordingly.
However, when the corresponding soft pointers are compared, no pointer
adjustment occurs; and, accordingly, the comparison evalutes to false.
For more information, see Ellis and Stroustrup, The Annotated C++ Reference Manual,
section 10.3c.
os_soft_pointer64_base::decache()
void decache( );
Causes the specified soft pointer to store its underlying value in unresolved format.
This affects only performance and address space release. Calling this function on a
soft pointer might slow the next resolution of the pointer but might hasten release of
the address space reserved for the pointer’s referent.
os_soft_pointer64_base::dump()
char* dump() const;
Returns a heap-allocated text string representing the specified soft pointer.
Overloading
The following overloading is supported:
char* dump(const char* db_str) const;
Returns a heap-allocated text string representing the specified soft pointer.
However, unlike the string returned by the char* os_soft_pointer64_
base::dump(void) function, this string does not contain an absolute database path.
The returned string is intended to be used as the dump_str argument of a soft pointer
load function of the form load(const char* dump_str, os_database* db). It is
the responsibility of the caller of load() to ensure that the db argument passed to the
Release 6.3
377
os_soft_pointer64_base
load function is the same as the database of the dumped soft pointer. It is the user’s
responsibility to delete the returned string when it is no longer needed.
This operation is useful in those applications in which you do not want the overhead
of storing the absolute database path in the dumped strings.
os_soft_pointer64_base::get_database()
os_database* get_database( ) const;
Returns a pointer to the database containing the referent of this.
os_soft_pointer64_base::get_database_key()
char* get_database_key(const char* dump_str);
Returns a heap-allocated string containing the database_key component of the
string dump_str. The dump_str argument must have been generated using the dump
operation. Otherwise, the exception err_reference_syntax is signaled. It is the
user’s responsibility to delete the returned string when it is no longer needed.
os_soft_pointer64_base::get_open_database()
os_database* get_open_database( ) const;
Returns a pointer to the database containing the referent of this. Opens the
database.
os_soft_pointer64_base::hash()
os_unsigned_int32 hash( ) const;
Returns an integer suitable for use as a hash table key. If two soft pointers refer to the
same object, hash() performed on one soft pointer returns the same value as hash
performed on the other soft pointer. In other words, hash() ensures that
coreferential soft pointers hash to the same value.
os_soft_pointer64_base::load()
void load(const char* dump_str);
The dump_str argument is assumed to be the result of a call to a compatible dump
function.
Overloading
The following overloading is supported:
void load(const char* dump_str, const os_database* db);
The dump_str argument is assumed to be the result of a call to a compatible dump
function. It is the responsibility of the caller of load() to ensure that the db argument
passed to the load function is the same as the database of the originally dumped soft
pointer.
The loaded soft pointer refers to the same object as the soft pointer used to dump the
string as long as the db argument is the same as the database of the dumped soft
pointer.
378
C++ A P I Reference
Chapter 2: Class Library
The exception err_reference_syntax is signaled if dump_str is not in the expected
format.
os_soft_pointer64_base::operator ==()
os_boolean operator ==(void const* right_arg) const;
os_boolean operator ==(
os_soft_pointer64_base const& right_arg) const;
os_boolean operator ==(
os_soft_pointer32_base const& right_arg) const;
Returns 1 if the this argument and right_arg have the same referent; returns 0
otherwise.
os_soft_pointer64_base::operator !()
os_boolean operator !(void const* arg) const;
os_boolean operator !(
os_soft_pointer64_base const& arg) const;
os_boolean operator !(
os_soft_pointer32_base const& arg) const;
Returns 1 if the argument is a null soft pointer; returns 0 otherwise.
os_soft_pointer64_base::operator !=()
os_boolean operator !=(void const* right_arg) const;
os_boolean operator !=(
os_soft_pointer64_base const& right_arg) const;
os_boolean operator !=(
os_soft_pointer32_base const& right_arg) const;
Returns 1 if the this argument and right_arg have different referents; returns 0
otherwise.
os_soft_pointer64_base::operator <()
os_boolean operator <(void const* right_arg) const;
os_boolean operator <(
os_soft_pointer64_base const& right_arg) const;
os_boolean operator <(
os_soft_pointer32_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes the referent of right_arg, and a return value of 0 indicates that
it does not. Otherwise, the results are undefined.
os_soft_pointer64_base::operator >()
os_boolean operator >(void const* right_arg) const;
os_boolean operator >(
os_soft_pointer64_base const& right_arg) const;
Release 6.3
379
os_soft_pointer64_base
os_boolean operator >(
os_soft_pointer32_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows the referent of right_arg, and a return value of 0 indicates that it
does not. Otherwise, the results are undefined.
os_soft_pointer64_base::operator <=()
os_boolean operator <=(void const* right_arg) const;
os_boolean operator <=(
os_soft_pointer64_base const& right_arg) const;
os_boolean operator <=(
os_soft_pointer32_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument precedes or is the same as the referent of right_arg, and a return value of
0 indicates that it does not precede it or is not the same. Otherwise, the results are
undefined.
os_soft_pointer64_base::operator >=()
os_boolean operator >=(void const* right_arg) const;
os_boolean operator >=(
os_soft_pointer64_base const& right_arg) const;
os_boolean operator >=(
os_soft_pointer32_base const& right_arg) const;
If the this argument and right_arg refer to elements of the same array or one
beyond the end of the array, a return value of 1 indicates that the referent of the this
argument follows or is the same as the referent of right_arg, and a return value of
0 indicates that it does not follow it or is not the same. Otherwise, the results are
undefined.
os_soft_pointer64_base::~os_soft_pointer64_base()
~os_soft_pointer64();
Cleans up internal data structures.
os_soft_pointer64_base::resolve()
void* resolve( ) const;
Returns a hard pointer with the same referent as the this soft pointer. Returns 0 if
this is a null soft pointer.
380
C++ A P I Reference
Chapter 2: Class Library
os_soft_pointer32<T>
template <class T>
class os_soft_pointer32 : public os_soft_pointer32_base
ObjectStore provides several soft pointer classes, but usually your code should refer
only to instantiations of the class template os_soft_pointer<T>, such as os_soft_
pointer<employee>. The template parameter is the referent type, the type of object
referred to by the soft pointer. See the entry for the macro os_soft_pointer on
page 489.
Instances of this class are ObjectStore soft pointers for 32-bit platforms. Soft pointers
provide an alternative to using regular pointers to persistent memory. Soft pointers
reduce address space usage by deferring the reservation of address space for the soft
pointer’s referent until the soft pointer is dereferenced. See the Advanced C++ A P I
User Guide.
You can also use soft pointers to allow 32-bit applications to access persistent
pointers stored by 64-bit applications as well as to allow 64-bit applications to access
pointers stored by 32-bit applications.
Dereferencing a soft pointer is somewhat slower than dereferencing a regular, hard
pointer, but the soft pointer facility uses a caching mechanism to increase softpointer efficiency.
In a database, a soft pointer has the same format as a hard pointer. When one
application stores a soft pointer in a database, another application can subsequently
use the pointer as a regular, hard pointer. Inversely, when one application stores a
hard pointer in a database, another application subsequently can use the pointer as
a soft pointer.
An application’s (or DLL’s) schema specifies those pointers that are treated as soft by
the application (or DLL). For any pointer-valued data member in a database schema,
the application’s schema can specify the member’s value type as a soft pointer class
instead of a pointer type. These definitions are schema compatible.
Because an application’s schema specifies those pointers that are to be treated as soft,
only values of data members can be treated as soft pointers. Top-level pointers, or
pointers in top-level arrays cannot be treated as soft.
To defer address-space reservation for referents of top-level pointers, replace the
top-level pointers with instances of os_Reference. This class has an API just like the
soft pointer API.
os_soft_pointer32<T> defines constructors, assignment operators, a conversion
operator, operator ->(), and resolve(). Other soft pointer operations are
inherited from os_soft_pointer32_base; see os_soft_pointer32_base on
page 373.
If you use a soft pointer type whose referent type is not a class, you must call the
macro OS_SOFT_POINTER32_NOCLASS() on page 490, passing the referent type.
Release 6.3
381
os_soft_pointer32<T>
If a soft pointer refers to an object in a database that is not open, ObjectStore opens
the database automatically when the object is accessed (unless the autoopen mode is
auto_open_disable). The mode in which the database is opened is determined by
the value of objectstore::get_auto_open_mode().
In some cases, comparing two references has a different result from comparing the
corresponding pointers. See os_soft_pointer32_base on page 373 for more
information.
os_soft_pointer32<T>::operator =()
os_soft_pointer32<T>& operator =(
const os_soft_pointer32<T> const&
);
os_soft_pointer32<T>& operator =(
const os_soft_pointer64<T> const&
);
Establishes the referent of the right operand as the referent of the left operand.
Overloading
The following overloading is supported:
os_soft_pointer32<T>& operator =(T*);
Establishes the object pointed to by the right operand as the referent of the left
operand. If the right operand is 0, the left operand becomes a null soft pointer.
os_soft_pointer32<T>::operator T*()
operator T*( ) const;
Returns a hard pointer with the same referent as the this soft pointer. Returns 0 if
this is a null soft pointer.
os_soft_pointer32<T>::operator –>()
T* operator –>( ) const;
Returns a hard pointer with the same referent as the this soft pointer. Returns 0 if
this is a null soft pointer.
os_soft_pointer32<T>::os_soft_pointer32()
os_soft_pointer32();
Constructs a null soft pointer.
Overloadings
The following overloadings are supported:
os_soft_pointer32(T* hard_ptr);
Constructs a soft pointer with the same referent as the specifed hard pointer. If hard_
ptr is 0, constructs a null soft pointer.
os_soft_pointer32(os_soft_pointer32<T> const& soft_ptr);
os_soft_pointer32(os_soft_pointer64<T> const& soft_ptr);
382
C++ A P I Reference
Chapter 2: Class Library
Constructs a soft pointer with the same referent as the specifed soft pointer. If the
specified soft pointer is NULL, constructs a null soft pointer.
os_soft_pointer32<T>::resolve()
T* resolve( ) const;
Returns a hard pointer with the same referent as the this soft pointer. Returns 0 if
this is a null soft pointer.
Release 6.3
383
os_soft_pointer64<T>
os_soft_pointer64<T>
template <class T>
class os_soft_pointer64 : public os_soft_pointer64_base
ObjectStore provides several soft pointer classes, but usually your code should refer
only to instantiations of the class template os_soft_pointer<T>, such as os_soft_
pointer<employee>. The template parameter is the referent type, the type of object
referred to by the soft pointer. See the entry for the macro os_soft_pointer on
page 489.
Instances of this class are ObjectStore soft pointers for 64-bit platforms. Soft pointers
provide an alternative to using regular pointers to persistent memory. Soft pointers
reduce address space usage by deferring the reservation of address space for the soft
pointer’s referent until the soft pointer is dereferenced. See the Advanced C++ A P I
User Guide.
You can also use soft pointers to allow 32-bit applications to access persistent
pointers stored by 64-bit applications, as well as to allow 64-bit applications to access
pointers stored by 32-bit applications.
Dereferencing a soft pointer is somewhat slower than dereferencing a regular, hard
pointer, but the soft pointer facility uses a caching mechanism to increase softpointer efficiency.
In a database, a soft pointer has the same format as a hard pointer. When one
application stores a soft pointer in a database, another application can subsequently
use the pointer as a regular, hard pointer. Inversely, when one application stores a
hard pointer in a database, another application can subsequently use the pointer as
a soft pointer.
An application’s (or DLL’s) schema specifies those pointers that are treated as soft by
the application (or DLL). For any pointer-valued data member in a database schema,
the application’s schema can specify the member’s value type as a soft pointer class
instead of a pointer type. These definitions are schema compatible.
Because an application’s schema specifies those pointers that are to be treated as soft,
only values of data members can be treated as soft pointers. Top-level pointers, or
pointers in top-level arrays, cannot be treated as soft.
To defer address-space reservation for referents of top-level pointers, replace the
top-level pointers with instances of os_Reference. This class has an API just like the
soft pointer API.
os_soft_pointer64<T> defines constructors, assignment operators, a conversion
operator, operator ->(), and resolve(). Other soft pointer operations are
inherited from os_soft_pointer64_base on page 377.
If you use a soft pointer type whose referent type is not a class, you must call the
macro OS_SOFT_POINTER64_NOCLASS(), passing the referent type. For more
information about the macro, see OS_SOFT_POINTER64_NOCLASS() on page 491.
384
C++ A P I Reference
Chapter 2: Class Library
If a soft pointer refers to an object in a database that is not open, ObjectStore opens
the database automatically when the object is accessed (unless the autoopen mode is
auto_open_disable). The mode in which the database is opened is determined by
the value of objectstore::get_auto_open_mode().
In some cases, comparing two references has a different result from comparing the
corresponding pointers. See os_soft_pointer64_base on page 377 for more
information.
os_soft_pointer64<T>::operator =()
os_soft_pointer64<T>& operator =(
const os_soft_pointer64<T> const&
);
os_soft_pointer64<T>& operator =(
const os_soft_pointer32<T> const&
);
Establishes the referent of the right operand as the referent of the left operand.
Overloading
The following overloading is supported:
os_soft_pointer64<T>& operator =(T*);
Establishes the object pointed to by the right operand as the referent of the left
operand. If the right operand is 0, the left operand becomes a null soft pointer.
os_soft_pointer64<T>::operator T*()
operator T*( ) const;
Returns a hard pointer with the same referent as the this soft pointer. Returns 0 if
this is a null soft pointer.
os_soft_pointer64<T>::operator –>()
T* operator –>( ) const;
Returns a hard pointer with the same referent as the this soft pointer. Returns 0 if
this is a null soft pointer.
os_soft_pointer64<T>::os_soft_pointer64()
os_soft_pointer64();
Constructs a null soft pointer.
Overloadings
The following overloadings are supported:
os_soft_pointer64(T* hard_ptr);
Constructs a soft pointer with the same referent as the specifed hard pointer. If hard_
ptr is 0, constructs a null soft pointer.
os_soft_pointer64(os_soft_pointer64<T> const& soft_ptr);
os_soft_pointer64(os_soft_pointer32<T> const& soft_ptr);
Release 6.3
385
os_soft_pointer64<T>
Constructs a soft pointer with the same referent as the specifed soft pointer. If the
specified soft pointer is NULL, constructs a null soft pointer.
os_soft_pointer64<T>::resolve()
T* resolve( ) const;
Returns a hard pointer with the same referent as the this soft pointer. Returns 0 if
this is a null soft pointer.
386
C++ A P I Reference
Chapter 2: Class Library
os_soft_pointer32<void>
class os_soft_pointer32_void : public os_soft_pointer32_base
The definition of this class is generated by the macro OS_SOFT_POINTER32_
NOCLASS(). See OS_SOFT_POINTER32_NOCLASS() on page 490 for more information.
Release 6.3
387
os_soft_pointer64<void>
os_soft_pointer64<void>
class os_soft_pointer64_void : public os_soft_pointer64_base
The definition of this class is generated by the macro OS_SOFT_POINTER64_
NOCLASS(). See OS_SOFT_POINTER64_NOCLASS() on page 491 for more information.
388
C++ A P I Reference
Chapter 2: Class Library
os_soft_pointer32<char>
class os_soft_pointer32_void : public os_soft_pointer32_base
The definition of this class is generated by the macro OS_SOFT_POINTER32_
NOCLASS(). See OS_SOFT_POINTER32_NOCLASS() on page 490 for more information.
Release 6.3
389
os_soft_pointer64<char>
os_soft_pointer64<char>
class os_soft_pointer64_void : public os_soft_pointer64_base
The definition of this class is generated by the macro OS_SOFT_POINTER64_
NOCLASS(). See OS_SOFT_POINTER64_NOCLASS() on page 491 for more information.
390
C++ A P I Reference
Chapter 2: Class Library
os_str_conv
This class provides conversion facilities for various Japanese text encoding methods:
EUC, JIS, SJIS, Unicode, and UTF8.
It provides a facility, called autodetect, to detect the encoding of a given string. This
is useful for applications in which a client might send strings in an unknown format
— a common issue for Internet applications.
os_str_conv::change_mapping()
int change_mapping(mapping_table[],size_t table_sz);
You can modify the mapping behavior of an existing instance of os_str_conv
(whether heap- or stack-allocated) by calling os_str_conv::change_mapping().
Override information is stored for future conversion services associated with that
instance.
The override mapping information applies to any explicit mapping that has been
established for the given os_str_conv instance. Mappings of os_str_conv
instances cannot be overridden by instances using autodetect. Attempts to do so
return –1 from change_mapping() to indicate this error condition.
The change_mapping() function takes two arguments: mapping_table[] and
table_sz. The mapping_table[] argument is an array of mapping code pairs that
can be allocated locally, globally, or on the heap. If the array is heap allocated, the
user must delete it after calling change_mapping().
Internally, change_mapping() makes a sorted copy of mapping_table[]. The
sorting provides quick lookup at run time. The internal copy is freed when the os_
str_conv destructor is eventually called.
Note that the mapping pairs are unsigned 32-bit quantities, and the least significant
bit (LSB) is on the right. For example, the single-byte character 0x5C is represented
as 0x0000005C, and the two-byte code 0x81,0x54 is represented as 0x0000815F.
The table_sz argument is the number of elements (not bytes) in mapping_table[].
os_str_conv::convert()
Because Unicode is a 16-bit quantity, byte order depends on platform architecture.
(Other encodings are byte streams and therefore do not depend on processor
architecture.) On little-endian systems such as Intel, the low-order byte comes first.
On big-endian systems (Sparc, for example), the high-order byte is first.
Overloadings
There are three overloadings to the os_str_conv::convert() function to provide
flexibility for dealing with Unicode strings with different byte-ordering schemes. If
an argument is of char* type, all 16-bit quantities are considered big-endian
regardless of platform. However, if the type is os_unsigned_int16*, the values
assigned or read are handled according to the platform architecture.
The overloadings are as follows:
encode_type convert(char* dest, const char* src);
Release 6.3
391
os_str_conv
If either dest or src is a buffer containing Unicode characters, these 16-bit characters
are considered big-endian regardless of platform architecture.
encode_type convert(os_unsigned_int16* dest, const char* src);
Interprets 16-bit Unicode buffer dest according to the byte order of the processor
used.
encode_type convert(char* dest, const os_unsigned_int16* src);
Interprets 16-bit Unicode buffer src according to the byte order of the processor
used.
os_str_conv::get_converted_size()
virtual size_t get_converted_size(const char* src) const;
Returns the size of the buffer, in units of bytes, required to contain the converted
result of the given src string. If src is a Unicode string, its 16-bit characters are
considered big-endian regardless of platform architecture.
Because the entire source string must be examined, the time it takes for this function
to complete is proportional to the length of the source string.
If the autodetect mode is used and autodetect fails to determine the encoding of src,
get_converted_size() returns 0.
Overloading
The following overloading is supported:
virtual size_t get_converted_size(
const os_unsigned_int16* src
) const;
Returns the size of the buffer, in units of bytes, required to contain the converted
result of the given src string. If src is a Unicode string, its 16-bit characters are
interpreted according to the byte order of the processor used.
Because the entire source string must be examined, the time it takes for this function
to complete is proportional to the length of the source string.
If the autodetect mode is used and autodetect fails to determine the encoding of src,
get_converted_size() returns 0.
392
C++ A P I Reference
Chapter 2: Class Library
os_str_conv::os_str_conv()
os_str_conv(
encode_type_enum dest,
encode_type_enum src = AUTOMATIC
);
Instantiates a conversion path.
The value of encode_type_enum can be one of the following:
Release 6.3
Value
Meaning
AUTOMATIC
Determines the encoding of the source string
automatically. This automatic detection
distinguishes EUC and SJIS only. It might not
correctly detect SJIS if the string contains half-width
kana.
AUTOMATIC_ALLOW_KANA
Determines the encoding of the source string
automatically. This automatic detection
distinguishes EUC and SJIS only. This correctly
interprets SJIS strings that contain half-width kana,
but it might incorrectly interpret certain EUC strings
as SJIS strings.
ASCII
Strings are interpreted as single-byte ASCII
characters.
SJIS
Strings are interpreted as multibyte Japanese strings
of SJIS encoding.
EUC
Strings are interpreted as multibyte Japanese strings
of EUC encoding.
UNICODE
Strings are interpreted as Japanese strings of
Unicode encoding.
JIS
Strings are interpreted as multibyte Japanese strings
of JIS encoding.
UTF8
Strings are interpreted as multibyte Japanese strings
of UTF-8 encoding.
393
os_string
os_string
Instances of this class encapsulate null-terminated character arrays.
os_string::compare()
os_int16 compare(const os_string& str) const;
Performs a string comparison similar to the strcmp() function, and returns one of
three values to indicate the result of the comparison:
• 0 if the this string and the str argument have matching character arrays
• 1 if this is greater than str
• –1 if this is less than str
os_string::compare_nocase()
os_int16 compare_nocase(const os_string& str) const;
Performs a string comparison similar to the strcmp() function, but ignores case. The
return value indicates the result of the comparison and can be one of the following:
• 0 if the this string and the str argument have matching character arrays
• 1 if this is greater than str
• –1 if this is less than str
os_string::is_null()
os_boolean is_null() const;
Returns nonzero if the specified string is the null string; returns 0 otherwise.
os_string::operator const char*()
operator const char*();
Returns a pointer to the specified string’s character array.
os_string::operator =()
os_string& operator=(const os_string& str);
Sets the value of the specified string to a copy of the value of the specified string.
394
C++ A P I Reference
Chapter 2: Class Library
os_string::os_string()
os_string();
Constructs a null string.
Overloadings
The following overloadings are supported:
os_string(const char* ch);
Constructs a string whose value is a copy of the specified character array.
os_string(const os_string& str);
Constructs a copy of the specified string.
os_string::~os_string()
~os_string();
Deletes the private character array associated with the specified string.
Release 6.3
395
os_subscription
os_subscription
Objects of class os_subscription are created by users to perform subscription and
unsubscription operations. Note that you do not need to create os_subscription
objects in order to subscribe or unsubscribe. You can accomplish a single
subscription or unsubscription by passing an os_database, os_segment, os_
cluster, or address range directly to os_notification::subscribe() or os_
notification::unsubscribe().
The primary reason to manipulate os_subscription objects directly is to pass an
array of them to os_notification::subscribe(). os_
notification::subscribe() has overloadings that take the same sets of
arguments as os_subscription constructors. Use these if you want to subscribe to
only a single notification address. You can call these directly and completely bypass
the use of os_subscription objects.
The reason you might want to pass an array of os_subscription to os_
notification::subscribe() is that it is much more efficient to call os_
notification::subscribe() once with an array than to call it separately for each
subscription when there are multiple subscriptions to register.
Each os_subscription object represents an address range in an ObjectStore
database. Four constructors allow creation of subscriptions covering an entire
database, an entire segment, an entire object cluster, or a specific location range.
When passing database locations to os_subscription member functions, you need
not explicitly convert to os_soft_pointer.
os_subscription::assign()
void assign(const os_database* db);
Initializes or reassigns an os_subscription object to an entire database. You must
have previously created the object with the os_database overloading of the os_
subscription() constructor. Once the object has been created, you can use the
assign() function to reassign it as often as needed.
The assignment operator overloading (os_subscription::operator =()) has the
same purpose as the assign() function.
Overloadings
The following overloadings can be used to initialize or reassign an os_
subscription object to an entire segment, cluster, or address range:
void assign(const os_segment* seg);
void assign(const os_cluster* clstr);
void assign(const os_soft_pointer<void>& addr_range,
os_int32 number_of_bytes = 1);
You must use an overloading that has the same argument type as the overloading of
the constructor that you used to construct the os_subscription object.
396
C++ A P I Reference
Chapter 2: Class Library
The number_of_bytes argument to the os_soft_pointer overloading must be used
if the range referenced by addr_range is greater than 1.
os_subscription::get_database()
os_database* get_database();
The only accessor for os_subscription returns the database associated with the
subscription. An uninitialized os_subscription has a null (0) database.
Subscribe and unsubscribe nonstatic member functions are provided as shortcuts for
calling os_notification::subscribe() and os_notification::unsubscribe().
They are
• void subscribe();
• void unsubscribe();
See os_namespace on page 258 for more information about notification.
os_subscription::operator=()
os_subscription& operator=(const os_database* db);
Initializes or reassigns an os_subscription object to an entire database. You must
have previously created the object with the os_database overloading of the os_
subscription() constructor. Once the object has been created, you can use the
assignment operator to reassign it as often as needed.
The os_subscription::assign() function has the same purpose as the assignment
operator overloading.
Overloadings
The following overloadings can be used to initialize or reassign an os_
subscription object to an entire segment, cluster, or address:
os_subscription& operator=(const os_segment* seg);
os_subscription& operator=(const os_cluster* clstr);
os_subscription& operator=(const os_soft_pointer<void>& addr);
You must use an overloading that has the same argument type as the overloading of
the constructor that you used to construct the os_subscription object.
Note that you can use the os_soft_pointer overloading only if addr references a
single byte. For anything larger, you must must use the os_soft_pointer
overloading of os_subscription::assign().
When passing database locations to os_subscription member functions, you need
not explicitly convert to os_soft_pointer.
Release 6.3
397
os_subscription
os_subscription::os_subscription()
os_subscription();
Creates an uninitialized subscription. The default constructor.
After constructing an os_subscription object, you can use os_
subscription::assign() or one of the overloadings of the assignment operator to
initialize or reassign an os_subscription object.
Overloadings
The following overloadings create a subscription to an entire database, segment,
cluster, or address range:
os_subscription(const os_database* db);
os_subscription(const os_segment* seg);
os_subscription(const os_cluster* clstr);
os_subscription(
const os_soft_pointer<void>& addr_range,
os_int32 number_of_bytes = 1
);
The number_of_bytes argument to the last overloading must be used if the size of
the range referenced by addr_range is greater than 1 byte.
398
C++ A P I Reference
Chapter 2: Class Library
os_template
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent type or function
templates. os_type_template is derived from os_template; see os_type_
template on page 436.
os_template::Function
This enumerator is a possible return value from os_template::get_kind( ),
indicating a function template.
os_template::get_args()
os_List<const os_template_formal_arg*> get_args( ) const;
Returns a list, in declaration order, of the formal arguments of the specified template.
Each element of the list is a pointer to a const os_template_formal_arg.
os_template::get_kind()
enum os_template_kind {Type, Function};
os_template_kind get_kind( ) const;
Returns an enumerator indicating whether the specified template is a type template
or a function template. The possible return values are os_template::Type and os_
template::Function.
os_template::is_unspecified()
os_boolean is_unspecified( ) const;
Returns nonzero (true) if and only if the specified os_template is the unspecified
template. Some os_template-valued attributes in the MOP are required to have
values in a consistent schema, but they might lack values in the transient schema
before schema installation or evolution is performed. The get function for such an
attribute returns a reference to an os_template. The fact that a reference rather than
a pointer is returned indicates that the value is required in a consistent schema. In
the transient schema, if such an attribute lacks a value (because you have not yet
specified it), the get function returns the unspecified template. This is the only os_
template for which is_unspecified( ) returns nonzero.
os_template::operator const os_type_template&()
operator const os_type_template&( ) const;
Provides for safe conversion to const os_type_template. If the specified os_
template is not an os_type_template, err_mop_illegal_cast is signaled.
Release 6.3
399
os_template
os_template::operator os_type_template&()
operator os_type_template&( );
Provides for safe conversion to os_type_template. If the specified os_template is
not an os_type_template, err_mop_illegal_cast is signaled.
os_template::set_args()
void set_args(os_List<os_template_formal_arg*>&);
Specifies the list, in declaration order, of the formal arguments of the specified
template. Each element of the list is a pointer to an os_template_formal_arg.
os_template::Type
This enumerator is a possible return value from os_template::get_kind( ),
indicating a type template.
400
C++ A P I Reference
Chapter 2: Class Library
os_template_actual_arg
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent actual arguments
used to instantiate type or function templates. The types os_type_template_
actual_arg and os_literal_template_actual_arg are derived from os_
template_actual_arg.
os_template_actual_arg::get_kind()
enum os_template_actual_arg_kind {
type_actual,
literal_actual
};
os_template_actual_arg_kind get_kind( ) const;
Returns an enumerator indicating whether the specified actual is a type or a value
(that is, literal).
os_template_actual_arg::operator const os_literal_template_
actual_arg&()
operator const os_literal_template_actual_arg&( ) const;
Provides for safe conversion to const os_literal_template_actual_arg&. If the
specified os_template_actual_arg is not an os_literal_template_actual_arg,
err_mop_illegal_cast is signaled.
os_template_actual_arg::operator const os_type_template_
actual_arg&()
operator const os_type_template_actual_arg&( ) const;
Provides for safe conversion to const os_type_template_actual_arg&. If the
specified os_template_actual_arg is not an os_type_template_actual_arg,
err_mop_illegal_cast is signaled.
os_template_actual_arg::operator os_literal_template_actual_
arg&()
operator os_literal_template_actual_arg&( );
Provides for safe conversion to os_literal_template_actual_arg&. If the
specified os_template_actual_arg is not an os_literal_template_actual_arg,
err_mop_illegal_cast is signaled.
Release 6.3
401
os_template_actual_arg
os_template_actual_arg::operator os_type_template_actual_
arg&()
operator os_type_template_actual_arg&();
Provides for safe conversion to const os_type_template_actual_arg&. If the
specified os_template_actual_arg is not an os_type_template_actual_arg,
err_mop_illegal_cast is signaled.
402
C++ A P I Reference
Chapter 2: Class Library
os_template_formal_arg
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent formal arguments for
type or function templates. This class has no public members.
os_template_formal_arg::get_kind()
enum os_template_formal_arg_kind {Type, Value};
os_template_formal_arg_kind get_kind( ) const;
Returns an enumerator indicating whether the specified formal is a type argument
or a value argument (that is, whether its actuals are types or values).
os_template_formal_arg::get_name()
const char* get_name( ) const;
Returns the name of the specified formal argument.
os_template_formal_arg::operator const os_template_type_
formal&()
operator const os_template_type_formal&( ) const;
Provides for safe conversion to const os_template_type_formal&. If the specified
os_template_formal_arg is not an os_template_type_formal, err_mop_
illegal_cast is signaled.
os_template_formal_arg::operator const os_template_value_
formal&()
operator const os_template_value_formal&( )const;
Provides for safe conversion to const os_template_value_formal&. If the
specified os_template_formal_arg is not an os_template_value_formal, err_
mop_illegal_cast is signaled.
os_template_formal_arg::operator os_template_type_formal&()
operator os_template_type_formal&( );
Provides for safe conversion to os_template_type_formal&. If the specified os_
template_formal_arg is not an os_template_type_formal, err_mop_illegal_
cast is signaled.
os_template_formal_arg::operator os_template_value_
formal&()
operator os_template_value_formal&();
Provides for safe conversion to os_template_value_formal&. If the specified os_
template_formal_arg is not an os_template_value_formal, err_mop_illegal_
cast is signaled.
Release 6.3
403
os_template_formal_arg
os_template_formal_arg::set_name()
void set_name(const char* name);
Sets the name of the specified formal argument.
404
C++ A P I Reference
Chapter 2: Class Library
os_template_instantiation
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent instantiations of a
type or function template. The class os_type_template is derived from os_
template_instantiation; see os_type_template on page 436.
os_template_instantiation::create()
static os_template_instantiation& create(
os_template*,
os_List<os_template_actual_arg*>*
);
Creates an os_template_instantiation from the specified template and list of
actual arguments.
os_template_instantiation::get_args()
os_List<const os_template_actual_arg*> get_args( ) const;
Returns a list, in declaration order, of the actual arguments used to instantiate the
associated template. Each element of the list is a pointer to a const os_template_
actual_arg.
Overloadings
The following is the non-const overloading of this function:
os_List<os_template_actual_arg*> get_args( );
Returns a list, in declaration order, of the actual arguments used to instantiate the
associated template. Each element of the list is a pointer to an os_template_actual_
arg.
os_template_instantiation::get_template()
const os_template& get_template( ) const;
Returns the const template instantiated by the specified os_template_
instantiation.
Overloadings
The following is the non-const overloading of this function:
os_template& get_template( );
Returns the non-const template instantiated by the specified os_template_
instantiation.
os_template_instantiation::set_args()
void set_args(os_List<os_template_actual_arg*>&);
Sets, in declaration order, the actual arguments with which to instantiate the
associated template.
Release 6.3
405
os_template_instantiation
os_template_instantiation::set_template()
void set_template(os_template&);
Sets the template instantiated by the specified os_template_instantiation.
406
C++ A P I Reference
Chapter 2: Class Library
os_template_type_formal
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent formal template
parameters whose actuals are types. The class os_template_type_formal is
derived from os_template_formal_arg; see os_template_formal_arg on
page 403.
os_template_type_formal::create()
static os_template_type_formal& create(const char* name);
Creates an os_template_type_formal with the specified name.
Release 6.3
407
os_template_value_formal
os_template_value_formal
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent formal template
parameters whose actuals are values. The class os_template_value_formal is
derived from os_template_formal_arg; see os_template_formal_arg on
page 403.
os_template_value_formal::create()
static os_template_value_formal& create(
const char* name,
os_type* type
);
Creates an os_template_value_formal with the specified name. The actuals for the
created formal are instances of the specified type.
os_template_value_formal::get_type()
const os_type& get_type( ) const;
Returns a const reference to an os_type representing the type of actuals for the
specified formal.
Overloading
The following is the non-const overloading of this function:
os_type& get_type( );
Returns a non-const reference to an os_type representing the type of actuals for the
specified formal.
os_template_value_formal::set_type()
void set_type(os_type&);
Sets the type of actuals for the specified formal.
408
C++ A P I Reference
Chapter 2: Class Library
os_transaction
Instances of the class os_transaction represent transactions of the current session.
For more information about transactions, see Chapter 5, Transactions, in the C++
A P I User Guide.
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_transaction::abort()
static void abort(os_transaction* = get_current( ));
Aborts the specified transaction. For dynamic transactions, control flows to the next
statement after you call abort( ). For lexical transactions, control flows to the next
statement after the end of the current transaction block. Persistent data is rolled back
to its state at the beginning of the transaction. In addition, if the aborted transaction
is not nested within another transaction, all locks are released and other sessions can
access the pages that the aborted transaction accessed.
os_transaction::abort_top_level()
static void abort_top_level( );
Aborts the outermost transaction within which control currently resides. If the
current transaction is not nested, this function aborts the current transaction.
os_transaction::begin()
static os_transaction *begin(
transaction_type_enum t_type = os_transaction::update,
transaction_scope_enum t_scope = os_transaction::local
);
Begins a dynamic transaction. A pointer to an object representing the transaction is
returned. The user is responsible for deleting this object after terminating the
transaction. The t_type argument should be coded as either os_
transaction::update or os_transaction::read_only, depending on the type of
transaction desired. Unlike lexical transactions, which are started with a transaction
macro (OS_BEGIN_TXN() or OS_BEGIN_NAMED_TXN()), dynamic transactions are not
retried automatically when aborted because of deadlock. For information about the
lexical-transaction macros, see OS_BEGIN_TXN() on page 474.
The t_scope argument specifies whether a transaction is local (the default) or global.
To start a global transaction in a single session, call os_transaction::begin() with
the t_scope argument set to os_transaction::global. For information about local
and global transactions, see Local and Global Transactions in Chapter 5 of the C++
A P I User Guide.
Release 6.3
409
os_transaction
For multithreaded applications, calling os_transaction::begin() in one thread
can affect other, concurrent threads. For applications that do not use the sessions
facility, starting a transaction in one thread causes all other concurrent threads to
enter the same transaction. For applications that use the sessions facility, starting a
transaction in one thread causes all other concurrent threads in the calling thread's
current session to enter the same transaction.
ObjectStore performs automatic synchronization that prevents two threads from
entering the ObjectStore run time concurrently. However, you are responsible for
synchronizing threads’ access to your own persistent data.
Applications that do not use the sessions facility must synchronize access to
persistent data by all concurrent threads. In addition, such applications must
synchronize threads before a transaction commit, abort, or checkpoint; that is, when
one thread performs a commit, abort, or checkpoint, there must be no concurrent
access to persistent data by any other threads.
Applications that use the sessions facility must synchronize access to persistent data
by threads in the same session; ObjectStore synchronizes access to persistent data by
threads in different sessions. For more information, see Chapter 3, Multithread and
Multisession Applications, of the Advanced C++ A P I User Guide.
In addition, such applications must synchronize threads before a transaction
commit, abort, or checkpoint; that is, when one thread performs a commit, abort, or
checkpoint, no concurrent access to persistent data by other threads in the same
session is allowed.
All applications are responsible for synchronizing all threads’ access to transient
data.
Overloading
The following overloading is supported:
static os_transaction *os_transaction::begin(
char* name,
transaction_type_enum t_type = update,
transaction_scope_enum t_scope = local
);
Like the first overloading, except that the new transaction has the specified name.
os_transaction::checkpoint()
Note
Like transaction commit and abort, checkpoint operations are not thread safe.
Applications must ensure that other threads do not access persistent memory during
a checkpoint operation.
static void checkpoint();
Invokes checkpoint on the current transaction.
Overloadings
The following overloading is supported:
static checkpoint(os_transaction*);
410
C++ A P I Reference
Chapter 2: Class Library
Invokes checkpoint on the given transaction. Note that checkpoint is valid only for a
top-level dynamic transaction. Attempting to invoke a checkpoint on a nested or
lexical transaction results in an exception.
os_transaction::commit()
static void commit(os_transaction* = get_current( ));
Commits the specified dynamic transaction. Unlike transactions started with a
transaction statement, dynamic transactions are not retried automatically when the
transaction is aborted because of a deadlock.
os_transaction::get_current()
static os_transaction* get_current( );
Returns a pointer to the most deeply nested transaction in which control currently
resides. The value is 0 if no transaction is in progress.
os_transaction::get_name()
char* get_name( ) const;
Returns the name of the specified transaction, as set by os_transaction::set_
name( ). It is the caller’s responsibility to deallocate the string when it is no longer
needed.
os_transaction::get_parent()
os_transaction* get_parent( ) const;
Returns a pointer to the transaction within which the specified transaction is directly
nested.
os_transaction::get_scope()
os_transaction_scope_enum get_scope( ) const;
Returns os_transaction::local or os_transaction::global, depending on
whether the current transaction is local or global.
os_transaction::get_type()
os_transaction_type get_type( ) const;
Returns os_transaction::read_only or os_transaction::update, depending
on the one that is true of the current transaction.
os_transaction::is_aborted()
os_boolean is_aborted( ) const;
Returns nonzero if the specified dynamic transaction is aborted, and 0 otherwise. For
a transaction newly created by os_transaction::begin( ), 0 is returned.
Release 6.3
411
os_transaction
os_transaction::is_committed()
os_boolean is_committed( ) const;
Returns nonzero if the specified dynamic transaction is committed, and 0 otherwise.
For a transaction newly created by os_transaction::begin( ), 0 is returned.
os_transaction::is_lock_contention()
static os_boolean is_lock_contention();
Returns nonzero (true) if a ObjectStore server involved in the specified transaction
has experienced contention for some persistent memory that the calling application
is using; otherwise, returns 0 (false). It also returns false if it is not called from within
a transaction.
This function can be used in conjunction with multiversion concurrency control
(MVCC) to help determine whether to start a new transaction 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 (true).
Calling this function outside a transaction signals err_trans.
Note
is_lock_contention() is advisory only; it does not have to be called, and you can
ignore its return value without jeopardizing in any way the correctness of
ObjectStore's behavior.
os_transaction::is_prepared()
os_boolean is_prepared( ) const;
Returns nonzero (true) if os_transaction::prepare_to_commit() was invoked in
the current transaction; otherwise, returns 0 (false).
os_transaction::prepare_to_commit()
prepare_to_commit();
Performs, in advance, the parts of transaction commit that can fail due to the inability
to acquire a resource. If this function completes successfully, the actual transaction
commit is virtually reduced to sending a commit message to the ObjectStore server.
All the modified data was sent to the server during the invocation of the prepare_
to_commit() call. After the call to prepare_to_commit(), the only ObjectStore
operations that should occur are transaction commit or abort.
Some of the failures that can occur during the call to prepare_to_commit() are
• The client is selected as a deadlock victim by the server. The exception err_
deadlock would be signaled.
• The server runs out of disk space while it is growing a segment or writing to the
log file. The exception err_server_full would be signaled.
• The exception err_broken_server_connection can be signaled if the server fails
during commit.
412
C++ A P I Reference
Chapter 2: Class Library
Restrictions
Restrictions on use:
The exception err_prepare_to_commit is signaled if
• There is access to persistent data after a call to prepare_to_commit().
• Any objectstore operation other than commit or abort is attempted after a call
to prepare_to_commit().
• The function is invoked within a nested transaction.
After err_prepare_to_commit is handled, the transaction cannot do anything else
with ObjectStore and it must call os_transaction::abort_top_level().
os_transaction::read_only
This enumerator is an optional argument used in the transaction macros OS_BEGIN_
TXN() and OS_BEGIN_NAMED_TXN() or as an argument to os_
transaction::begin(). It specifies a transaction that performs no updates on
persistent storage.
For information about the macros, see OS_BEGIN_TXN() on page 474. For
information about begin(), see os_transaction::begin() on page 409.
os_transaction::session_of()
os_session* session_of() const;
Returns the os_session object for the session in which the specified os_
transaction* was retrieved.
This function can be used with os_session::set_current() to enable a thread to
join the session associated with an os_transaction object. For example, if txn_ptr
references an os_transaction object, then the statement
os_session::set_current(txn_ptr->session_of());
enables the currently executing thread to access the object by setting the thread’s
current session to the session associated with txn_ptr.
os_transaction::set_name()
void set_name(const char* new_name);
Sets the name of the specified transaction. The function copies the string new_name.
os_transaction::top_level()
os_boolean top_level( ) const;
Returns nonzero if the specified transaction is nonnested; returns 0 otherwise.
Release 6.3
413
os_transaction
os_transaction::update
This enumerator is an optional argument used in the transaction macros OS_BEGIN_
TXN() and OS_BEGIN_NAMED_TXN() or as an argument to os_
transaction::begin(). It specifies a transaction that performs updates on
persistent storage.
For information about the macros, see OS_BEGIN_TXN() on page 474. For
information about begin(), see os_transaction::begin() on page 409.
414
C++ A P I Reference
Chapter 2: Class Library
os_transaction_hook
This class provides functions for registering and deregistering transaction hook
functions. It also provides enumerators for specifying the type of event to trigger
invocation of a given hook function.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/tranhook.hh>.
os_transaction_hook::after_begin
This enumerator is used as an argument to register_hook( ) to specify that a hook
function is to be invoked immediately after each transaction begins.
The type is event_type.
os_transaction_hook::after_checkpoint
This enumerator is used as an argument to register_hook( ) to specify that a hook
function is to be invoked after os_transaction::checkpoint() completes its work
and before control is returned to the caller. For information about the checkpoint()
function, see os_transaction::checkpoint() on page 410.
The type is event_type.
os_transaction_hook::after_commit
This enumerator is used as an argument to register_hook( ) to specify that a hook
function is to be invoked immediately after each transaction commit.
The type is event_type.
os_transaction_hook::before_abort
This enumerator is used as an argument to register_hook( ) to specify that a hook
function is to be invoked immediately before each transaction abort.
The type is event_type.
os_transaction_hook::before_checkpoint
This enumerator is used as an argument to register_hook( ) to specify that a hook
function is to be invoked before os_transaction::checkpoint() starts its work.
For information about the checkpoint() function, see os_
transaction::checkpoint() on page 410.
The type is event_type.
Release 6.3
415
os_transaction_hook
os_transaction_hook::before_commit
This enumerator is used as an argument to register_hook( ) to specify that a hook
function is to be invoked immediately before each transaction commit.
The type is event_type.
os_transaction_hook::before_retry
This enumerator is used as an argument to register_hook( ) to specify that a hook
function is to be invoked immediately before each retry of an aborted transaction.
The type is event_type.
os_transaction_hook::deregister_hook()
static void deregister_hook(os_int32 event_type);
Deregisters all hook functions with event type event_type. Note that if a previously
registered hook function was returned by register_hook( ), it must be reregistered.
os_transaction_hook::register_hook()
typedef void (*hook_t)(
const os_transaction_hook::event_type,
const os_transaction* txn
);
static hook_t register_hook(
os_transaction_hook::event_type,
hook_t hook_fn
);
Registers hook_fn and specifies that it should be called each time an event of type
os_transaction_hook::event_type occurs. The value of os_transaction_
hook::event_type is one of the following enumerators:
• os_transaction_hook::after_begin on page 415
• os_transaction_hook::after_commit on page 415
• os_transaction_hook::before_abort on page 415
• os_transaction_hook::before_commit on page 416
• os_transaction_hook::before_retry on page 416
A pointer to the current hook function is returned, or 0 is returned if there is none.
The application must ensure that any previously registered hook functions, as
returned by register_hook( ), are called at some point during the execution of the
current hook function.
When hook_fn is invoked, the arguments passed to it are as follows: the first
argument (os_transaction_hook::event_type) is an enumerator indicating the
type of event that triggered invocation. The second argument is a pointer to the
current transaction. If the first argument is os_transaction_hook::before_retry,
the second argument is 0.
Caution
416
Do not abort or commit the current transaction from within a hook function.
C++ A P I Reference
Chapter 2: Class Library
os_transformer_binding
Instances of this class represent an association between a class and a transformer
function. Instances of os_transformer_binding are used as arguments to os_
schema_evolution::augment_pre_evol_transformers( ) and os_schema_
evolution::augment_post_evol_transformers( ). Instances should be allocated
only in transient memory.
os_transformer_binding::os_transformer_binding()
os_transformer_binding(
char* class_name,
void (*func)(void*)
);
Associates the class named class_name with the function func.
Release 6.3
417
os_type
os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent C++ types.
Type definitions
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.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_type::Anonymous_indirect
This enumerator indicates a const or volatile type. It is a possible return value
from os_type::get_kind( ).
os_type::Array
This enumerator indicates an array type. It is a possible return value from os_
type::get_kind( ).
os_type::Char
This enumerator indicates a character type. It is a possible return value from os_
type::get_kind( ).
os_type::Class
This enumerator indicates a class. It is a possible return value from os_type::get_
kind( ).
os_type::Double
This enumerator indicates the type double. It is a possible return value from os_
type::get_kind( ).
os_type::Enum
This enumerator indicates an enumeration type. It is a possible return value from os_
type::get_kind( ).
os_type::Float
This enumerator indicates the type float. It is a possible return value from os_
type::get_kind( ).
os_type::Function
This enumerator indicates a function type. It is a possible return value from os_
type::get_kind( ).
418
C++ A P I Reference
Chapter 2: Class Library
os_type::get_alignment()
os_unsigned_int32 get_alignment( ) const;
Gets the alignment associated with the type.
os_type::get_enclosing_class()
const os_class_type *get_enclosing_class( ) const;
If a class’s definition is nested within that of another class, this other class is the
enclosing class of the nested class. The function returns a const pointer to the
enclosing class, or 0 if there is no enclosing class.
os_class_type *get_enclosing_class( );
If a class’s definition is nested within that of another class, this other class is the
enclosing class of the nested class. The function returns a non-const pointer to the
enclosing class, or 0 if there is no enclosing class.
os_type::get_kind()
os_unsigned_int32 get_kind( ) const;
Returns one of the following enumerators describing the specified instance of os_
type:
• Type
• Void
• Unsigned_char
• Signed_char
• Char
• Wchar_t
• Unsigned_short
• Signed_short
• Integer
• Unsigned_integer
• Signed_long
• Unsigned_long
• Float
• Double
• Long_double
• Named_indirect
• Anonymous_indirect
• Pointer
• Reference
• Pointer_to_member
• Array
• Class
• Instantiated_class
• Enum
• Function
Release 6.3
419
os_type
• Undefined
These enumerators are defined within the scope of the class os_type.
os_type::get_kind_string()
static const char* get_kind_string(os_type_kind);
Returns a string representation of a type kind, as specified with one of the
enumerators returned by get_kind( ).
os_type::get_size()
os_unsigned_int32 get_size( );
Returns the size of the specified type in bytes.
os_type::get_string()
char* get_string( ) const;
Returns a new string containing a printable representation of the specified instance
of os_type. The string must be deleted after its value has been consumed.
os_type::Instantiated_class
This enumerator indicates a class that is an instantiation of a class template. It is a
possible return value from os_type::get_kind( ).
os_type::Integer
This enumerator indicates the type int. It is a possible return value from os_
type::get_kind( ).
os_type::is_class_type()
os_boolean os_type::is_class_type() const;
Returns 1 if the type is an os_class_type or os_instantiated_class_type.
os_type::is_const()
os_boolean is_const( ) const;
Returns 1 if and only if the type expression associated with the specified instance of
os_type includes a const type specifier.
os_type::is_indirect_type()
os_boolean os_type::is_indirect_type() const;
Returns true if the type is an os_anonymous_indirect_type or an os_named_
indirect_type.
os_type::is_integral_type()
os_boolean is_integral_type( ) const;
420
C++ A P I Reference
Chapter 2: Class Library
Returns nonzero if the specified os_type is an instance of os_integral_type, such
as one representing the type unsigned int. Returns 0 otherwise.
os_type::is_pointer_type()
os_boolean os_type::is_pointer_type() const;
Returns 1 if the type is an os_pointer_type, os_reference_type, or an os_
pointer_to_member_type.
os_type::is_real_type()
os_boolean is_real_type( ) const;
Returns nonzero if the specified os_type is an instance of os_real_type, such as one
representing the type long double. Returns 0 otherwise.
os_type::is_unspecified()
os_boolean is_unspecified( ) const;
Returns nonzero if and only if the specified os_type is the unspecified type. Some
os_type-valued attributes in the MOP are required to have values in a consistent
schema but might lack values in the transient schema before schema installation or
evolution is performed. The get function for such an attribute returns a reference to
an os_type or os_class_type. The fact that a reference rather than a pointer is
returned indicates that the value is required in a consistent schema. In the transient
schema, if such an attribute lacks a value (because you have not yet specified it), the
get function returns the unspecified type. This is the only os_type for which is_
unspecified( ) returns nonzero.
os_type::is_volatile()
os_boolean is_volatile( ) const;
Returns 1 if and only if the type expression associated with the specified instance of
os_type includes a volatile type specifier.
os_type::Long_double
This enumerator indicates the type long double. It is a possible return value from
os_type::get_kind( ).
os_type::Named_indirect
This enumerator indicates a typedef. It is a possible return value from os_
type::get_kind( ).
os_type::operator const os_anonymous_indirect_type&()
operator const os_anonymous_indirect_type&( ) const;
Provides for safe casts from const os_type to const os_anonymous_indirect_
type&. If the cast is not permissible, err_mop_illegal_cast is signaled.
Release 6.3
421
os_type
os_type::operator const os_array_type&()
operator const os_array_type&( ) const;
Provides for safe casts from const os_type to const os_array_type&. If the cast is
not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_class_type&()
operator const os_class_type&( ) const;
Provides for safe casts from const os_type to const os_class_type&. If the cast is
not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_enum_type&()
operator const os_enum_type&( ) const;
Provides for safe casts from const os_type to const os_enum_type&. If the cast is
not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_function_type&()
operator const os_function_type&( ) const;
Provides for safe casts from const os_type to const os_function_type&. If the
cast is not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_instantiated_class_type&()
operator const os_instantiated_class_type&( ) const;
Provides for safe casts from const os_type to const os_instantiated_class_
type&. If the cast is not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_integral_type&()
operator const os_integral_type&( ) const;
Provides for safe casts from const os_type to const os_integral_type&. If the
cast is not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_named_indirect_type&()
operator const os_named_indirect_type&( ) const;
Provides for safe casts from const os_type to const os_named_indirect_type&.
If the cast is not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_pointer_to_member_type&()
operator const os_pointer_to_member_type&( ) const;
Provides for safe casts from const os_type to const os_pointer_to_member_
type&. If the cast is not permissible, err_mop_illegal_cast is signaled.
422
C++ A P I Reference
Chapter 2: Class Library
os_type::operator const os_pointer_type&()
operator const os_pointer_type&( ) const;
Provides for safe casts from const os_type to const os_pointer_type&. If the cast
is not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_real_type&()
operator const os_real_type&( ) const;
Provides for safe casts from const os_type to const os_real_type&. If the cast is
not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_reference_type&()
operator const os_reference_type&( ) const;
Provides for safe casts from const os_type to const os_reference_type&. If the
cast is not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_type_type&()
operator const os_type_type&( ) const;
Provides for safe casts from const os_type to const os_type_type&. If the cast is
not permissible, err_mop_illegal_cast is signaled.
os_type::operator const os_void_type&()
operator const os_void_type&( ) const;
Provides for safe casts from const os_type to const os_void_type&. If the cast is
not permissible, err_mop_illegal_cast is signaled.
os_type::operator os_anonymous_indirect_type&()
operator os_anonymous_indirect_type&( );
Provides for safe casts from os_type to os_anonymous_indirect_type&. If the cast
is not permissible, err_mop_illegal_cast is signaled.
os_type::operator os_array_type&()
operator os_array_type&( );
Provides for safe casts from os_type to os_array_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_class_type&()
operator os_class_type&( );
Provides for safe casts from os_type to os_class_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
Release 6.3
423
os_type
os_type::operator os_enum_type&()
operator os_enum_type&( );
Provides for safe casts from os_type to os_enum_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_function_type&()
operator os_function_type&( );
Provides for safe casts from os_type to os_function_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_instantiated_class_type&()
operator os_instantiated_class_type&( );
Provides for safe casts from os_type to os_instantiated_class_type&. If the cast
is not permissible, err_mop_illegal_cast is signaled.
os_type::operator os_integral_type&()
operator os_integral_type&( );
Provides for safe casts from os_type to os_integral_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_named_indirect_type&()
operator os_named_indirect_type&( );
Provides for safe casts from os_type to os_named_indirect_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_pointer_to_member_type&()
operator os_pointer_to_member_type&( );
Provides for safe casts from os_type to os_pointer_to_member_type&. If the cast
is not permissible, err_mop_illegal_cast is signaled.
os_type::operator os_pointer_type&()
operator os_pointer_type&( );
Provides for safe casts from os_type to os_pointer_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_real_type&()
operator os_real_type&( );
Provides for safe casts from os_type to os_real_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
424
C++ A P I Reference
Chapter 2: Class Library
os_type::operator os_reference_type&()
operator os_reference_type&( );
Provides for safe casts from os_type to os_reference_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_type_type&()
operator os_type_type&( );
Provides for safe casts from os_type to os_type_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::operator os_void_type&()
operator os_void_type&( );
Provides for safe casts from os_type to os_void_type&. If the cast is not
permissible, err_mop_illegal_cast is signaled.
os_type::Pointer
This enumerator indicates a pointer type. It is a possible return value from os_
type::get_kind( ).
os_type::Pointer_to_member
This enumerator indicates a pointer-to-member type. It is a possible return value
from os_type::get_kind( ).
os_type::Reference
This enumerator indicates a reference type. It is a possible return value from os_
type::get_kind( ).
os_type::set_alignment()
void set_alignment(os_unsigned_int32);
Sets the alignment associated with the type.
os_type::set_size()
void set_size (os_unsigned_int32 size) _OS_throw (err_mop);
Sets the size of the specified type in bytes.
os_type::Signed_char
This enumerator indicates the type signed char. It is a possible return value from
os_type::get_kind( ).
Release 6.3
425
os_type
os_type::Signed_long
This enumerator indicates the type long. It is a possible return value from os_
type::get_kind( ).
os_type::Signed_short
This enumerator indicates the type short. It is a possible return value from os_
type::get_kind( ).
os_type::strip_indirect_types()
const os_type& strip_indirect_types( ) const;
For types with const or volatile specifiers, this function returns a const reference
to the type being specified as const or volatile. For example, if the specified os_
type represents the type const int, then strip_indirect_types() returns an os_
type representing the type int. If the specified os_type represents the type char
const* const, then strip_indirect_types() returns an os_type representing the
type char const*.
For typedefs, this function returns the original type for which the typedef is an
alias.
This function calls itself recursively until the result is not an os_indirect_type. So,
for example, consider an os_named_indirect_type representing
typedef const part const_part;
The result of applying strip_indirect_types( ) to this is an os_class_type
representing the class part (not an os_anonymous_indirect_type representing
const part, which would be the result of os_indirect_type::get_target_
type( )).
Overloadings
The following overloadings are supported:
os_type& strip_indirect_types( );
For types with const or volatile specifiers, this function returns a non-const
reference to the type being specified as const or volatile. For example, if the
specified os_type represents the type const int, strip_indirect_types()
returns an os_type representing the type int. If the specified os_type represents the
type char const* const, strip_indirect_types() returns an os_type
representing the type char const*.
For typedefs, this function returns the original type for which the typedef is an
alias.
This function calls itself recursively until the result is not an os_indirect_type. So,
for example, consider an os_named_indirect_type representing
typedef const part const_part;
The result of applying strip_indirect_types( ) to this is an os_class_type
representing the class part (not an os_anonymous_indirect_type representing
426
C++ A P I Reference
Chapter 2: Class Library
const part, which would be the result of os_indirect_type::get_target_
type( )).
os_type::Type
This enumerator indicates a type serving as a parameter to a class or function
template. It is a possible return value from os_type::get_kind( ).
os_type::type_at()
static const os_type* type_at(const void* p);
Returns the type of the object that begins at location p. The p argument should point
to the beginning of an instance of a class or built-in type such as int. The instance
can be allocated at top level, or it can be the value of a data member or the subobject
corresponding to a base class. If p does not point to the beginning of such an instance,
0 is returned. If two or more objects start at p, the type of the innermost object is
returned.
os_type::type_containing()
static const os_type* type_containing(
const void* p,
const void*& p_container,
os_unsigned_int32& element_count
);
If the outermost object that contains the location p is not an array, this function
returns the type of the outermost containing object. The argument p_container is
modified to point to the containing object, and element_count is set to 0.
If the outermost containing object is an array, the function sets element_count to the
number of elements in the array, adjusts p_container to point to the first element of
the array, and returns the element type of the array.
If p points to released or transient memory, os_type::type_containing() returns
0 and sets p_container and element_count to 0.
os_type::Undefined
This enumerator indicates a type whose kind cannot be determined. It is a possible
return value from os_type::get_kind( ).
os_type::Unsigned_char
This enumerator indicates the type unsigned char. It is a possible return value from
os_type::get_kind( ).
os_type::Unsigned_integer
This enumerator indicates the type unsigned int. It is a possible return value from
os_type::get_kind( ).
Release 6.3
427
os_type
os_type::Unsigned_long
This enumerator indicates the type unsigned long. It is a possible return value from
os_type::get_kind( ).
os_type::Unsigned_short
This enumerator indicates the type unsigned short. It is a possible return value
from os_type::get_kind( ).
os_type::Void
This enumerator indicates the type void. It is a possible return value from os_
type::get_kind( ).
428
C++ A P I Reference
Chapter 2: Class Library
os_Type_fixup_info
This class is part of the dump/load facility and is used by implementers of
customized dump and load utilities. It specifies the protocol for a user-defined class
derived from it. The derived class holds information about the loading of the fixup
form currently being processed.
See Chapter 6, Dump/Load Facility, in the Advanced C++ A P I User Guide for
information on customizing the dumping and loading of ObjectStore databases.
This section describes the behavior, if implemented correctly, of the members of os_
Type_fixup_info. The class type_fixup_info is a class that is derived from os_
Type_fixup_info for customization of the loading of the type type.
os_Type_fixup_info::fixup_data
type_fixup_data& fixup_data;
The class type_fixup_data is derived from os_Type_data (this base class has no
members). type_fixup_data has a data member for each portion of the fixup-form
value emitted by type_dumper::operator ()().
See Specializing os_Type_fixup_info in the Advanced C++ A P I User Guide for
information on implementing this function.
os_Type_fixup_info::os_Type_fixup_info()
type_fixup_info (
os_Type_fixup_loader cur_fixup_loader,
os_Loader_stream lstr,
os_Object_info& info,
type_fixup_data& data_arg
);
Constructs an instance of type_fixup_info.
The cur_fixup_loader argument is the fixup loader for the object currently being
fixed up. The lstr argumentis the dump stream from which the current fixup form
is being processed. The info argument is the fixup info for the object being fixed up.
data_arg is used to set the member type_fixup_info::type_data.
See Specializing os_Type_fixup_info in the Advanced C++ A P I User Guide for
information on implementing this function.
Release 6.3
429
os_Type_fixup_loader
os_Type_fixup_loader
This class is part of the dump/load facility and is used by implementers of
customized dump and load utilities. It is an abstract base class that specifies the
protocol for a user-defined class derived from it. The derived class handles the
loading of fixup forms.
See Chapter 6, Dump/Load Facility, in the Advanced C++ A P I User Guide for
information on customizing the dumping and loading of ObjectStore databases.
This section describes the behavior, if implemented correctly, of the members of os_
Type_fixup_loader. The class type_fixup_loader is a class that is derived from
os_Type_fixup_loader for customization of the loading of the type type.
os_Type_fixup_loader::fixup()
void type_fixup_loader::fixup (
os_Type_fixup_info& info,
os_boolean is_most_derived_class
);
This function performs fixup based on the information passed in. For example, if the
object being fixed up is a collection and each portion of the fixup form identifies a
collection element, fixup() inserts an element in the collection.
is_most_derived_class indicates whether the object being fixed up is a direct
instance of type. 1 indicates that the object is a direct instance of type; 0 indicates
that the object is a direct instance of a class derived from type.
See Implementing fixup() in the Advanced C++ A P I User Guide for information on
implementing this function.
os_Type_fixup_loader::get()
static os_Type_fixup_loader& type_fixup_loader::get ();
Returns an instance of type_fixup_loader.
See Implementing get() in the Advanced C++ A P I User Guide for information on
implementing this function.
430
C++ A P I Reference
Chapter 2: Class Library
os_Type_fixup_loader::load()
Loader_action* type_fixup_loader::load (
Loader_stream& stream,
Type_data& given_data,
os_boolean is_most_derived_class
);
Loads part or all of the info portion of a fixup form from the load stream and sets
the data members of given_data accordingly.
is_most_derived_class indicates whether the object being fixed up is a direct
instance of type. A value of 1 indicates that the object is a direct instance of type; a
value of 0 indicates that the object is a direct instance of a class derived from type.
This function returns 0 when the entire info portion is consumed.
See Implementing load() in the Advanced C++ A P I User Guide for information on
implementing this function.
os_Type_fixup_loader::operator ()()
os_Loader_action* type_fixup_loader::operator () (
os_Loader_stream& stream,
os_Loader_info& previous_info
);
Loads a fixup form and performs the corresponding fixups, including
creation of nonroot objects.
This function returns 0 for success.
See Implementing operator ()() in the Advanced C++ A P I User Guide for information
on implementing this function.
Release 6.3
431
os_Type_info
os_Type_info
This class is part of the dump/load facility and is used by implementers of
customized dump and load utilities. It specifies the protocol for a user-defined class
derived from it. The derived class holds information about the loading of the object
form currently being processed.
os_Type_info defines members for getting the type and predump location of the
object being loaded or fixed up, as well as members for getting and setting the
postload location of the object.
See Chapter 6, Dump/Load Facility, in the Advanced C++ A P I User Guide for
information on customizing the dumping and loading of ObjectStore databases.
This section describes the behavior, if implemented correctly, of the members of os_
Type_info that can be implemented in the derived class. It also describes some
members that are implemented only by the base class. The class type_info is a class
that is derived from os_Type_info for customization of the loading of the type type.
os_Type_info::data
type_data& data;
The class type_data is derived from os_Type_data (this base class has no
members). type_data has a data member for each portion of the object-form value
emitted by type_dumper::operator ()(). type_data has a data member for each
data member and base class of type.
See Implementing data in the Advanced C++ A P I User Guide for information on
implementing this function.
os_Type_info::get_original_location()
os_Dumper_reference get_original_location () const;
Returns a reference that resolves to the predump location of the object being loaded.
os_Type_info::get_replacing_database()
os_database& get_replacing_database () const;
Returns a reference to the postload database of the object being loaded.
os_Type_info::get_replacing_location()
os_Dumper_reference get_replacing_location () const;
Returns a reference that resolves to the postload location of the object being loaded.
os_Type_info::get_replacing_segment()
os_segment& get_replacing_segment () const;
Returns a reference to the postload segment of the object being loaded.
432
C++ A P I Reference
Chapter 2: Class Library
os_Type_info::get_type()
const os_type& get_type () const;
Returns a reference to an os_type that represents the type of the object being loaded.
os_Type_info::os_Type_info()
type_info::type_info (
type_loader& cur_loader,
os_Loader_stream& lstr,
os_Object_info& info,
type_data& data_arg
);
Constructs an instance of type_info.
cur_loader is the loader for the object currently being loaded. The lstr argument
is the dump stream from which the current object form is being processed. The info
argument is the loader info for the object loaded just previously. data_arg is used
to set the member type_info::type_data.
Instances of this class hold information about the loading of the object form or fixup
form currently being processed.
See Specializing os_Type_info in the Advanced C++ A P I User Guide for information
on implementing this function.
Overloading
The following overloading is supported:
os_Type_info::os_Type_info (
os_Type_loader&,
os_Loader_stream&,
os_Object_info&
);
Constructs an object to hold information about the object currently being loaded by
a specified loader. The last argument is the info for the previous object load.
os_Type_info::set_replacing_location()
void set_replacing_location (os_Dumper_reference location);
Records the location at which the postload object has been created. This is a
protected member of os_Type_info.
Release 6.3
433
os_Type_loader
os_Type_loader
This class is part of the dump/load facility and is used by implementers of
customized dump and load utilities. It is an abstract base class that specifies the
protocol for a user-defined class derived from it. The derived class handles the
loading of object forms.
See Chapter 6, Dump/Load Facility, in the Advanced C++ A P I User Guide for
information on customizing the dumping and loading of ObjectStore databases.
This section describes the behavior, if implemented correctly, of the members of os_
Type_loader that can be implemented in the derived class. The class type_loader
is a class that is derived from os_Type_loader for customization of the loading of
the type type.
os_Type_loader::create()
void type_loader::create (os_Loader_info& given_info);
Creates and performs fixup on the persistent object corresponding to the object form
being loaded. Arguments to persistent new() are retrieved from given_info.
Arguments to the object constructor are retrieved from the type_data associated
with given_info.
See Implementing create() in the Advanced C++ A P I User Guide for information on
implementing this function.
os_Type_loader::fixup()
void type_loader::fixup (
os_Type_data& given_data,
void* obj,
os_boolean is_most_derived_class
);
Adjusts pointers and C++ references in newly loaded objects.
Also sets members of the newly loaded object if the constructor called by create()
does not restore the entire state of the object being loaded.
is_most_derived_class indicates whether the object being loaded is a direct
instance of type. A value of 1 indicates that the object is a direct instance of type; a
value of 0 indicates that the object is a direct instance of a class derived from type.
See Implementing fixup() in the Advanced C++ A P I User Guide for information on
implementing this function.
os_Type_loader::get()
static Type_loader& type_loader::get ();
Returns an instance of type_loader.
See Implementing get() in the Advanced C++ A P I User Guide for information on
implementing this function.
434
C++ A P I Reference
Chapter 2: Class Library
os_Type_loader::load()
Loader_action* type_loader::load (
os_Loader_stream& stream,
os_Type_data& given_data,
os_boolean is_most_derived_class
);
Loads the value portion of an object form from the load stream and sets the data
members of given_data accordingly.
is_most_derived_class indicates whether the object being loaded is a direct
instance of type. A value of 1 indicates that the object is a direct instance of type; a
value of 0 indicates that the object is a direct instance of a class derived from type.
Returns 0 for success.
See Implementing load() in the Advanced C++ A P I User Guide for information on
implementing this function.
os_Type_loader::operator ()()
os_Loader_action* type_loader::operator () (
os_Loader_stream& stream,
os_Loader_info& previous_info
);
Loads an object form and creates and performs root-object fixup on the
corresponding object.
Returns 0 for success.
See Implementing operator ()() in the Advanced C++ A P I User Guide for information
on implementing this function.
Release 6.3
435
os_type_template
os_type_template
class os_type_template : public os_template
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent parameterized types.
os_type_template is derived from os_template.
os_type_template::create()
static os_type_template& create(
os_type*,
os_List<os_template_formal_arg*>&
);
Creates a template that is a parameterization of the specified type with the specified
parameters.
os_type_template::get_type()
const os_type& get_type( ) const;
Returns the type being parameterized.
os_type_template::set_type()
void set_type(os_type&);
Specifies the type being parameterized.
436
C++ A P I Reference
Chapter 2: Class Library
os_type_template_actual_arg
class os_type_template_actual_arg : public os_template_actual_arg
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. Instances of this class represent types that are actual
parameters of class templates.
os_type_template_actual_arg::create()
static os_type_template_actual_arg& create(os_type*);
Creates an actual parameter consisting of the specified type.
os_type_template_actual_arg::get_type()
const os_type& get_type( ) const;
Returns a reference to a const type, the type of which the actual parameter consists.
Overloadings
The following is the non-const overloading of this function:
os_type& get_type( );
Returns a reference to a non-const type, the type of which the actual argument
consists.
os_type_template_actual_arg::set_type()
void set_type(os_type&);
Sets the type of which the actual argument consists.
Release 6.3
437
os_type_type
os_type_type
class os_type_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents a type serving as
a parameter to a class or function template. This class is derived from os_type. The
member functions os_type::get_size( ) and os_type::get_alignment( ) signal
err_mop when invoked on an os_type_type.
438
C++ A P I Reference
Chapter 2: Class Library
os_typed_pointer_void
Instances of this class encapsulate a void* pointer and an object representing the
type of object pointed to. Instances of os_typed_pointer_void are returned by os_
schema_evolution::get_evolved_address( ), os_schema_evolution::get_
unevolved_address( ), os_schema_evolution::get_evolved_object( ), and os_
schema_evolution::get_unevolved_object( ).
os_typed_pointer_void::get_type()
const os_type& get_type( ) const;
Returns a reference to an os_type representing the class of the object pointed to by
the specified os_typed_pointer_void.
os_typed_pointer_void::operator void*()
operator void*( ) const;
Returns the void* pointer encapsulated by the specified os_typed_pointer_void.
Release 6.3
439
os_typespec
os_typespec
Instances of this class are passed to persistent new by applications using the
ObjectStore C++ library interface. Typespecs must be transiently allocated; you
should not allocate a typespec in persistent memory.
If a user-defined class includes a member function declared exactly as follows,
static os_typespec* et_os_typespec( );
the ObjectStore schema generator automatically supplies a body for the function,
which returns a pointer to a typespec for the class. The os_typspec object referenced
by the pointer is statically allocated; that is, subsequent calls to the function in the
same process return a pointer to the same object and the object need not be deleted.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_typespec::get_char()
static os_typespec* get_char( );
Returns a pointer to a typespec for the type char. The first time such a function is
called by a particular process, it allocates the typespec and returns a pointer to it.
Subsequent calls to the function in the same process do not result in further
allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_double()
static os_typespec* get_double( );
Returns a pointer to a typespec for the type double. The first time such a function is
called by a particular process, it allocates the typespec and returns a pointer to it.
Subsequent calls to the function in the same process do not result in further
allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_float()
static os_typespec* get_float( );
Returns a pointer to a typespec for the type float. The first time such a function is
called by a particular process, it allocates the typespec and returns a pointer to it.
Subsequent calls to the function in the same process do not result in further
allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_int()
static os_typespec* get_int( );
Returns a pointer to a typespec for the type int. The first time such a function is
called by a particular process, it allocates the typespec and returns a pointer to it.
Subsequent calls to the function in the same process do not result in further
allocation; instead, a pointer to the same os_typespec object is returned.
440
C++ A P I Reference
Chapter 2: Class Library
os_typespec::get_long()
static os_typespec* get_long( );
Returns a pointer to a typespec for the type long. The first time such a function is
called by a particular process, it allocates the typespec and returns a pointer to it.
Subsequent calls to the function in the same process do not result in further
allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_long_double()
static os_typespec* get_long_double( );
Returns a pointer to a typespec for the type long_double. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_name()
char* get_name( );
Returns the name of the type designated by the specified typespec.
os_typespec::get_os_int16()
static os_typespec* get_os_int16( );
Returns a pointer to a typespec for the ObjectStore portable type os_int16. The first
time such a function is called by a particular process, it allocates the typespec and
returns a pointer to it. Subsequent calls to the function in the same process do not
result in further allocation; instead, a pointer to the same os_typespec object is
returned.
os_typespec::get_os_int32()
static os_typespec* get_os_int32( );
Returns a pointer to a typespec for the ObjectStore portable type os_int32. The first
time such a function is called by a particular process, it allocates the typespec and
returns a pointer to it. Subsequent calls to the function in the same process do not
result in further allocation; instead, a pointer to the same os_typespec object is
returned.
os_typespec::get_os_int64()
static os_typespec* get_os_int64( );
Returns a pointer to a typespec for the ObjectStore portable type os_int64. The first
time such a function is called by a particular process, it allocates the typespec and
returns a pointer to it. Subsequent calls to the function in the same process do not
result in further allocation; instead, a pointer to the same os_typespec object is
returned.
Release 6.3
441
os_typespec
os_typespec::get_os_signed_int8()
static os_typespec* get_os_signed_int8( );
Returns a pointer to a typespec for the ObjectStore portable type os_signed_int8.
The first time such a function is called by a particular process, it allocates the
typespec and returns a pointer to it. Subsequent calls to the function in the same
process do not result in further allocation; instead, a pointer to the same os_
typespec object is returned.
os_typespec::get_os_unsigned_int8()
static os_typespec* get_os_unsigned_int8( );
Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_int8.
The first time such a function is called by a particular process, it allocates the
typespec and returns a pointer to it. Subsequent calls to the function in the same
process do not result in further allocation; instead, a pointer to the same os_
typespec object is returned.
os_typespec::get_os_unsigned_int16()
static os_typespec* get_os_unsigned_int16( );
Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_
int16. The first time such a function is called by a particular process, it allocates the
typespec and returns a pointer to it. Subsequent calls to the function in the same
process do not result in further allocation; instead, a pointer to the same os_
typespec object is returned.
os_typespec::get_os_unsigned_int32()
static os_typespec* get_os_unsigned_int32( );
Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_
int32. The first time such a function is called by a particular process, it allocates the
typespec and returns a pointer to it. Subsequent calls to the function in the same
process do not result in further allocation; instead, a pointer to the same os_
typespec object is returned.
os_typespec::get_os_unsigned_int64()
static os_typespec* get_os_unsigned_int64( );
Returns a pointer to a typespec for the ObjectStore portable type os_unsigned_
int64. The first time such a function is called by a particular process, it allocates the
typespec and returns a pointer to it. Subsequent calls to the function in the same
process do not result in further allocation; instead, a pointer to the same os_
typespec object is returned.
442
C++ A P I Reference
Chapter 2: Class Library
os_typespec::get_pointer()
static os_typespec* get_pointer( );
Returns a pointer to a typespec for the type void*. The first time such a function is
called by a particular process, it allocates the typespec and returns a pointer to it.
Subsequent calls to the function in the same process do not result in further
allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_short()
static os_typespec* get_short( );
Returns a pointer to a typespec for the type short. The first time such a function is
called by a particular process, it allocates the typespec and returns a pointer to it.
Subsequent calls to the function in the same process do not result in further
allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_signed_char()
static os_typespec* get_signed_char( );
Returns a pointer to a typespec for the type signed_char. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_signed_int()
static os_typespec* get_signed_int( );
Returns a pointer to a typespec for the type signed_int. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_signed_long()
static os_typespec* get_signed_long( );
Returns a pointer to a typespec for the type signed_long. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_signed_short()
static os_typespec* get_signed_short( );
Returns a pointer to a typespec for the type signed_short. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
Release 6.3
443
os_typespec
os_typespec::get_unsigned_char()
static os_typespec* get_unsigned_char( );
Returns a pointer to a typespec for the type unsigned_char. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_unsigned_int()
static os_typespec* get_unsigned_int( );
Returns a pointer to a typespec for the type unsigned_int. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_unsigned_long()
static os_typespec* get_unsigned_long( );
Returns a pointer to a typespec for the type unsigned_long. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::get_unsigned_short()
static os_typespec* get_unsigned_short( );
Returns a pointer to a typespec for the type unsigned_short. The first time such a
function is called by a particular process, it allocates the typespec and returns a
pointer to it. Subsequent calls to the function in the same process do not result in
further allocation; instead, a pointer to the same os_typespec object is returned.
os_typespec::operator ==()
os_boolean operator ==(const os_typespec&) const;
Returns nonzero (true) if the two typespecs designate the same type; returns 0 (false)
otherwise.
os_typespec::os_typespec()
os_typespec(char* type_name);
Constructs an os_typespec object that represents the type with the specified name.
444
C++ A P I Reference
Chapter 2: Class Library
Restrictions
type_name must be a name for one of the following:
• A fundamental type, such as int or char.
• A class.
• A pointer-to-class or pointer-to-fundamental type. For example, foo** is not
allowed; use void* instead.
Names that have been defined with typedef are not allowed. type_name must not
contain embedded spaces; for example, specify "void*", not "void *". Typespecs
must be allocated transiently, not in persistent memory.
If you use const or volatile in specifying the type, always put the const or
volatile specifier after the type it modifies. For example, use
char const*
rather than
const char*
Instead of using the os_typespec constructor to generate a typespec, it generally is
preferable to use one of the static members of os_typespec (for example, os_
typespec::get_char()) to generate a typespec for a fundamental type and get_
os_typespec() to generate typespecs for classes. These typespecs are statically
allocated and do not require explicit deletion. The object created by the os_
typespec constructor, on the other hand, is allocated off the heap and must be
explicitly deleted.
For information about using typespecs, see Using Typespecs in Chapter 3 of the C++
A P I User Guide.
Release 6.3
445
os_unsigned_int64
os_unsigned_int64
Instances of the class os_unsigned_int64 represent unsigned 64-bit integers on any
platform; the underlying implementation will vary from platform to platform.
Members of this class provide all of the standard C++ operators for manipulating
integers. For information about signed 64-bit integers, see os_int64 on page 231.
Type definitions
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.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
os_unsigned_int64::os_unsigned_int64()
os_unsigned_int64(os_unsigned_uint64 num);
Constructs a copy of num.
Overloadings
The following overloadings are supported:
os_unsigned_int64(os_platform_uint64 num);
Constructs an instance of os_unsigned_int64 based on the value of num. The os_
platform_int64 argument is an ObjectStore type definition for native 64-bit integer
data types, if there is one.
os_unsigned_int64(os_unsigned_int32 num);
Constructs an instance of os_unsigned_int64 based on the value of num, a 32-bit
integer.
os_unsigned_int64(
os_unsigned_int32 high,
os_unsigned_int32 low
);
Constructs an instance of os_unsigned_int64 based on the values of high and low,
where high represents the upper 32 bits and low represents the lower 32 bits.
os_unsigned_int64::get_high()
os_unsigned_int32 get_low( );
Returns an unsigned 32-bit integer based on the upper 32 bits of the value of the
object.
os_unsigned_int64::get_low()
os_unsigned_int32 get_low( );
Returns an unsigned 32-bit integer based on the lower 32 bits of the value of the
object.
446
C++ A P I Reference
Chapter 2: Class Library
os_unsigned_int64::sprint()
void sprint(char* result, os_int32 = 10) const;
Converts the value of the object into a formatted string at the specified base and
writes the string to result. The base argument can be either 10 or 16; the default is
10.
Release 6.3
447
os_untranslatable_pointer_handler
os_untranslatable_pointer_handler
This is a base class for handling a pointer to an evolved object, or to a data member
within an evolved object, when the pointer cannot be translated to the corresponding
location after evolution. You can define your own classes derived from this one and
define methods for the handle_xxx() virtual functions. This class supplies default
methods that signal an error via the _default_handler() method.
os_untranslatable_pointer_handler::clone()
virtual os_untranslatable_pointer_handler* clone();
You must override this function to make a copy of this that is an instance of your
derived class. Your method should call the copy constructor.
os_untranslatable_pointer_handler::get_exception()
objectstore_exception& get_exception();
Returns an exception object describing what is wrong with the offending pointer.
os_untranslatable_pointer_handler::get_explanation()
const char* get_explanation();
Returns an internationalized error message describing what is wrong with the
offending pointer.
os_untranslatable_pointer_handler::get_source_cluster()
os_cluster* get_source_cluster();
Returns the cluster containing the offending pointer.
os_untranslatable_pointer_handler::get_source_offset()
os_unsigned_int32 get_source_offset();
Returns the offset of the offending pointer in that cluster.
os_untranslatable_pointer_handler::get_source_path()
const os_path_to_data& get_source_path();
Returns the os_path_to_data of the offending pointer. This is the path to the data
member that is the untranslatable pointer. See os_path_to_data on page 271 for
more information about the os_path_to_data class.
os_untranslatable_pointer_handler::get_target_cluster()
os_cluster* get_target_cluster();
Returns the os_cluster containing the target of the pointer. Not valid if get_
target_exported() is true.
448
C++ A P I Reference
Chapter 2: Class Library
os_untranslatable_pointer_handler::get_target_exported()
os_boolean get_target_exported();
Returns true if the target is identified by segment and export ID; returns false if the
target is identified by segment and cluster.
os_untranslatable_pointer_handler::get_target_export_id()
os_export_id get_target_export_id();
Returns the export ID of the target of the pointer. Valid only if get_target_
exported() is true.
os_untranslatable_pointer_handler::get_final_offset()
os_unsigned_int32 get_final_offset();
Returns the offset of pointer target within the primitive type object that is the end of
the target_path. Normally this is zero. If relocating an ObjectStore Java Interface
pointer this is 1 or 3. This offset could be large when the end of the target_path is
an array of primitive types such as a char string.
os_untranslatable_pointer_handler::get_target_offset()
os_unsigned_int32 get_target_offset();
Returns the offset in the target cluster if the target of the pointer is not an exported
object or the offset in the top-level exported object pointed to by the pointer.
os_untranslatable_pointer_handler::get_target_path()
const os_path_to_data& get_target_path();
Returns the type of top-level object and path to the pointer target before schema
evolution. If the pointer is not a void* pointer, its target type is get_target_
path(.type().
os_untranslatable_pointer_handler::get_target_segment()
os_segment* get_target_segment();
Returns the os_segment containing the target of the pointer.
Release 6.3
449
os_untranslatable_pointer_handler
os_untranslatable_pointer_handler::handle_xxx()
The default way of handling untranslatable pointers is to signal an exception. You
can override the following handle_xxx() virtual functions, where xxx is a specific
kind of untranslatable pointer. You can set the pointer to NULL or set it to a new
path.
virtual
virtual
virtual
virtual
virtual
virtual
virtual
os_path_to_data*
os_path_to_data*
os_path_to_data*
os_path_to_data*
os_path_to_data*
os_path_to_data*
os_path_to_data*
handle_ambiguous_void_pointer();
handle_deleted_sub_object();
handle_evolved_to_bit_field();
handle_evolved_to_incompatible_type();
handle_evolved_to_smaller();
handle_evolved_to_static();
handle_wrong_type_pointer();
The return value from the handle_xxx() virtual functions is NULL to set the
offending pointer to NULL, or a new value for target_path to set the offending
pointer according to that path and final_offset. The method is permitted to
modify final_offset. The new target must lie within the same top-level object and
must have the correct type.
The returned os_path_to_data will be deleted by ObjectStore. If a non-NULL value
is returned and the new target is not valid, an error will be signalled without calling
the pointer handler again.
The handle_xxx() virtual functions are not allowed to touch persistent storage.
Note that there can be simultaneous calls to these virtual functions in multiple
threads. Each thread will have its own instance of os_untranslatable_pointer_
handler or the user's derived class.
os_untranslatable_pointer_handler::is_PTOM()
os_boolean os_untranslatable_pointer_handler::is_PTOM();
Returns true if the untranslatable pointer is a pointer-to-member type. Returns false
if the untranslatable pointer is not a pointer-to-member type. This function can be
useful during schema evolution. See Evolving Schemas That Contain Pointer-toMember Types.
os_untranslatable_pointer_handler::set_final_offset()
void set_final_offset(os_unsigned_int32 x);
Sets the offset of pointer target within the primitive type object that is the end of the
target_path. Normally this is zero. If relocating an ObjectStore Java Interface
pointer this is 1 or 3. This offset could be large when the end of the target_path is
an array of primitive types such as a char string.
450
C++ A P I Reference
Chapter 2: Class Library
os_void_type
class os_void_type : public os_type
This class is part of the ObjectStore metaobject protocol (MOP), which provides
access to ObjectStore schemas. An instance of this class represents the type void. The
os_void_type class is derived from os_type. Note, however, that the member
functions os_type::get_size( ) and os_type::get_alignment( ) signal err_mop
if they are invoked on an os_void_type object.
Required
header files
Programs using this class must include <ostore/ostore.hh>, followed by
<ostore/coll.hh> (if used), followed by <ostore/mop.hh>.
os_void_type::create()
static os_void_type& create( );
Creates an object representing the type void.
Release 6.3
451
os_with_mapped
os_with_mapped
Instances of os_with_mapped can be used to force data to stay in the client cache
during system calls that cannot handle page faults. For more information, see
Chapter 3 in the C++ A P I User Guide.
os_with_mapped::os_with_mapped()
os_with_mapped (
void* location,
os_unsigned_int32 size,
os_boolean for_write = 0
);
Creates an os_with_mapped object that ensures that the persistent range indicated in
the location and size arguments is accessible to system calls and library functions,
by forcing the range to stay in the cache and accessible in memory.
location specifies the starting address of the range. size specifies the size of the
range in bytes. for_write is a Boolean value that indicates whether you intend to
update the object.
Note that an os_with_mapped object cannot be used across transaction boundaries,
including nested transactions.
os_with_mapped::~os_with_mapped()
~os_with_mapped();
Restores normal cache behavior with respect to the range of data specified at the time
the os_with_mapped object was created.
452
C++ A P I Reference
Chapter 2: Class Library
tix_context
The class tix_context makes error messages more informative by providing
contextual information.
In the following example, if you get the error Connection attempt timed out, you
are also told that the error occurred while you were trying to create that database.
{
tix_context tc1("While creating database %s\n", the_pathname);
. . .
server->create_database(the_pathname);
. . .
}
If any TIX exception is signaled during the execution of server->create_database,
and the exception is not handled inside the server->create_database, the error
message associated with the error is extended to append the string "While
creating database /a/b/c" to the end.
tix_context works as follows: When an exception is signaled, as the signaler moves
up the stack searching for a handler, if it encounters a tix_context, it runs sprintf
on the arguments and adds this string to the end of the error message. If it does
finally find a handler, the string returned by the report function member (and
report0) includes the context messages of all tix_context objects that were on the
stack between the point at which the exception was signaled and the point at which
it was handled. If no handler is found, the message that is issued includes the context
messages of all tix_context objects that were on the stack.
The tix_context constructor has one required argument (a printf()-style control
string) and up to four additional arguments, which must all be strings. The control
string should have as many occurrences of %s as there are arguments. You can use
only strings and %s, and no more than four.
C++ requires that you include a variable name for the tix_context object, such as
tc1 in the preceding example.
Note that the sprintf is done only if the exception is actually signaled; establishing
a tix_context that is never used incurs little overhead.
The tix_context constructor does not copy any of the strings it is given, so if there
is any chance that those strings might get altered during execution of the scope of the
tix_context, you should probably make copies. It is a good idea to delete them
manually when you are finished with them.
The current limit on the length of the report string is 4096 characters.
Release 6.3
453
tix_exception
tix_exception
Every predefined TIX exception is an instance of tix_exception and represents a
particular type of error condition or exceptional circumstance. Every exception has
a parent, except the exception err_objectstore (see Chapter 5, Predefined TIX
Exceptions, on page 499). The parent of a given exception is an ancestor of that
exception. The parent of any ancestor of a given exception is also an ancestor of that
exception. If one exception is an ancestor of another, the other exception is said to be
a descendant of the first.
tix_exception::ancestor_of()
os_int32 ancestor_of(tix_exception const* e);
Returns nonzero if this is an ancestor of e, and 0 otherwise. Any parent of e is an
ancestor of e, and any parent of an ancestor of e is also an ancestor of e. In addition,
every exception is considered to be its own ancestor; therefore, if this is the same as
e, the function returns nonzero.
tix_exception::get_os_deadlock_exception()
os_deadlock_exception* get_os_deadlock_exception() const;
If this is an os_deadlock_exception, returns this cast to a pointer of that type;
otherwise returns NULL.
tix_exception::get_os_lock_timeout_exception()
os_lock_timeout_exception* get_os_lock_timeout_exception() const;
If this is an os_lock_timeout_exception, returns this cast to a pointer of that
type; otherwise returns NULL.
tix_exception::release_pointer()
void release_pointer();
If this is a dynamically allocated exception, delete it; otherwise do nothing.
An exception handler that might handle err_deadlock or err_lock_timeout
should free the exception object in order to avoid memory leaks as follows:
tix_handler::get_exception()->release_pointer();
This is safe for all exception handlers but is unnecessary if the exception is known
not to be err_deadlock or err_lock_timeout.
454
C++ A P I Reference
Chapter 2: Class Library
tix_exception::set_unhandled_exception_hook()
static tix_unhandled_exception_hook_t
set_unhandled_exception_hook(
tix_unhandled_exception_hook_t new_hook
);
Registers a function that is called if a TIX exception is unhandled.
Caution
Release 6.3
It is not safe to access persistent memory or use the ObjectStore API while your
function is in use during an unhandled TIX exception, especially during an err_
deadlock exception.
455
tix_handler
tix_handler
A tix_handler carries information about the particular exceptional circumstances
leading to the signaling of the current exception.
tix_handler::get_current()
static tix_handler* get_current();
Returns the tix_handler for the current exception.
tix_handler::get_exception()
static tix_exception* get_exception();
Returns the current TIX exception.
tix_handler::get_report()
static char* get_report();
Returns the format string used to signal the current exception. The string includes
the text of the error message and is suitable for further processing, writing to a file,
or displaying on the screen. Compare tix_handler_get_report0().
tix_handler::get_report0()
static char* get_report0();
Returns the format string used to signal the current exception without the error
message associated with the exception. Compare tix_handler_get_report().
tix_handler::get_value()
static os_int32 get_value();
Returns the error code associated with the current user-defined exception by means
of the objectstore_exception::signal() or objectstore_
exception::vsignal() function. For more information, see objectstore_
exception::signal() on page 96.
456
C++ A P I Reference
Chapter 3
System-Supplied Global
Functions
Some system-supplied interface functions are not members of any class but are
global C++ functions.
Global C++ Functions
These functions are the following, and appear alphabetically in the discussions that
follow.
::operator delete()
458
::operator new()
459
::os_fetch()
461
::os_fetch_address()
464
::os_store()
465
The system-supplied global functions are listed alphabetically in this chapter.
Release 6.3
457
::operator delete()
::operator delete()
Persistent storage can be reclaimed using ::operator delete operator, just as it
would be used for transient objects. ObjectStore determines whether the storage is
persistent or transient.
When a persistent object is deleted using ::operator delete(), the database in
which it is to be stored must be opened by the process performing the deletion, and
this process must have a transaction in progress.
Note
Applications can register their own transient delete; see objectstore::set_
transient_delete_function() on page 93. If you want to override ObjectStore’s
global ::operator delete(), you must define it to delete both transient and
persistent memory. To delete persistent memory, the definition of ::operator
delete() must include a call to objectstore::free_memory(); see
objectstore::free_memory() on page 61.
Required
header file
All ObjectStore programs must include the header file <ostore/ostore.hh>.
void ::operator delete()
Deletes the specified object from storage. The argument must point to the beginning
of an object’s storage. If it points to the middle of an object, the exception err_
invalid_deletion is signaled. This might happen, for example, if the argument
points to the fifth element of a persistent array, or if the argument has been cast from
a D* to a B*, where class D is derived directly from class B and another class.
458
C++ A P I Reference
Chapter 3: System-Supplied Global Functions
::operator new()
ObjectStore provides overloadings of ::operator new() for allocating persistent or
transient storage, using the following syntax:
void* ::operator new(obj_size, clustering_info, typespec, elements)
obj_size is the size of the new object. This argument is optional and, if not
specified, is supplied by the system.
clustering_info specifies clustering information, that is, the database, segment, or
cluster in which to allocate storage for the new object. Specifying a transient
database, segment, or cluster results in transient allocation.
typespec specifies the type of the new object. This argument is an instance of the
class os_typed_pointer_void; see os_typed_pointer_void on page 439.
If new is used to create an array, elements specifies the number of elements.
Overloadings
Each overloading returns a pointer to newly allocated memory. Persistent memory
is initialized to null by ObjectStore.
void *::operator new(size_t, os_database*,
os_typespec*[, os_int32])
If this form is used, a newly created object of the type specified by the os_typespec
is stored in the specified database. If the transient database is specified, the new
object is transiently allocated. If you specify the transient database, you can supply
0 for the os_typespec* argument. If you are allocating for an array objects, use the
argument os_int32 (a signed 32-bit integer type) to specify the number of elements.
For more information about retrieving transient databases, see os_database::get_
transient_database() on page 161.
void *::operator new(
size_t, os_segment*, os_typespec*[, os_int32])
If this form is used, a newly created object of the type specified by the os_typespec
is stored in the specified segment unless that segment is the schema segment, in
which case err_misc is signaled. If the transient segment is specified, the new object
is transiently allocated. If you specify the transient segment, you can supply 0 for the
os_typespec* argument. If you are allocating for an array of objects, use the
argument os_int32 (a signed 32-bit integer type) to specify the number of elements.
For more information about retrieving transient segments, see os_segment::get_
transient_segment() on page 357.
void *::operator new(size_t, os_cluster*,
os_typespec*[, os_int32])
If this form is used, a newly created object of the type specified by the os_typespec
is stored in the specified cluster unless the new object does not fit in the cluster, in
which case err_cluster_full is signaled. If this argument is the address of
transient memory, the new object is transiently allocated. If you are allocating
transient storage, you can supply 0 for the os_typespec* argument. If you are
Release 6.3
459
::operator new()
allocating an array, use the argument os_int32 (a signed 32-bit integer type) to
specify the number of elements.
void *::operator new(size_t, os_cluster::with(),
os_typespec* [, os_int32])
If this form is used, a newly created object of the type specified by the os_typespec
is stored as close as possible to the object specified as the argument to os_
cluster::with(); see os_cluster::with() on page 137. If the transient cluster is
specified, the new object is transiently allocated. If you specify the transient cluster,
you can supply 0 for the os_typespec* argument. If you are allocating for an array
of objects, use the argument os_int32 (a signed 32-bit integer type) to specify the
number of elements.
For more information about retrieving transient clusters, see os_cluster::get_
transient_cluster() on page 133.
os_cluster::with() returns an automatic variable of the class os_cluster_with.
This object contains a pointer to the object near which you want to allocate.
Following is an example of the way to use this method in operator new(), which
allocates storage for obj2 as close as possible to obj1:
a_class* obj2 = new(os_cluster::with(obj1),
a_typespec) a_class;
Note that for optimum clustering, use the os_cluster::with() overloading of
::operator new(). This overloading has the added advantage that os_
cluster::with() returns an automatic variable that does not require the user to
delete it explicitly. For more information, see the C++ A P I User Guide.
460
C++ A P I Reference
Chapter 3: System-Supplied Global Functions
::os_fetch()
The following functions retrieve the value of a specified data member for a specified
object.
void* os_fetch(
const void* obj,
const os_member_variable& mem,
void*& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
unsigned long os_fetch(
const void* obj,
const os_member_variable& mem,
unsigned long& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
long os_fetch(
const void* obj,
const os_member_variable& mem,
long& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
unsigned int os_fetch(
const void* obj,
const os_member_variable& mem,
unsigned int& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
int os_fetch(
const void* obj,
const os_member_variable& mem,
int& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
unsigned short os_fetch(
const void* obj,
const os_member_variable& mem,
unsigned short& val
Release 6.3
461
::os_fetch()
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
short os_fetch(
const void* obj,
const os_member_variable& mem,
short& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
unsigned char os_fetch(
const void* obj,
const os_member_variable& mem,
unsigned char& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
char os_fetch(
const void* obj,
const os_member_variable& mem,
char& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
float os_fetch(
const void* obj,
const os_member_variable& mem,
float& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
double os_fetch(
const void* obj,
const os_member_variable& mem,
double& val
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
long double os_fetch(
const void* obj,
const os_member_variable& mem,
long double& val
462
C++ A P I Reference
Chapter 3: System-Supplied Global Functions
);
Retrieves the value of the member represented by mem for the object obj by setting
val to a reference to the value. err_mop is signaled if the value type of the specified
member is not compatible with val.
Release 6.3
463
::os_fetch_address()
::os_fetch_address()
The following functions retrieve the address of a specified data member for a given
object or the address of the subobject corresponding to a specified base class for a
given object.
void* os_fetch_address(
void* obj,
const os_member_variable& mem
);
Retrieves the address of the data member mem for the object pointed to by obj. err_
mop is signaled if mem is an os_field_member_variable.
void* os_fetch_address(
void* obj,
const os_base_class& b
);
Retrieves the address of the subobject corresponding to base class b for the object
pointed to by obj.
464
C++ A P I Reference
Chapter 3: System-Supplied Global Functions
::os_store()
The following functions store the value of a specified data member for a specified
object.
void os_store(
void* obj,
const os_member_variable& mem,
const void* val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const unsigned long val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const long val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const unsigned int val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const int val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const unsigned short val
Release 6.3
465
::os_store()
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const short val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const unsigned char val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const char val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const float val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const double val
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
void os_store(
void* obj,
const os_member_variable& mem,
const long double val
466
C++ A P I Reference
Chapter 3: System-Supplied Global Functions
);
Establishes val as the value of the member represented by mem for the object obj.
err_mop is signaled if the value type of the specified member is not compatible with
val.
Release 6.3
467
::os_store()
468
C++ A P I Reference
Chapter 4
System-Supplied Macros
This chapter provides reference information for all ObjectStore macros except those
included with the collections facility. For information about those macros, see the
C++ Collections Guide and Reference.
ObjectStore Macros
The descriptions are listed alphabetically by macro name. However, the macros can
be grouped logically, as follows:
• Transaction processing:
- OS_BEGIN_TXN() on page 474
- OS_BEGIN_TXN_NAMED() on page 478
- OS_END_TXN() on page 480
• Fault handling:
- OS_ESTABLISH_FAULT_HANDLER on page 481
- OS_END_FAULT_HANDLER on page 479
• TIX exception handling:
- TIX_HANDLE() on page 494
- TIX_EXCEPTION on page 493
- TIX_END_HANDLE on page 492
- TIX_HANDLE_IF() on page 497
- DEFINE_EXCEPTION() on page 472
- DECLARE_EXCEPTION() on page 471
• Schema source file macros:
- OS_MARK_SCHEMA_TYPE() on page 482
- OS_MARK_SCHEMA_TYPESPEC() on page 483
- OS_REPORT_DLL_LOAD_AND_UNLOAD() on page 486
- OS_SCHEMA_DLL_ID() on page 487
- OS_SCHEMA_INFO_NAME() on page 488
Release 6.3
469
ObjectStore Macros
• Soft pointer use:
- os_soft_pointer on page 489
- OS_SOFT_POINTER32_NOCLASS() on page 490
- OS_SOFT_POINTER64_NOCLASS() on page 491
• Reference use:
- OS_REFERENCE_NOCLASS() on page 484
- OS_REFERENCE_PROTECTED_NOCLASS() on page 485
470
C++ A P I Reference
Chapter 4: System-Supplied Macros
DECLARE_EXCEPTION()
Declares a TIX exception defined elsewhere with DEFINE_EXCEPTION().
Syntax
DECLARE_EXCEPTION(name );
Arguments
name
The name of a user-defined TIX exception you want to declare. It must be defined
in the same application, using the DEFINE_EXCEPTION() macro. A user-defined
TIX exception is a variable of the class objectstore_exception and is part of the
TIX exception-handling facility.
Description
Use this macro to declare a user-defined TIX exception that you have defined
elsewhere in your application with the DEFINE_EXCEPTION() macro.
The DECLARE_EXCEPTION() macro must end with a semicolon (;).
The DECLARE_EXCEPTION() macro makes a TIX variable available to files other than
the one in which it is defined. For example, by specifying the DECLARE_EXCEPTION()
macro in a header file, you make the declared variable accessible to any file that
includes the header file.
The following example uses the DECLARE_EXCEPTION() macro to declare the
variable bad_char_input that is defined elsewhere in the program with the DEFINE_
EXCEPTION() macro:
DECLARE_EXCEPTION(bad_char_input)
For information about
• The DEFINE_EXCEPTION() macro, see DEFINE_EXCEPTION() on page 472
• TIX exception handlers, see TIX_HANDLE() on page 494
• Using the DECLARE_EXCEPTION() macro, see User-Defined Exceptions in Chapter
6 of the C++ A P I User Guide
Release 6.3
471
DEFINE_EXCEPTION()
DEFINE_EXCEPTION()
Specifies a user-defined TIX exception.
Syntax
DEFINE_EXCEPTION(name, "message", pointer-to-parent );
Arguments
name
The identifier for the exception you want to create.
message
The error message to display when the exception is signaled. As shown in the
syntax statement, this argument must be enclosed in quotation marks.
pointer-to-parent
The address of a parent exception, which thus becomes the new exception’s
parent. For information about parent exceptions, see Parent Exceptions on
page 500. Supply 0 for this argument if you do not want your exception to have a
parent.
Description
Use this macro to define your own TIX exception. A user-defined TIX exception is a
variable of the class objectstore_exception and is part of the TIX exceptionhandling facility.
The DEFINE_EXCEPTION() macro must end in a semicolon (;).
The following example program shows how to use the DEFINE_EXCEPTION() macro.
The program defines three exceptions: err_too_few_args, err_too_many_args,
and err_bad_arg. These are used to perform error-checking on command-line
arguments. The first one, err_too_few_args, is handled by a TIX exception handler;
the other two are not handled. All three exceptions are signaled by calls to the
method signal(); see objectstore_exception::signal() on page 96.
// def_exc.cc: Illustrates how to use the DEFINE_EXCEPTION
// macro to define your own TIX exceptions. This program defines
// TIX exceptions to handle command-line argument errors. The
// program signals err_too_few_args if there are no arguments
// present, err_too_many_args if there are more than one,
// and err_bad_arg if the word "bad" is used as an argument.
// Only err_too_few_args is handled.
#include <ostore/ostore.hh>
#include <string.h>
#include <fstream.h>
DEFINE_EXCEPTION(err_too_few_args, "Too few arguments", 0);
DEFINE_EXCEPTION(err_too_many_args, "Too many arguments", 0);
DEFINE_EXCEPTION(err_bad_arg, "Illegal argument: ", 0);
void validate_args(int argc, char **argv);
main(int argc, char **argv)
{
OS_ESTABLISH_FAULT_HANDLER {
objectstore::initialize();
TIX_HANDLE (err_too_few_args) {
validate_args(argc, argv);
} TIX_EXCEPTION {
472
C++ A P I Reference
Chapter 4: System-Supplied Macros
tix_exception *exception = tix_handler::get_exception();
if (exception == &err_too_few_args)
cout << "Missing command-line arguments.\n";
else
cout << "Unknown exception occurred.\n";
} TIX_END_HANDLE
} OS_END_FAULT_HANDLER
}
void validate_args(int argc, char **argv)
{
if (argc == 1) // no arguments
// No message is specified because the default message
// specified in the DEFINE_EXCEPTION macro is sufficient.
err_too_few_args.signal("");
else if (argc > 2) // more than one argument
// No message is specified, so only the default message
// specified with the DEFINE_EXCEPTION macro will
// be displayed.
err_too_many_args.signal("");
else if (argc == 2 && !strcmp(argv[1], "bad"))
// This call to signal includes a message,
// which will therefore be displayed along with the
// default message specified with the DEFINE_EXCEPTION
// macro.
err_bad_arg.signal(argv[1]);
}
Following is the output from a sample run:
$ def_exc
Missing command-line arguments.
$ def_exc arg
$ def_exc arg arg
Too many arguments
(err_too_many_args)
$ def_exc bad
Illegal argument:
bad (err_bad_arg)
This example program is available online in
• $OS_ROOTDIR/examples/doc_demos/ref4/def_exc.cc (UNIX)
• %OS_ROOTDIR%\examples\doc_demos\ref4\def_exc.cpp (Windows)
For information about
• signal(), see objectstore_exception::signal() on page 96
• TIX exception handlers, see TIX_HANDLE() on page 494
• Using the DEFINE_EXCEPTION() macro, see User-Defined Exceptions in Chapter
6 of the C++ A P I User Guide
Release 6.3
473
OS_BEGIN_TXN()
OS_BEGIN_TXN()
OS_BEGIN_TXN (or OS_BEGIN_TXN_NAMED) begins a lexical transaction and establishes
a new scope.
Syntax
The syntaxes are as follows. There must be no spaces anywhere in the argument lists
to OS_BEGIN_TXN() and OS_BEGIN_TXN_NAMED(). Also, the enclosing braces are not
required, but some source code editors complain if you do not use them.
OS_BEGIN_TXN(txn-tag,expression,txn-type ) {
. . .
} OS_END_TXN(txn-tag )
OS_BEGIN_TXN_NAMED(txn-tag,expression,txn-type,txn-name ) {
. . .
} OS_END_TXN(txn-tag )
Arguments
txn-tag
An identifier — a tag for the transaction that is not used for any other transaction
in the same function. (The tags are used to construct statement labels and must
therefore have the same scope as labels in C++.) The tag specified in a
transaction’s OS_BEGIN_TXN() and OS_END_TXN() macros must be the same.
expression
This argument is of type tix_exception** and specifies a location in which
ObjectStore stores the transaction’s completion status. If the tix_exception**
points to 0 when the transaction completes, the transaction committed; that is, its
changes were made permanent and visible.
If the tix_exception** points to a nonzero value, the transaction aborted; that is,
any changes to persistent state within the transaction were undone. The identity
of the exception gives the reason for the abort.
In the event of an abort that causes the transaction to abort, you can examine
expression only if one of the following is true:
- You enclosed the entire transaction in a TIX exception handler; see TIX_
HANDLE() on page 494.
- The exception was caused by an explicit abort — that is, by a call to os_
transaction::abort() or os_transaction::abort_top_level().
For information causing an explicit abort, see os_transaction::abort() on
page 409 or os_transaction::abort_top_level() on page 409.
The referenced exception in expression can be one of the predefined exceptions
listed in Chapter 5, Predefined TIX Exceptions, on page 499, or a user-defined
exception. See DEFINE_EXCEPTION() on page 472 for information about userdefined exceptions.
txn-type
This is one of the following enumerators:
474
C++ A P I Reference
Chapter 4: System-Supplied Macros
- os_transaction::read_only, which indicates that the transaction performs
no updates to persistent storage. If write access to persistent data is attempted,
a run-time error is signaled.
- os_transaction::update, which indicates that the transaction performs
updates to persistent storage.
For more information about these enumerators, see os_transaction::read_
only on page 413 and os_transaction::update on page 414.
txn-name
The name you want to give to the transaction. See os_transaction::get_
name() on page 411.
Description
OS_BEGIN_TXT begins a lexical transaction and establishes a new scope. OS_END_
TXN() ends and commits the transaction started by the previous matching OS_
BEGIN_TXN() call. OS_END_TXN() also marks the end of the scope established by OS_
BEGIN_TXN().
OS_BEGIN_TXN_NAMED() is identical in behavior to OS_BEGIN_TXN(), except that it
allows you to specify a transaction name. The name must be unique among
transactions in the same function. It is used in constructing statement labels.
ObjectStore also supports dynamic transactions, which use member functions of the
class os_transaction; see os_transaction on page 409.
Transactions can be nested. For example, you can nest an update transaction inside
a read-only transaction if you want to write temporarily to persistent memory, as in
the following:
OS_BEGIN_TXN(txn1, 0, os_transaction::read_only) {
OS_BEGIN_TXN(txn2, 0, os_transaction::update) {
// process database
os_transaction::abort(); // Roll back the transaction
} OS_END_TXN(txn2)
} OS_END_TXN(txn1)
The following example program illustrates how to use the OS_BEGIN_TXN() and OS_
END_TXN() macros to form a lexical transaction. By way of contrast, the program also
illustrates a dynamic transaction.
The program creates a database (stanza.db) and uses a lexical transaction to write
an array of strings to the database. After the lexical transaction commits, the program
starts a dynamic transaction and reads the strings from the database, displaying
them on standard output.
// txn_example.cc: illustrates lexical and dynamic transactions
// The program writes an array of strings to a database in a
// lexical transaction (using the macros), and reads the array
// in a dynamic transaction (using the os_transaction methods).
#include <ostore/ostore.hh>
#include <string.h>
#include <fstream.h>
#define SIZE 5
main( )
{
Release 6.3
475
OS_BEGIN_TXN()
os_database* db;
os_database_root* root;
os_transaction* txn;
char *verse[] = {
"Matter, as wise logicians say,",
" Cannot without a form subsist;",
"And form, say I as well as they,",
" Must fail if matter brings no grist.",
""
};
OS_ESTABLISH_FAULT_HANDLER {
objectstore::initialize();
// create the database "stanza.db"; if it already exists,
// overwrite it
db = os_database::create("stanza.db", 0644, 1);
// start a lexical transaction in update mode
OS_BEGIN_TXN(t1, 0, os_transaction::update) {
// allocate persistent storage for an array of pointers
// to chars
char **s = (char**)new(db,
os_typespec::get_pointer(), SIZE) void**[SIZE];
// create a root ...
root = db->create_root("root");
// ... and associate it with the first element of the
// array, making it the entry point
root->set_value(s, os_typespec::get_pointer());
for (int i = 0; i < SIZE; i++) {
int len = strlen(verse[i])+1;
// allocate persistent storage for the string,
// clustering it with the previously allocated array
s[i] = new(os_cluster::with(s),
os_typespec::get_char(), len) char[len];
// copy the string in verse[i] to the allocated storage
strcpy(s[i], verse[i]);
}
} OS_END_TXN(t1)
db->close(); // close database
db->open(0); // re-open database for read-only
// start a dynamic transaction in read-only mode
txn = os_transaction::begin(os_transaction::read_only);
root = db->find_root("root"); // find the database root
// get the entry-point (the first element of an array of
// pointers to chars) associated with the root
char** s =
(char**)(root->get_value(os_typespec::get_pointer()));
// print the strings
for (; **s; s++)
cout << *s << endl;
txn->commit(); // commit transaction
db->close(); // close database
// clean up
delete db;
delete root;
delete txn;
} OS_END_FAULT_HANDLER
return 0;
}
476
C++ A P I Reference
Chapter 4: System-Supplied Macros
Following is the output from a sample run:
$ txn_example
Matter, as wise logicians say,
Cannot without a form subsist;
And form, say I as well as they,
Must fail if matter brings no grist.
This example program is available online in
• $OS_ROOTDIR/examples/doc_demos/ref4/txn_example.cc (UNIX)
• %OS_ROOTDIR%\examples\doc_demos\ref4\txn_example.cpp (Windows)
For information about using the OS_BEGIN_TXN() and OS_END_TXN() macros to
write lexical transactions, see Using Lexical Transactions in Chapter 5 of the C++ A P I
User Guide.
Release 6.3
477
OS_BEGIN_TXN_NAMED()
OS_BEGIN_TXN_NAMED()
Like the OS_BEGIN_TXN() macro, this macro begins a lexical transaction and
establishes a new scope. Unlike the other macro, this one allows you to specify a
transaction name.
See OS_BEGIN_TXN() on page 474 for a full description of the transaction macros.
478
C++ A P I Reference
Chapter 4: System-Supplied Macros
OS_END_FAULT_HANDLER
Use this macro with the OS_ESTABLISH_FAULT_HANDLER macro to delimit a faulthandler block.
See OS_ESTABLISH_FAULT_HANDLER on page 481 for information on the fault-handler
macros.
Release 6.3
479
OS_END_TXN()
OS_END_TXN()
Use this macro to mark the end of a lexical transaction established by the OS_BEGIN_
TXN() or OS_BEGIN_TXN_NAMED() macro.
See OS_BEGIN_TXN() on page 474 for a full description of the lexical transaction
macros.
480
C++ A P I Reference
Chapter 4: System-Supplied Macros
OS_ESTABLISH_FAULT_HANDLER
OS_ESTABLISH_FAULT_HANDLER and OS_END_FAULT_HANDLER are used to handle
page faults.
Syntax
int main (int argc, char** argv)
{
OS_ESTABLISH_FAULT_HANDLER {
// your code
} OS_END_FAULT_HANDLER
return value;
}
The enclosing braces are not required, but some source code editors complain if you
do not use them.
Description
ObjectStore uses page faulting to detect references to persistent memory. All
applications performing ObjectStore operations must use the OS_ESTABLISH_
FAULT_HANDLER and OS_END_FAULT_HANDLER macros to establish a page-fault
handler at the top of every stack in the program. Essentially, this requirement means
that you must enclose the code in the top-level function (main() or WinMain())
within these macros. If the program uses multiple threads, the first function of each
new thread that uses ObjectStore must also include these macros.
See Establishing a Page Fault Handler in Chapter 3 of the C++ A P I User Guide for
information about using the fault-handler macros.
Release 6.3
481
OS_MARK_SCHEMA_TYPE()
OS_MARK_SCHEMA_TYPE()
Used in schema source files to include a class in an application’s schema.
Syntax
OS_MARK_SCHEMA_TYPE(class)
Arguments
class
The class to be included in the application’s schema. Names defined with the
typedef directive are not allowed. To include a template class that has more than
one argument, use the OS_MARK_SCHEMA_TYPESPEC() macro.
Description
Use the OS_MARK_SCHEMA_TYPE()macro in schema source files when you want to
include a class in your application’s schema. Calls to the macro should appear
outside any function at global or file scope level.
Schema source files must include the file <ostore/manschem.hh> after including
<ostore/ostore.hh> and should contain all the include directives from the
application’s source necessary to compile.
You must mark every class on which the application might perform persistent new,
as well as every class whose instances can be used by the application as database
entry points. You must also mark every class that appears in a library interface query
string or index path in the application.
However, if you specify the -make_reachable_source_classes_persistent
option to the ossg schema generator, you need not mark every class that might be
read from a database. This option causes every class that is defined in the schema
source file and reachable from a persistently marked class to be persistently
allocatable and accessible. The -make_reachable_source_classes_persistent
option is useful to ensure that items that could be overlooked, for example, subtypes,
are marked. However, it can also make classes persistent that do not need to be so
for compilation to succeed.
For information about
• The OS_MARK_SCHEMA_TYPESPEC() macro, see OS_MARK_SCHEMA_TYPESPEC() on
page 483
• Using the OS_MARK_SCHEMA_TYPE() macro in schema source files, see Building
ObjectStore C++ Applications
• The ossg schema generator, see Managing ObjectStore
482
C++ A P I Reference
Chapter 4: System-Supplied Macros
OS_MARK_SCHEMA_TYPESPEC()
Used in schema source files to include a class template when the template has more
than one argument.
Syntax
OS_MARK_SCHEMA_TYPESPEC((type-name<param-list >))
type-name
The name of a class template.
param-list
A comma-separated list of parameters.
Description
The OS_MARK_SCHEMA_TYPESPEC() macro is used in schema source files to include
a class template in an application’s schema when the template has more than one
argument.
You can use this macro to parameterize types with multiple parameters. Note that
you must enclose type-name and param-list within its own set of parentheses,
which results in the double set of parentheses. If the template has one or no
parameters, you can use the OS_MARK_SCHEMA_TYPE() macro.
Calls to the macro should appear outside any function at global or file scope level.
Schema source files must include the file <ostore/manschem.hh> after including
<ostore/ostore.hh> and should contain all the include directives from the
application’s source that are necessary to compile.
You must mark every class on which the application might perform persistent new,
as well as every class whose instances can be used by the application as database
entry points. You also must mark every class that appears in a library interface query
string or index path in the application.
However, if you specify the -make_reachable_source_classes_persistent
option to the ossg schema generator, you need not mark every class that might be
read from a database. This option causes every class that is defined in the schema
source file and reachable from a persistently marked class to be persistently
allocatable and accessible. The -make_reachable_source_classes_persistent
option is useful to ensure that items that could be overlooked, for example, subtypes,
are marked. However, it can also make classes persistent that need be for
compilation to succeed.
For information about
• The OS_MARK_SCHEMA_TYPE() macro, see OS_MARK_SCHEMA_TYPE() on page 482
• Using the OS_MARK_SCHEMA_TYPESPEC() macro in schema source files, see
Building ObjectStore C++ Applications
• The ossg schema generator, see Managing ObjectStore
Release 6.3
483
OS_REFERENCE_NOCLASS()
OS_REFERENCE_NOCLASS()
Used to define template instantiation.
Syntax
OS_REFERENCE_NOCLASS(type)
Arguments
type
The referent type.
Description
If you use a reference type whose referent type is not a class, you must call this
macro, passing the referent type. Calling this macro provides a definition for the
template instantiation. For example, the following defines the class os_
Reference<float>:
OS_REFERENCE_NOCLASS(float);
Implicit instantiation of the template defines operator ->(), which is invalid for
nonclass parameters. Calling the macro defines an instantiation that does not
provide operator ->().
For references whose referent type is not a class, you resolve the pointer by calling
resolve() or by relying on the conversion operator.
For information about reference types, see os_Reference<T> on page 293.
484
C++ A P I Reference
Chapter 4: System-Supplied Macros
OS_REFERENCE_PROTECTED_NOCLASS()
Used to define template instantiation.
Syntax
OS_REFERENCE_PROTECTED_NOCLASS(type)
Arguments
type
The referent type.
Description
If you use a protected reference type whose referent type is not a class, you must call
this macro, passing the referent type. Calling this macro provides a definition for the
template instantiation. For example, the following defines the class os_Reference_
protected<float>:
OS_REFERENCE_PROTECTED_NOCLASS(float);
Implicit instantiation of the template defines operator ->(), which is invalid for
nonclass parameters. Calling the macro defines an instantiation that does not
provide operator ->().
For references whose referent type is not a class, you resolve the pointer by calling
resolve() or by relying on the conversion operator.
For information about protected reference types, see os_Reference_protected<T>
on page 304.
Release 6.3
485
OS_REPORT_DLL_LOAD_AND_UNLOAD()
OS_REPORT_DLL_LOAD_AND_UNLOAD()
Used in schema source files when generating component schemas.
Syntax
OS_REPORT_DLL_LOAD_AND_UNLOAD(boolean )
Arguments
boolean
A Boolean value.
Description
The OS_REPORT_DLL_LOAD_AND_UNLOAD() macro is used in schema source files
when you are generating component schemas. It enables or disables automatic
reporting of DLL loading and unloading.
When boolean is true, automatic reporting of DLL loading and unloading is
enabled. This is accomplished by having ossg generate code that calls os_DLL_
schema_info::DLL_loaded() and os_DLL_schema_info::DLL_unloaded() from
the DLL’s initialization and termination functions. By default, automatic reporting is
enabled.
If boolean is false, automatic reporting is not enabled and you must write your
own code to call os_DLL_schema_info::DLL_loaded() and os_DLL_schema_
info::DLL_unloaded() from the DLL’s initialization and termination functions.
For information about
• Component schemas, see Component Schemas in Chapter 9 of the C++ A P I User
Guide
• The ossg utility, see Managing ObjectStore
486
C++ A P I Reference
Chapter 4: System-Supplied Macros
OS_SCHEMA_DLL_ID()
Used in schema source files when generating component schemas.
Syntax
OS_SCHEMA_DLL_ID(string )
Arguments
string
The string that specifies the DLL identifier.
Description
The OS_SCHEMA_DLL_ID() macro is used in schema source files when you are
generating component schemas to specify the DLL identifier of the DLL.
This macro can be used multiple times, for example, to specify different platformspecific DLL identifiers. Do not conditionalize these calls on the platform; you want
all the DLL identifiers to be recorded in any database that depends on this DLL.
You must call OS_SCHEMA_DLL_ID at least once in a DLL schema source file to
distinguish it from an application schema.
For information about
• Component schemas, see Component Schemas in Chapter 9 of the C++ A P I User
Guide
• The ossg utility, see Managing ObjectStore
Release 6.3
487
OS_SCHEMA_INFO_NAME()
OS_SCHEMA_INFO_NAME()
Used in schema source files when generating component schemas.
Syntax
OS_SCHEMA_INFO_NAME(name )
Arguments
name
The name used for the extern os_DLL_schema_inf variable.
Description
The OS_SCHEMA_INFO_NAME() macro must be used in schema source files when you
are generating component schemas.
This macro generates the variable extern os_DLL_schema_info name; that is, the
os_DLL_schema_info of this DLL. The default is to generate the schema information
with a static name. Call this if you are going to call os_DLL_schema_info::DLL_
loaded() yourself so you can get access to the os_DLL_schema_info.
This macro also works in an application schema, in which case the type of the
variable is os_application_schema_info instead of os_DLL_schema_info.
For information about
• Component schemas, see Component Schemas in Chapter 9 of the C++ A P I User
Guide
• The ossg utility, see Managing ObjectStore
488
C++ A P I Reference
Chapter 4: System-Supplied Macros
os_soft_pointer
The os_soft_pointer macro expands to os_soft_pointer32 on 32-bit platforms
and os_soft_pointer64 on 64-bit platforms.
See os_soft_pointer32<T> on page 381 and os_soft_pointer64<T> on page 384
for more information.
Release 6.3
489
OS_SOFT_POINTER32_NOCLASS()
OS_SOFT_POINTER32_NOCLASS()
Used if a 32-bit soft pointer type is used.
Syntax
OS_SOFT_POINTER32_NOCLASS(type )
Arguments
type
The referent type. This provides a definition for the template instantiation. For
example, the following defines the class os_soft_ptr32<float>:
OS_SOFT_POINTER32_NOCLASS(float);
Description
If you use a 32-bit soft pointer type (see os_soft_pointer32<T> on page 381) whose
referent type is not a class, you must call this macro, passing the referent type.
Implicit instantiation of the template defines operator ->(), which is invalid for
nonclass parameters. Calling the macro defines an instantiation that does not
provide operator ->().
For soft pointers whose referent type is not a class, you resolve the pointer by calling
resolve() or by relying on the conversion operator.
The ObjectStore API explicitly provides (using OS_SOFT_POINTER32_NOCLASS()) the
following instantiations of os_soft_pointer32<T>:
• os_soft_pointer32<void>
• os_soft_pointer32<char>
490
C++ A P I Reference
Chapter 4: System-Supplied Macros
OS_SOFT_POINTER64_NOCLASS()
Used if a 64-bit soft pointer type is used.(
Syntax
OS_SOFT_POINTER64_NOCLASS(type )
Arguments
type
The referent type. This provides a definition for the template instantiation. For
example, the following defines the class os_soft_ptr64<float>:
OS_SOFT_POINTER64_NOCLASS(float);
Description
If you use a 64-bit soft pointer type (see os_soft_pointer64<T> on page 384) whose
referent type is not a class, you must call this macro, passing the referent type.
Implicit instantiation of the template defines operator ->(), which is invalid for
nonclass parameters. Calling the macro defines an instantiation that does not
provide operator ->().
For soft pointers whose referent type is not a class, you resolve the pointer by calling
resolve() or by relying on the conversion operator.
The ObjectStore API explicitly provides (using OS_SOFT_POINTER64_NOCLASS()) the
following instantiations of os_soft_pointer64<T>:
• os_soft_pointer64<void>
• os_soft_pointer64<char>
Release 6.3
491
TIX_END_HANDLE
TIX_END_HANDLE
This macro delimits the end of a block of code for which you have defined a TIX
exception handler.
See TIX_HANDLE() on page 494 for information about the TIX exception handler
macros.
492
C++ A P I Reference
Chapter 4: System-Supplied Macros
TIX_EXCEPTION
This macro is used in a block of code delimited by the macros TIX_HANDLE() and
TIX_END_HANDLE to mark the beginning of the statement block to which control is
transferred in the event of a specified exception.
See TIX_HANDLE() on page 494 for information about the TIX exception handler
macros.
Release 6.3
493
TIX_HANDLE()
TIX_HANDLE()
Used to specify a handler for an exception signaled by a given code block.
Syntax
TIX_HANDLE(exception ) {
exception-block
} TIX_EXCEPTION {
handle-exception-block
} TIX_END_HANDLE
Arguments
exception-block
handle-exception-block
These can consist of any number of statements and are considered to be within
their own block. The enclosing braces are not required, but many source code
editors can complain if you do not use them.
exception
This can be one of the following:
- The name of a predefined TIX exception to be handled. This should not be err_
internal — you cannot handle ObjectStore internal errors.
- A user-defined exception. See DEFINE_EXCEPTION() on page 472 for
information about using this macro to define your own TIX exceptions.
- A parent exception. Specifying a parent exception causes all children of the
parent to be handled. For information about parent exceptions, see Parent
Exceptions on page 500.
Description
This macro is used in conjunction with the macros TIX_EXCEPTION and TIX_END_
HANDLE to specify a handler for an exception signaled by a given code block.
If exception is signaled while control is dynamically within the exception-block,
control is transferred to handle-exception-block, unless a more recently
established handler for the exception is found first. (If the exception occurs within
nested handlers, the innermost nest is considered the most recent.) After handleexception-block executes, program control passes to the statement immediately
following TIX_END_HANDLE.
If exception is signaled but there is no handle-exception-block, program control
passes to the statement immediately following TIX_END_HANDLE. In this situation,
you might want to handle the exception outside the TIX exception handler.
If exception is not signaled in exception-block, control flows from the end of
exception-block to the statement immediately following TIX_END_HANDLE.
In place of the TIX_HANDLE() macro, you can substitute the TIX_HANDLE_IF()
macro, which allows for conditional processing. See TIX_HANDLE_IF() on page 497.
These constructs can be nested, allowing handling of multiple exceptions. For
example:
TIX_HANDLE(exception2 ) {
TIX_HANDLE(exception1 ) {
494
C++ A P I Reference
Chapter 4: System-Supplied Macros
exception-block
} TIX_EXCEPTION {
handle-exception1-block
} TIX_END_HANDLE
} TIX_EXCEPTION {
handle-exception2-block
} TIX_END_HANDLE
Nested handlers are especially useful when the outer handler specifies a parent
exception in exception2 and the inner handlers each specify a child of the parent in
exception1. However, some care should be taken in constructing a nested handler
to ensure that the parent is in the outer handler and the children are in the inner
handlers. If they are reversed, the child might never get control.
The following program illustrates a simple TIX exception handler. The program tries
to open the database file named on the command line. If the attempt fails because the
database does not exist, ObjectStore signals err_database_not_found and program
control passes to handle-exception-block, which handles the exception. The
handler creates a database with the same name.
Note that the intent of this example (as of all the examples in this chapter) is to
illustrate TIX exception handling and not to show how to open a database.
// tix_example.cpp: illustrates a very simple TIX exception handler.
// The program tries to open a database named on the command-line.
// If the open fails because the database doesn't exist
// (err_database_not_found), the exception handler creates a
// database of that name.
#include <ostore/ostore.hh>
#include <iostream>
main(int argc, char** argv)
{
OS_ESTABLISH_FAULT_HANDLER {
if (argc != 2) { // check for name of database
cout << "Usage: " << argv[0] << " <database>" << endl;
return 1;
}
objectstore::initialize();
os_database *db;
TIX_HANDLE(err_database_not_found) {
db = os_database::open(argv[1]); // try to open database
} TIX_EXCEPTION { // an exception was signaled
cout << "Can't open " << argv[1];
cout << ", will create it." << endl;
db = os_database::create(argv[1]);
} TIX_END_HANDLE
cout << "Opened " << db->get_pathname() << endl;
db->close(); // close database
} OS_END_FAULT_HANDLER
return 0;
}
Following is the output from running the program with different command-line
arguments:
$ tix_example # no command-line arguments
Usage: tix_example <database>
$ tix_example nonsense.db # one argument, but doesn't exist
Release 6.3
495
TIX_HANDLE()
Can't open nonsense.db, will create it.
Opened /h/handcuff/2/tmp/examples/nonsense.db
$ tix_example nonsense.db # argument to an existing database
Opened /h/handcuff/2/tmp/examples/nonsense.db
This example program is available online in
• $OS_ROOTDIR/examples/doc_demos/ref4/tix_example.cc (UNIX)
• %OS_ROOTDIR%\examples\doc_demos\ref4\tix_example.cpp (Windows)
See Establishing a TIX Exception Handler in Chapter 6 of the C++ A P I User Guide for
more information about using TIX exception handlers.
496
C++ A P I Reference
Chapter 4: System-Supplied Macros
TIX_HANDLE_IF()
Used to specify a handler for an exception signaled by a given code block.
Syntax
TIX_HANDLE_IF(flag, exception ) {
exception-block
} TIX_EXCEPTION {
handle-exception-block
} TIX_END_HANDLE
Arguments
flag
A conditional expression, as used in an if statement. If it evaluates to nonzero
(true), the handler is established around exception-block; otherwise, no handler
is established.
exception-block
handle-exception-block
As in the TIX_HANDLE() macro, these can consist of any number of statements and
are considered to be within their own block. The enclosing braces are not required,
but many source code editors can complain if you do not use them.
exception
Identifies the exception, just as it does in the TIX_HANDLE() macro.
Description
The TIX_HANDLE_IF() macro is just like the TIX_HANDLE() macro except that it
allows for conditional processing of the exception.
See TIX_HANDLE() on page 494 for information about TIX exception handlers.
Release 6.3
497
TIX_HANDLE_IF()
498
C++ A P I Reference
Chapter 5
Predefined TIX Exceptions
This chapter contains information on significant predefined exceptions. These
exceptions are defined in client.hh, ostore.hh, and /backrest/osbr_err.hh,
making them available to your application.
Release 6.3
499
Parent Exceptions
Parent Exceptions
The following are parents in the exceptions object tree hierarchy. They are never
signaled directly, but they are useful when establishing a TIX exception handler for
them to catch a group of exceptions. See TIX_HANDLE() on page 494.
ObjectStore
exceptions
object tree
hierarchy
The hierarchy is arranged as follows:
all_exceptions
err_objectstore
err_allocator_framework
General exceptions
err_coll
err_mop
err_osbr
err_rpc
err_schema_evolution
• Every TIX exception is a descendant of all_exceptions.
• Every TIX exception that is signaled by ObjectStore itself is a child of err_
objectstore, which is a child of all_exceptions.
• Every TIX exception signaled from the remote procedure call (RPC) mechanism,
which ObjectStore uses for all its network communications, is a child of err_rpc,
which is a child of err_objectstore.
500
C++ A P I Reference
Chapter 5: Predefined TIX Exceptions
General ObjectStore Exceptions
The following exceptions are all descended from err_objectstore.
err_abort_committed
err_address_space_full — Address space is full.
err_alignment — A memory fault was signaled by the operating system, but
rather than the usual access fault, this fault indicates that there was an alignment
error. Often this means that there was an attempt to dereference through a pointer
whose value is odd.
err_architecture_mismatch — The architecture of the database is not compatible
with that of the application.
err_authentication_failure
err_awaiting_recovery — ObjectStore cannot perform a recovery operation
because a server is down and needs to be brought back up. Specifically, this error
occurs when ObjectStore tries to recover a block that is tied up during a two-phase
commit that is still in progress because of a server crash. Check the console messages
to see explanatory messages from the two-phase commit recovery procedure.
err_beyond_segment_length — This error message has several meanings. The
most common is that the client sent a block number that was higher than the highest
block in the segment.
err_broken_server_connection — This usually means the same thing as err_
network_failure and might mean network trouble or that the server has crashed;
see the class os_server on page 367. This exception can also occur if a client is
attempting to communicate with an incompatible server (for example, the server and
client are from different, incompatible releases of ObjectStore).
err_cache_manager_not_responding — The server was unable to form a network
connection to the cache manager process of your client host. You should see whether
the cache manager process appears to be alive; if it is not, look in the operating
system error log for an error message that might help explain what happened to the
cache manager.
err_cannot_commit — ObjectStore tried to perform a commit involving updates
to multiple servers (that is, a two-phase commit), and it cannot determine a common
network for communications.
err_cannot_open_application_schema — This is signaled if you try to create or
look up a database, but the application schema database for your application cannot
be found.
err_cannot_shrink_cluster — This is signaled if you specify a cluster size by
calling os_cluster::set_size() with an argument that is smaller than the current
size, and the call would “shrink” a cluster in a way that would delete persistent
objects. You cannot shrink a cluster other than by removing free space at the end of
the cluster.
Release 6.3
501
General ObjectStore Exceptions
err_checkpoint_aborted
err_checkpoint_committed
err_checkpoint_not_inner
err_cluster_full — Signaled by an attempt to allocate storage in a cluster that
does not have enough room for the specified object.
err_cluster_is_deleted — This error message has several meanings. The most
common is that an operation was attempted on a cluster that has been deleted or is
believed not to exist.
err_cluster_mismatch
err_cluster_transient — Signaled when the user attempts to perform an
operation that is not legal for transient clusters.
err_commit_aborted
err_commit_abort_only — Signaled when the user attempts to commit an abort-
only transaction.
err_commit_with_children
err_conflicting_failover_configuration
err_connection_closed
err_cross_db_pointer — A pointer from one database to another was found. This
happens only if external pointers are not allowed. See, for example, os_
database::allow_external_pointers().
err_cursor_at_end
err_cursor_not_at_object
err_database_exists — The database already exists. This error can occur if you
use os_dbutil::mkdir() and specify the path of an existing database.
err_database_is_deleted — The database has been deleted.
err_database_lock_conflict
err_database_not_found — The specified database was not found. For example,
the application tried to look up /a/b/c, but the directory /a/b did not contain a
database named c.
err_database_not_open — The database is not open. Signaled by the notification
APIs.
err_database_not_open_update — Signaled when the database open mode is not
update; the mode could be read-only or MVCC.
err_database_transient — This operation is not allowed on the transient
database. Signaled by the notification APIs.
err_database_wrong_version — Currently, there is only one version of database
format, so this exception cannot be signaled. In the future, however, the format of
databases might change. This exception is signaled if an executable file linked with
502
C++ A P I Reference
Chapter 5: Predefined TIX Exceptions
an older version of ObjectStore that cannot understand the new format attempts to
operate on a database in the new format.
err_datagram_error
err_db_already_open_multi_db_mvcc — Signalled when an application tries to
open a database for single-database MVCC and the database is already open for
multidatabase MVCC.
err_db_already_open_single_db_mvcc — Signalled when an application tries to
open a database for multidatabase MVCC and the database is already open for
single-database MVCC.
err_db_cannot_change_open — Signaled when the user attempts to open a
database that is already open in a different open mode.
err_db_is_offline — Signalled when an application tries to open a database that
has been taken offline. See osdbcontrol in Managing ObjectStore.
err_db_going_offline — Signalled when an application tries to open a database
that is scheduled to be taken offline. See osdbcontrol in Managing ObjectStore.
err_db_kill_clients_failed — Signalled when an attempt to take a database
offline using the -kill_clients option. See osdbcontrol in Managing ObjectStore.
err_deadlock — A deadlock was detected. Note that ObjectStore transactions
establish handlers for this exception. An exception handler for this exception will
normally receive an instance os_deadlock_exception as the exception object.
err_default_cluster — Cluster cannot be assigned as the default cluster. It can be
a huge cluster, or it might not be in the specified segment.
err_default_segment — Segment cannot be assigned as the default segment. It can
be the system segment or it might not be in the specified database.
err_deref_transient_pointer — An attempt was made to dereference a pointer
to transient memory. The operating system signaled a virtual memory access fault,
but the address of the fault was within the transient area of the address space, rather
than within the persistent area.
err_directory_exists — This is signaled by objectstore::make_directories
or objectstore::mkdir when you try to make a new directory on the Directory
Manager but a directory with that name already exists.
err_directory_not_empty — The directory was not empty, but the application
tried to delete the directory. This can happen only from mkdir.
err_directory_not_found — The specified path name contained a directory
component that was not found.
err_explicit_commit_stack_txn
err_file_error
err_file_not_db
Release 6.3
503
General ObjectStore Exceptions
err_file_not_local — You have asked a server to operate on a file database that
is stored not on that server host but on another host that the server host has mounted
using NFS. This should be possible only if you specify a server explicitly for file
databases, which is not the usual way file databases are used.
err_file_pathname — An entry point has checked a path name and signaled that
it is a file path name rather than a rawfs path name.
err_hardware — A memory fault was signaled by the operating system, but rather
than the usual access fault, this fault indicates that there was a hardware error, such
as a memory bus timeout.
err_illegal_acquire_lock
err_inconsistent_db — This error is signaled if the release of the database is not
compatible with the release of the client, or if the database or transaction log was
modified, renamed, deleted, or moved other than by ObjectStore.
err_indigestible_pna
err_insufficient_virtual_memory — Heap space is used up.
err_internal — This error message has several meanings, including
• The client did a RELEASE_BLOCKS on a block it does not own.
• The client sent a block number that was higher than the highest block in the
segment.
• The database_handle sent by the client was not valid.
• An attempt was made to perform an operation on a segment that has been deleted
or is believed not to exist.
You cannot handle err_internal.
err_invalid_deletion — An argument that was not a pointer to a persistent
object was passed to operator delete.
err_invalid_pathname — A syntactically invalid path name was specified.
err_invalid_root_value — You have tried to store a transient or a cross-database
pointer in a root.
err_license_limit — No connections are available, due to licensing limitations.
This refers to the maximum number of connections, as specified by the server
password file.
err_link_not_found — Intrarawfs link was not found.
err_locator_file_id
err_locator_read_only
err_locator_syntax
err_lock_timeout — An attempt to acquire a lock has been unsuccessful within a
specified amount of time. An exception handler for this exception will normally
504
C++ A P I Reference
Chapter 5: Predefined TIX Exceptions
receive a dynamically-allocated instance of os_lock_timeout_exception as the
exception object.
err_log_data_segment_full —Signalled when the log data segment of the
osserver transaction log is full. This error condition can be caused by a number of
extremely large update transactions running concurrently. It can also occur when the
osrestore utility is used on a very large database. Before running osrestore, large
databases should first be deleted. Deleting them results in the restored data being
directly written to the material database, instead of keeping the restored data in the
transaction log.
err_misc —When you are using notifications, this error can occur for the following
reasons:
- The notification kind specified is reserved for use by ObjectStore.
- The notification queue size must be set before subscribing to notifications.
- The notification queue size must be greater than 0 but no larger than %d entries.
- An error occurred during an attempt to connect to the cache manager
notification service: %s.
- The connection to cache manager was broken.
err_mvcc_incoherent — Signalled when ObjectStore cannot guarantee a consistent
snapshot of all databases open for multidatabase MVCC. See Handling err_mvcc_
incoherent in Chapter 2 of the Advanced C++ A P I User Guide. This exception can can
be signalled in the following circumstances:
- An application tries to open another database for multidatabase MVCC during
a transaction
- Server-to-server communication fails and is re-established between the time an
application opens a database for multidatabase MVCC and the time it tries to
fetches data from the database.
err_mvcc_nested
err_net_cant_connect
err_net_connect_timeout
err_net_connection_refused
err_net_host_down
err_net_no_server
err_network
err_network_failure — The network connection failed, possibly due to network
trouble, or because the server or directory manager crashed.
err_no_credentials — Access is not permitted; no credentials were presented.
err_no_query_trans
err_no_rawfs — There is no rawfs on the server.
err_no_service_on_net
Release 6.3
505
General ObjectStore Exceptions
err_no_such_host — The specified host does not exist.
err_no_trans — There is no transaction in progress.
err_not_a_database — The path name is not the path name of a database. For
example, the application tried to delete a database called /a/b, but /a/b was a
directory.
err_not_a_directory — A path name that was expected to be a directory is
something else, possibly a database.
err_not_assigned — No database is assigned to the specified location. The
application dereferenced a pointer that pointed into an area of virtual memory used
for persistent objects but which was not a valid location. It was not valid because no
database was mapped to the specified address. Typically this means that the
application saved a pointer from a previous transaction, then used it in a subsequent
transaction, which is not allowed.
err_not_auth_db_kill — Signalled when a user tries to put a database offline with
the -kill_clients option but is not authorized to kill other clients. See osdbcontrol
in Managing ObjectStore.
err_null_pointer — An attempt was made to dereference a null (zero) pointer.
err_operation_not_supported
err_operator_new_args — Invalid arguments were specified for ObjectStore’s
operator new. Currently, this can happen only if you try to pass 0 to operator new
as the count argument.
err_os_auth_reg_string_array_too_small — length of the string specifying the
Windows registry location exceeds the length of the array allocated for the string.
err_os_auth_reg_string_invalid — the string specifying the Windows registry
location is null or empty.
err_os_auth_reg_string_too_long — the string specifying the Windows registry
location exceeds the maximum allowable length (MAX_REGISTRY_STRING_LENGTH).
err_os_compaction — Invalid arguments to objectstore::compact().
err_permission_denied — Permission to access this database was denied.
err_prepare_to_commit
err_protocol_not_supported — The ObjectStore client and server (or cache
manager) do not agree on the communication protocol to be used between them.
One reason for the protocol incompatibility could be that the client and server are
from different releases of ObjectStore.
err_rawfs_not_upgraded — The rawfs is from an old release.
err_read_only_file_system — The file database is stored in a read-only file
system.
506
C++ A P I Reference
Chapter 5: Predefined TIX Exceptions
err_reference_not_found — An attempt was made to resolve an object that has
been deleted. This can happen to any safe reference, or to an unsafe reference when
the target segment has been deleted.
err_reference_syntax — A string with improper syntax was passed to the
load() member of a reference class.
err_reference_to_transient — The application attempted to create a safe
reference to a transient location, which is not allowed.
err_restartable
err_root_exists — A root with the specified name already exists. This occurs
only if you create a root explicitly; it cannot happen as a result of implicit root
creation by persistent variables.
err_schema_database — Attempt to use a closed database as a schema database,
or attempt to use as a schema database a database that itself stored its schema
remotely.
err_schema_validation_error — An error occurred during schema validation.
err_schema_validation_failed — The schema could not be validated.
err_segment_is_deleted — This error message has several meanings. The most
common is that an operation was done on a segment that has been deleted or is
believed not to exist.
err_segment_transient — Signaled when the user attempts to perform an
operation that is not legal for transient segments. For example, this error is signaled
if you attempt to create a cluster in a transient segment; see os_segment::create_
cluster() on page 352.
err_server_address_in_use
err_server_cannot_open_cache — This error can occur if the server is running
on the same host as the client and could not open the cache file to use shared memory
transfers.
err_server_full — The server has run out of disk space.
err_server_not_superuser — The server is not running as the superuser.
err_server_refused_connection — The server refused to make the requested
connection.
err_server_restarted
err_string_too_long — Notification string is longer than 16,383 characters.
err_too_many_cross_svr_links — Excessively long cross-server link chain. The
maximum depth of a cross-server link chain is currently 15.
err_too_many_links — Too many levels of intrarawfs links.
err_too_many_retries — The transaction was retried more times than the value
specified by os_transaction::max_retries.
Release 6.3
507
Schema Evolution Exceptions
err_trans — An operation was performed outside a transaction when it should
have been within one, or an operation was performed within a transaction when it
should have been outside any transaction. For example, an attempt was made to
access persistent memory from outside any transaction.
err_transient_pointer — A transient pointer was found in a database.
err_trans_wrong_type — An attempt was made to start a nested transaction
whose type (update or read_only) differs from the type of the transaction within
which it is nested.
err_typespec_mismatch — A persistent variable type mismatch was detected.
This happens if two applications use a database; the first has a persistent variable
with a particular name and type, and the second has a persistent variable with the
same name but with a different type.
err_uninitialized — This error should not occur. It means the database is
uninitialized possibly because the application that created the database aborted
before it finished running, leaving the database empty and not yet initialized. If this
occurs, you should delete the database and recreate it.
err_unknown_pointer — While pointers were being relocated, ObjectStore came
upon a pointer that did not seem to be a valid pointer to any object.
err_user_aborted_simple_authentication
err_write_during_query — An attempt was made to write during a read-only
transaction. Write refers not only to storing into persistent objects but also to other
operations that modify the database, such as creating segments.
err_write_permission_denied — Permission to write this database was denied.
Schema Evolution Exceptions
The following exceptions are all descended from err_schema_evolution, which is
a descendant of err_objectstore.
err_se_ambiguous_subtype_evolution — An attempt was made to evolve an
object to a subtype in which it is not a unique supertype.
err_se_ambiguous_void_pointer — A void pointer was specified that could not
be interpreted unambiguously. This is the case when there are nested data that
occupy the same location before schema evolution but different locations afterward.
err_se_cannot_delete_class — The specified class cannot be deleted from the
schema because other classes still depend upon it.
err_se_cross_database_pointer — An attempt was made to resolve a crossdatabase pointer to a database that was not part of the set of databases being evolved.
err_se_deleted_component — A pointer was specified to the deleted component
of a valid object.
508
C++ A P I Reference
Chapter 5: Predefined TIX Exceptions
err_se_deleted_object — A pointer was specified to a deleted object.
err_se_illegal_pointer — This is the base type for various illegal pointers.
err_se_invalid_subtype_evolution — An attempt was made to evolve an object
to a type that was not a subtype.
err_se_pointer_type_mismatch
err_se_transient_object — A pointer to a transient object was encountered.
err_se_unnecessary — The requested schema evolution was unnecessary; all
schemas under consideration are compatible.
Metaobject Protocol Exceptions
The following exceptions are descended from err_mop, which is a descendant of
err_objectstore.
err_mop
err_mop_forward_definition — An attempt was made to access information
about a class for which only a forward definition exists, and the information required
a full definition.
err_mop_illegal_cast — An attempt was made to cast a metaobject to an
inappropriate type.
Database Copy Exceptions
The following exceptions are descended from err_osbr_all_exceptions, which is
a descendant of err_objectstore.
err_osbr_all_exceptions
err_osbr_misc
err_osbr_invalid_backup_data — Invalid data in backup image.
err_osbr_incomplete_backup_data — Backup image is incomplete.
err_osbr_cant_open_db — The database could not be opened.
err_osbr_not_supported
err_osbr_sync_timed_out — Server synchronization timed out.
err_osbr_restore_deadlocked — Backup/restore deadlocked.
err_osbr_cant_open_exclusive — Couldn't open database for exclusive access
because another client already has the database open or another recovery process
already has exclusive access to the db.
err_osbr_directory_not_found — The specified directory was not found.
Release 6.3
509
Database Copy Exceptions
err_osbr_path_exists — The specified path already exists.
510
C++ A P I Reference
Chapter 5: Predefined TIX Exceptions
RPC Exceptions
The following exceptions are children of err_rpc. They rarely are signaled; only the
most common ones are described in detail in the following list:
err_rpc_cantrecv — The operating system signaled an error when ObjectStore
tried to receive data. The textual message from the operating system is included in
the character-string report in the exception.
err_rpc_cantsend — The operating system signaled an error when ObjectStore
tried to send data. The textual message from the operating system is included in the
character-string report in the exception.
err_rpc_timedout — The server or the directory manager timed out; that is, the
client was waiting for a reply, and after a certain fixed amount of time, did not
receive one. This can mean, among other things, that the server or directory manager
has crashed, that it is slow to respond, or that the network is not working properly.
err_rpc_auth_badcred
err_rpc_auth_badverf
err_rpc_autherror
err_rpc_auth_failed
err_rpc_auth_invalidresp
err_rpc_auth_ok
err_rpc_auth_rejectedcred
err_rpc_auth_rejectedverf
err_rpc_auth_tooweak
err_rpc_cantdecodeargs
err_rpc_cantdecoderes
err_rpc_cantencodeargs
err_rpc_failed
err_rpc_pmapfailure
err_rpc_procunavail
err_rpc_prognotregistered
err_rpc_progunavail
err_rpc_progversmismatch
err_rpc_success
err_rpc_systemerror
err_rpc_unknownhost
Release 6.3
511
Component Schema Exceptions
err_rpc_unknownproto
err_rpc_versmismatch
Component Schema Exceptions
The following exceptions exist:
512
err_schema_not_loaded
“The program schema must be loaded before
doing this operation”
err_schema_not_found
“The specified program schema was not
found”
err_bad_schema_info
“The program schema info being loaded is
invalid”
err_invalid_for_
application_schema
“This operation is invalid for the application
schema”
err_cannot_open_DLL_schema
“Unable to open DLL schema database”
err_transient_dope_damaged
“Some objects’ transient dope could be invalid”
err_DLL
“Operating system DLL operation failed”
err_DLL_not_loaded
“Shared library could not be loaded”
err_DLL_not_unloaded
“Shared library could not be unloaded”
err_DLL_symbol_not_found
“Symbol could not be found in shared library”
C++ A P I Reference
Index
Symbols
()
os_replicator, defined by 317
~os_archiver()
os_archiver, defined by 104
~os_archiver_options()
os_archiver_options, defined by 107
~os_backup()
os_backup, defined by 110
~os_backup_options()
os_backup_options, defined by 115
~os_recover()
os_recover, defined by 287
~os_recover_options()
os_recover_options, defined by 292
~os_replicator_statistic_info()
os_os_replicator_statistic_info,
defined 321
~os_restore()
os_restore, defined by 323
~os_restore_options()
os_restore_options, defined by 328
~os_untranslatable_pointer_handler()
os_untranslatable_pointer_handler, defined
by 451
A
abort()
os_transaction, defined by 409
abort_top_level()
os_transaction, defined by 409
access control
approaches to 45
os_segment_access, the class 362
Access_modifier
os_member, defined by 240
acquire_address_space()
Release 6.3
objectstore, defined by 54
acquire_lock()
objectstore, defined by 54
add()
os_path_to_data, defined by 271
add_db_to_archive()
os_archiver, defined by 104
add_DLL_identifier()
os_DLL_schema_info, defined by 206
add_missing_dispatch_table_handler()
objectstore, defined by 57
address-space markers, disabling 83
affiliate()
os_database, defined by 148
affiliation API
os_database::affiliate() 148
os_database::change_affiliation() 149
os_database::get_affiliated_
databases() 154
os_database::get_affiliation_index_
of() 154
os_database::get_path_to() 160
os_database::has_affiliation_to() 162
after_begin
os_transaction_hook, defined by 415
after_checkpoint
os_transaction_hook, defined by 415
after_commit
os_transaction_hook, defined by 415
allocating storage 459
ancestor_of()
tix_exception, defined by 454
Anonymous_indirect
os_type, defined by 418
Anonymous_union
os_class_type, defined by 119
Application_schema
os_schema, defined by 330
Array
513
B
os_type, defined by 418
assign()
os_notification, defined by 260
os_subscription, defined by 396
augment_classes_to_be_recycled()
os_schema_evolution, defined by 335
augment_classes_to_be_removed()
os_schema_evolution, defined by 335
augment_cluster_split_avoidance()
os_compact, defined by 141
os_schema_evolution, defined by 335
augment_dll_schema_db_names()
os_schema_evolution, defined by 335
augment_optional_classes()
os_schema_evolution, defined by 336
augment_post_compact_transformers()
os_compact, defined by 141
augment_post_evol_transformers()
os_schema_evolution, defined by 336
authentication
os_authentication 109
authorization 362
B
basic_undo()
basic_undo, defined by 52
basic_undo, the class
~basic_undo() 53
basic_undo() 52
get_exception() data member 52
has_exception() data member 52
before_abort
os_transaction_hook, defined by
before_checkpoint
os_transaction_hook, defined by
before_commit
os_transaction_hook, defined by
before_retry
os_transaction_hook, defined by
begin()
os_transaction, defined by 409
binary relationships
modeling 44
bind()
os_mop, defined by 254
bit_offset()
os_path_to_data, defined by 271
byte_offset()
514
415
415
416
416
os_path_to_data, defined by 271
C
change_affiliation()
os_database, defined by 149
change_mapping()
os_str_conv, defined by 391
change_schema_key()
os_database, defined by 149
change_time_interval()
os_archiver, defined by 104
os_replicator, defined by 316
change_type()
objectstore, defined by 58
Char
os_type, defined by 418
checkpoint
os_dbutil::svr_checkpoint() 192
os_transaction::checkpoint() 410
checkpoint()
os_transaction, defined by 410
chgrp()
os_dbutil, defined by 178
chmod()
os_dbutil, defined by 178
chown()
os_dbutil, defined by 178
Class
os_class_type, defined by 119
os_type, defined by 418
class library 47
classes, system-supplied
basic_undo 52
objectstore 54
objectstore_exception 96
os_access_modifier 97
os_address_space_marker 98
os_anonymous_indirect_type 101
os_app_schema 102
os_application_schema_info 103
os_archiver 104
os_archiver_options 106
os_array_type 108
os_authentication 109
os_backup 110
os_backup_options 112
os_base_class 116
os_class_type 119
C++ A P I Reference
Index
os_close_database 130
os_cluster 131
os_cluster_cursor 138
os_cluster_with 140
os_comp_schema 147
os_compact 141
os_database 148
os_database_root 172
os_database_schema 175
os_Database_table 176
os_dbutil 178
os_deadlock_exception 203
os_DLL_finder 205
os_DLL_schema_info 206
os_Dumper_reference 208
os_Dumper_specialization 211
os_dynamic_extent 213
os_enum_type 215
os_enumerator_literal 217
os_evolve_subtype_fun_binding 218
os_export_id 219
os_export_id_cursor 220
os_failover_server 222
os_field_member_variable 224
os_Fixup_dumper 225
os_function_type 227
os_indirect_type 229
os_instantiated_class_type 230
os_int64 231
os_integral_type 232
os_literal 234
os_literal_template_actual_arg 237
os_lock_timeout_exception 238
os_member 240
os_member_function 244
os_member_namespace 248
os_member_type 249
os_member_variable 250
os_mop 254
os_named_indirect_type 257
os_namespace 258
os_notification 260
os_object_cursor 268
os_path_to_data 271
os_pathname_and_segment_number 275
os_pathname_segment_cluster 276
os_persistent_to_transient_pointer_
manager 277
Release 6.3
os_Planning_action 278
os_pointer_literal 279
os_pointer_to_member_type 280
os_pointer_type 281
os_pragma 282
os_rawfs_entry 283
os_real_type 286
os_recover_options 289
os_Reference<T> 293
os_reference_cross_session 297
os_Reference_cross_session<T> 295
os_reference_internal 301
os_Reference_protected<T> 304
os_reference_protected_internal 306
os_reference_type 310
os_relationship_member_variable 311
os_release_cluster_pointer 312
os_release_database_pointer 313
os_release_root_pointer 314
os_release_segment_pointer 315
os_replicator 316
os_replicator_options 318
os_restore 287, 323
os_restore_options 325
os_retain_address 329
os_schema 330
os_schema_evolution 332
os_schema_handle 347
os_schema_info 350
os_schema_install_options 351
os_segment 352
os_segment_access 362
os_segment_cursor 365
os_server 367
os_session 370
os_soft_pointer32<char> 389
os_soft_pointer32<T> 381
os_soft_pointer32<void> 387
os_soft_pointer32_base 373
os_soft_pointer64<char> 390
os_soft_pointer64<T> 384
os_soft_pointer64<void> 388
os_soft_pointer64_base 377
os_str_conv 391
os_string 394
os_subscription 396
os_template 399
os_template_actual_arg 401
515
C
os_template_formal_arg 403
os_template_instantiation 405
os_template_type_formal 407
os_template_value_formal 408
os_transaction 409
os_transaction_hook 415
os_transformer_binding 417
os_type 418
os_Type_fixup_info 429
os_Type_fixup_loader 430
os_Type_info 432
os_Type_loader 434
os_type_template 436
os_type_template_actual_arg 437
os_type_type 438
os_typed_pointer_void 439
os_typespec 440
os_unsigned_int64 446
os_untranslatable_pointer_handler 448
os_void_type 451
os_with_ mapped 452
tix_context 453
tix_exception 454
tix_handler 456
untranslatable_pointer_handler 448
clear_persistent_to_transient_pointers()
objectstore, defined by 58
close()
os_database, defined by 150
close_all_connections()
os_dbutil, defined by 179
close_all_server_connections()
os_dbutil, defined by 179
close_server_connection()
os_dbutil, defined by 179
cluster_number
os_pathname_segment_cluster, defined by 276
clustering 44
specifying using operator new() 459
clusters 44
default
returning 354
setting 360
iterating over 138
transient 133
cmgr_remove_file()
os_dbutil, defined by 179
cmgr_shutdown()
516
os_dbutil, defined by 179
cmgr_stat()
os_dbutil, defined by 179
collections facility macros 469
commit()
os_transaction, defined by 411
compact()
os_compact, defined by 142
compaction 46
compare()
os_string, defined by
compare_nocase()
os_string, defined by
compare_schemas()
os_dbutil, defined by
Compilation_schema
os_schema, defined by
394
394
181
330
component schemas
objectstore::enable_damaged_dope_
repair() 59
objectstore::enable_DLL_schema() 60
objectstore::find_DLL_schema() 61
objectstore::get_autoload_DLLs_
function() 65
objectstore::is_damaged_dope_repair_
enabled() 75
objectstore::is_DLL_schema_enabled() 75
objectstore::load_DLL() 76
objectstore::set_autoload_DLLs_
function() 83
OS_REPORT_DLL_LOAD_AND_UNLOAD(), the
macro 486
OS_SCHEMA_DLL_ID(), the macro 487
os_schema_info 350
OS_SCHEMA_INFO_NAME(), the macro 488
connection_is_broken()
os_server, defined by 367
convert()
os_str_conv, defined by 391
copy_classes()
os_mop, defined by 255
copy_database()
os_dbutil, defined by 182
create()
os_access_modifier, defined by 97
os_anonymous_indirect_type, defined by 101
os_array_type, defined by 108
os_base_class, defined by 116
C++ A P I Reference
Index
os_class_type, defined by 119
os_database, defined by 150
os_enum_type, defined by 215
os_enumerator_literal, defined by 217
os_field_member_variable, defined by 224
os_function_type, defined by 227
os_instantiated_class_type, defined by 230
os_integral_type, defined by 232
os_literal_template_actual_arg, defined
by 237
os_member_function, defined by 244
os_member_namespace, defined by 248
os_member_type, defined by 249
os_member_variable, defined by 250
os_named_indirect_type, defined by 257
os_namespace, defined by 258
os_pointer_literal, defined by 279
os_pointer_to_member_type, defined by 280
os_pointer_type, defined by 281
os_pragma, defined by 282
os_real_type, defined by 286
os_reference_type, defined by 310
os_session, defined by 370
os_template_instantiation, defined by 405
os_template_type_formal, defined by 407
os_template_value_formal, defined by 408
os_Type_loader, defined by 434
os_type_template, defined by 436
os_type_template_actual_arg, defined by 437
os_void_type, defined by 451
create_char()
os_literal, defined by 234
create_cluster()
os_segment, defined by 352
create_defaulted_char()
os_integral_type, defined by 232
create_double()
os_real_type, defined by 286
create_enum_literal()
os_literal, defined by 234
create_float()
os_real_type, defined by 286
create_int()
os_integral_type, defined by 232
create_long()
os_integral_type, defined by 232
create_long_double()
os_real_type, defined by 286
Release 6.3
create_pointer_literal()
os_literal, defined by 234
create_root()
os_database, defined by 152
create_segment()
os_database, defined by 152
create_short()
os_integral_type, defined by 233
create_signed_char()
os_integral_type, defined by 233
os_literal, defined by 234
create_signed_int()
os_literal, defined by 234
create_signed_long()
os_literal, defined by 234
create_signed_short()
os_literal, defined by 234
create_unsigned_char()
os_integral_type, defined by 233
os_literal, defined by 234
create_unsigned_int()
os_literal, defined by 235
create_unsigned_long()
os_literal, defined by 235
create_unsigned_short()
os_literal, defined by 235
create_wchar_t()
os_literal, defined by 235
creating objects 459
cross-database pointers
affiliating databases 148
getting list of affiliated databases 154
retrieving path to affiliated database 160
cross-transaction pointers
disabling 81
enabling 81
current()
os_mop, defined by 255
os_object_cursor, defined by 268
D
data
os_Type_info, defined by 432
data member pairs 44
database access control 362
database fragmention
os_database::get_fragmentation() 157
database permissions 362
517
E
database utility API 178
database_of()
os_cluster, defined by 131
os_segment, defined by 352
database_pathname
os_pathname_and_segment_number, defined
by 275
os_pathname_segment_cluster, defined by 276
Database_schema
os_schema, defined by 330
databases
and persistent data 148
decache()
os_soft_pointer32_base, defined by 373
os_soft_pointer64_base, defined by 377
decaching soft pointers 86
DECLARE_EXCEPTION() macro
objectstore_exception, the class 96
DECLARE_EXCEPTION(), the macro 471
declares_get_os_typespec_function()
os_class_type, defined by 120
default cluster
in a segment 131
returning 354
setting 360
default segment
returning 156
setting 168
DEFINE_EXCEPTION() macro
objectstore_exception, the class 96
DEFINE_EXCEPTION(), the macro 472
defines_virtual_functions()
os_class_type, defined by 120
delete, the operator 458
deregister_hook()
os_transaction_hook, defined by 416
destroy()
os_cluster, defined by 131
os_database, defined by 153
os_database_root, defined by 172
os_segment, defined by 352
destructors and exceptions 52
disconnect()
os_server, defined by 368
disk_free()
os_dbutil, defined by 182
DLL_loaded()
os_DLL_schema_info, defined by 206
518
DLL_unloaded()
os_DLL_schema_info, defined by 207
os_schema_handle, defined by 347
Double
os_type, defined by 418
dump()
os_reference_cross_session, defined by 298
os_reference_internal, defined by 301
os_reference_protected_internal, defined
by 306
os_soft_pointer32_base, defined by 373
os_soft_pointer64_base, defined by 377
dump_info()
os_Fixup_dumper, defined by 225
duplicate()
os_Fixup_dumper, defined by 225
E
embedded_server_available()
objectstore, defined by 59
enable_damaged_dope_repair()
objectstore, defined by 59
enable_DLL_schema()
objectstore, defined by 60
entry points 172
Enum
os_type, defined by 418
enumerators
Namespace 241
no_access 362
objectstore::lock_as_used 76
objectstore::lock_cluster_read 77
objectstore::lock_cluster_write 77
objectstore::lock_database_read 77
objectstore::lock_database_write 77
objectstore::lock_page_write 78
objectstore::lock_segment_read 78
objectstore::lock_segment_write 78
objectstore::os_no_lock 54
objectstore::os_read_lock 54
objectstore::os_write_lock 54
objectstore::own_page_write 79
os_allocation_strategy_least_space 63
os_allocation_strategy_least_wait 63
os_base_class::Private 117
os_base_class::Protected 117
os_base_class::Public 117
os_class_type::Anonymous_union 119
C++ A P I Reference
Index
os_class_type::Class 119
os_class_type::Struct 129
os_class_type::Union 129
os_dbutil::os_svr_ping_is_alive 194
os_dbutil::os_svr_ping_no_such_host 194
os_dbutil::os_svr_ping_not_reachable 194
os_fetch_cluster 67
os_fetch_page 67
os_fetch_stream 67
os_formal_actual_arg::Value 403
os_function_type::Known 227
os_function_type::Unknown 227
os_function_type::Variable 227
os_member::Access_modifier 240
os_member::Field_variable 240
os_member::Function 240
os_member::Namespace 241
os_member::Private 242
os_member::Protected 243
os_member::Public 243
os_member::Relationship 243
os_member::Type 243
os_member::Variable 243
os_rawfs_entry::OSU_DATABASE 285
os_rawfs_entry::OSU_DIRECTORY 285
os_rawfs_entry::OSU_LINK 285
os_segment_access::no_access 362
os_segment_access::read_access 363
os_segment_access::read_write_access 363
os_svr_stat::get_client_info_others 195
os_svr_stat::get_svr_meter_samples 195
os_svr_stat::get_svr_parameters 195
os_svr_stat::get_svr_usage 195
os_template::Function 399
os_template::Type 400
os_template_actual_arg::literal_
actual 401
os_template_actual_arg::type_actual 401
os_template_formal_arg::Typel 403
os_transaction::read_only 413
os_transaction::update 414
os_transaction_hook::after_begin 415
os_transaction_hook::after_commit 415
os_transaction_hook::before_abort 415
os_transaction_hook::before_commit 415,
416
os_transaction_hook::before_retry 416
os_type::Anonymous_indirect 418
Release 6.3
os_type::Array 418
os_type::Char 418
os_type::Class 418
os_type::Double 418
os_type::Enum 418
os_type::Float 418
os_type::Function 418
os_type::Instantiated_class 420
os_type::Integer 420
os_type::Long_double 421
os_type::Named_indirect 421
os_type::Pointer 425
os_type::Pointer_to_member 425
os_type::Reference 425
os_type::Signed_char 425
os_type::Signed_long 426
os_type::Signed_short 426
os_type::Type 427
os_type::Undefined 427
os_type::Unsigned_char 427
os_type::Unsigned_integer 427
os_type::Unsigned_long 428
os_type::Unsigned_short 428
os_type::Void 428
OSU_DATABASE 285
OSU_DIRECTORY 285
OSU_LINK 285
read_access 363
read_write_access 363
equal_DLL_identifiers()
os_DLL_finder, defined by 205
equal_DLL_identifiers_same_prefix()
os_DLL_finder, defined by 205
equal_signature()
os_function_type, defined by 227
err_abort_committed exception 501
err_address_space_full exception 501
objectstore::acquire_address_space() 54
objectstore::set_default_address_space_
partition_size() 87
os_session::create() 370
os_session::force_full_
initialization() 370
err_alignment exception 501
err_architecture_mismatch exception 501
err_authentication_failure exception 501
err_awaiting_recovery exception 501
err_beyond_segment_length exception 501
519
E
err_broken_connection exception
os_dbutil::svr_ping() 194
err_broken_server_connection exception 501
handling with os_server 367
os_transaction::prepare_to_commit() 412
err_cache_manager_not_responding
exception 501
err_cannot_commit exception 501
err_cannot_open_application_schema
exception 501
err_cannot_shrink_cluster exception 501
os_cluster::set_size() 136
err_checkpoint_aborted exception 502
err_checkpoint_committed exception 502
err_checkpoint_not_inner exception 502
err_cluster_full exception
described 502
os_cluster, the class 459
os_cluster_with, the class 140
err_cluster_is_deleted exception
described 502
os_cluster::destroy() 131
err_cluster_mismatch exception 502
err_cluster_transient exception 502
err_commit_abort_only exception 502
err_commit_aborted exception 502
err_commit_with_children exception 502
err_conflicting_failover_configuration
exception 502
err_connection_closed exception 502
err_cross_db_pointer exception 502
err_cross_server_rename exception
os_dbutil::rename() 190
err_cursor_at_end exception 502
err_cursor_not_at_object exception 502
err_database_exists exception 502
os_database::create() 151
os_dbutil::make_link() 184
os_dbutil::mkdir() 185
os_dbutil::rename() 190
err_database_is_deleted exception 502
returned by os_database::destroy() 153
err_database_lock_conflict exception 502
err_database_not_found exception 502
returned by os_database::destroy() 153
returned by os_database::lookup() 163
returned by os_database::open() 164
err_database_not_open exception 502
520
objectstore::set_auto_open_mode() 84
os_database::create_root() 152
err_database_not_open_update exception 502
err_database_segment exception
returned by os_database::create_
segment() 152
err_database_transient exception 502
err_database_wrong_version exception 502
err_datagram_error exception 503
err_db_already_open_multi_db_mvcc
exception 503
err_db_already_open_single_db_mvcc
exception 503
err_db_cannot_change_open exception 503
returned by os_database::open() 164
err_db_going_offline exception 503
err_db_is_offline exception 503
err_db_kill_clients_failed exception 503
err_deadlock exception 503
objectstore::acquire_lock() 55
os_transaction::prepare_to_commit() 412
tix_exception::release_pointer() 454
tix_exception::set_unhandled_exception_
hook() 455
err_default_cluster exception 503
err_default_segment exception 503
err_deref_transient_pointer exception 503
err_directory_exists exception 503
os_dbutil::make_link() 184
os_dbutil::mkdir() 185
os_dbutil::rename() 190
err_directory_not_empty exception 503
os_dbutil::rmdir() 190
err_directory_not_found exception 503
os_dbutil::mkdir() 185
err_DLL_not_loaded exception
objectstore::find_DLL_schema() 61
objectstore::load_DLL() 76
err_DLL_not_unloaded exception
objectstore::unload_DLL() 94
err_DLL_symbol_not_found exception
objectstore::lookup_DLL_symbol() 78
err_explicit_commit_stack_txn exception 503
err_file_error exception 503
os_dbutil::remove() 190
err_file_not_db exception 503
err_file_not_local exception 504
os_dbutil::remove() 190
C++ A P I Reference
Index
err_file_pathname exception 504
err_hardware exception 504
err_illegal_acquire_lock exception 504
err_illegal_pointer exception
returned by os_schema_
evolution::evolve() 339
err_inconsistent_db exception 504
err_indigestible_pna exception 504
err_insufficient_virtual_memory
exception 504
err_internal exception 504
objectstore::set_cache_file() 85
err_invalid_deletion exception 504
delete operator 458
err_invalid_for_application_schema exception
os_schema_handle::DLL_unloaded() 347
err_invalid_pathname exception 504
err_invalid_pathname_encoding exception 90
err_invalid_rename exception
os_dbutil::rename() 190
err_invalid_root_value exception 504
os_database_root::set_value() 174
err_license_limit exception 504
err_link_not_found exception 504
err_locator_file_id exception 504
err_locator_misc exception
objectstore::set_locator_file() 88
err_locator_read_only exception 504
err_locator_syntax exception 504
err_lock_timeout exception 504
tix_exception::release_pointer() 454
err_log_data_segment_full exception
described 505
err_misc exception
described 505
objectstore::acquire_address_space() 54
objectstore::initialize_for_
sessions() 73
objectstore::set_default_address_space_
partition_size() 87
os_database::size() 171
os_database::size_in_sectors() 171
os_dbutil::cmgr_stat() 180
os_dbutil::disk_free() 182
os_dbutil::svr_stat() 195
os_schema_info::get() 350
os_segment, the class 459
os_server class 367
Release 6.3
os_session::create() 370
err_mop exception 509
os_class_type::get_dispatch_table_
pointer_offset() 122
os_class_type::get_dispatch_table_
pointer_offset_other_compiler() 122
os_class_type::get_most_derived_
class() 123
os_member_variable::get_offset() 250
os_member_variable::get_size() 250
os_member_variable::set_offset() 252
os_void_type, the class 451
err_mop_cannot_neutralize exception
os_mop::bind() 254
os_mop::get_failure_classes() 255
os_mop::get_neutralized_classes() 255
err_mop_forward_definition exception 509
os_class_type::find_base_class() 120
os_class_type::find_member_
variable() 120
os_class_type::get_base_classes() 121
os_class_type::get_indirect_virtual_
base_classes() 122
os_class_type::get_members() 123
err_mop_illegal_cast exception 509
os_class_type::operator os_instantiated_
class_type&() 127
os_member operators 241
os_member_variable operators 252
os_schema operators 330
os_template operators 399, 400
os_template_actual_arg operators 401
os_template_formal_arg operators 403
os_type operators 421
err_mop_not_neutral exception
os_mop::bind() 254
err_mvcc_incoherent exception
described 505
err_mvcc_nested exception 505
returned by os_database::open_mvcc() 166
err_net_cant_connect exception 505
err_net_connect_timeout exception 505
err_net_connection_refused exception 505
err_net_host_down exception 505
err_net_no_server exception 505
err_network exception 505
err_network_failure exception 505
err_no_credentials exception 505
521
E
err_no_query_trans exception 505
err_no_rawfs exception 505
err_no_schema exception
os_app_schema::get() 102
os_database_schema::get() 175
os_database_schema::get_for_update() 175
err_no_service_on_net exception 505
err_no_session exception
objectstore::acquire_address_space() 54
objectstore::initialize_for_
sessions() 74
os_segment::get_current() 371
err_no_such_host exception 506
err_no_trans exception 506
err_not_a_database exception 506
os_dbutil::remove() 190
err_not_a_directory exception 506
os_dbutil::list_directory() 184
os_dbutil::rmdir() 190
err_not_a_link exception
os_dbutil::rehost_link() 189
err_not_assigned exception 506
err_not_auth_db_kill exception 506
err_not_supported exception
objectstore::propagate_log() 79
err_null_pointer exception 506
err_opened_read_only exception
returned by os_database::change_schema_
key() 149
returned by os_database::freeze_schema_
key() 154
returned by os_database::open_mvcc() 166
err_operation_not_supported exception 506
err_operator_new_args exception 506
err_os_auth_reg_string_array_too_small
exception 506
thrown by os_authentication::get_nt_
registry_location() 109
err_os_auth_reg_string_invalid exception 506
thrown by os_authentication::set_nt_
registry_location() 109
err_os_auth_reg_string_too_long
exception 506
thrown by os_authentication::set_nt_
registry_location() 109
err_os_compaction exception 506
err_os_query_evaluation_error exception
returned by os_schema_
522
evolution::evolve() 339
err_osbr_all_exceptions exception 509
err_osbr_cant_open_db exception 509
err_osbr_cant_open_exclusive exception 509
err_osbr_directory_not_found exception 509
err_osbr_incomplete_backup_data
exception 509
err_osbr_invalid_backup_data exception 509
err_osbr_misc exception 509
err_osbr_not_supported exception 509
err_osbr_path_exists exception 510
err_osbr_restore_deadlocked exception 509
err_osbr_sync_timed_out exception 509
err_permission_denied exception 506
err_prepare_to_commit exception 506
os_transaction::prepare_to_commit() 413
err_protocol_not_supported exception 506
err_rawfs_not_upgraded exception 506
err_read_only_file_system exception 506
err_reference_not_found exception 507
err_reference_syntax exception
described 507
os_reference_cross_session::load() 298
os_reference_internal::get_database_
key() 301
os_reference_internal::load() 302
os_reference_protected::get_database_
key() 307
os_reference_protected_
internal::load() 307
os_soft_pointer32_base::get_database_
key() 374
os_soft_pointer32_base::load() 375
os_soft_pointer64_base::get_database_
key() 378
os_soft_pointer64_base::load() 379
err_reference_to_transient exception 507
err_restartable exception 507
err_root_exists exception 507
os_database::create_root() 152
err_rpc_auth_badcred exception 511
err_rpc_auth_badverf exception 511
err_rpc_auth_failed exception 511
err_rpc_auth_invalidresp exception 511
err_rpc_auth_ok exception 511
err_rpc_auth_rejectedcred exception 511
err_rpc_auth_rejectedverf exception 511
err_rpc_auth_tooweak exception 511
C++ A P I Reference
Index
err_rpc_autherror exception 511
err_rpc_cantdecodeargs exception 511
err_rpc_cantdecoderes exception 511
err_rpc_cantencodeargs exception 511
err_rpc_cantrecv exception 511
err_rpc_cantsend exception 511
err_rpc_failed exception 511
err_rpc_pmapfailure exception 511
err_rpc_procunavail exception 511
err_rpc_prognotregistered exception 511
err_rpc_progunavail exception 511
err_rpc_progversmismatch exception 511
err_rpc_success exception 511
err_rpc_systemerror exception 511
err_rpc_timedout exception 511
err_rpc_unknownhost exception 511
err_rpc_unknownproto exception 512
err_rpc_versmismatch exception 512
err_schema_database exception 507
os_database::create() 151
os_database::open() 165
os_database::set_schema_database() 170
err_schema_evolution exception
returned by os_schema_
evolution::evolve() 339
err_schema_key exception
objectstore::set_current_schema_key() 86
os_database::change_schema_key() 150
returned by os_database::freeze_schema_
key() 154
err_schema_not_found exception
objectstore::find_DLL_schema() 61
err_schema_not_loaded exception
os_schema_handle::get() 347
err_schema_validation_error exception 507
err_schema_validation_failed exception 507
err_se_ambiguous_subtype_evolution
exception 508
err_se_ambiguous_void_pointer exception 508
err_se_cannot_delete_class exception 508
returned by os_schema_evolution::augment_
classes_to_be_removed() 335
err_se_cross_database_pointer exception 508
err_se_deleted_component exception 508
err_se_deleted_object exception 509
err_se_illegal_pointer exception 509
err_se_invalid_subtype_evolution
exception 509
Release 6.3
err_se_pointer_type_mismatch exception 509
err_se_transient_object exception 509
err_se_unnecessary exception 509
err_segment_is_deleted exception 507
os_segment::destroy() 352
err_segment_transient exception 507
os_segment::create_cluster() 352
err_server_address_in_use exception 507
err_server_cannot_open_cache exception 507
err_server_full exception 507
os_transaction::prepare_to_commit() 412
err_server_not_superuser exception 507
err_server_refused_connection exception 507
os_server::reconnect() 369
err_server_restarted exception 507
err_string_too_long exception 507
err_too_many_cross_svr_links exception 507
err_too_many_links exception 507
err_too_many_retries exception 507
err_trans exception 508
os_server::disconnect() 368
os_transaction::is_lock_contention() 412
err_trans_wrong_type exception 508
err_transient_pointer exception 508
err_typespec_mismatch exception 508
err_uninitialized exception 508
err_unknown_pointer exception 508
err_user_aborted_simple_authentication
exception 508
err_write_during_query exception 508
err_write_permission_denied exception 508
evolve()
os_schema_evolution, defined by 337
example programs
DEFINE_EXCEPTION(), the macro 472
OS_BEGIN_TXN(), the macro 475
TIX_HANDLE(), the macro 495
exception facility classes
basic_undo 52
objectstore_exception 96
tix_context 453
tix_exception 454
tix_handler 456
exceptions
See also TIX exceptions
action when no handler for 96
ancestor 454
database copy 509
523
E
descendant 454
destructors invoked 52
err_abort_committed 501
err_address_space_full 501
err_alignment 501
err_all_exceptions 509
err_architecture_mismatch 501
err_authentication_failure 501
err_awaiting_recovery 501
err_beyond_segment_length 501
err_broken_connection 194
err_broken_server_connection 501
err_cache_manager_not_responding 501
err_cannot_commit 501
err_cannot_open_application_schema 501
err_cannot_shrink_cluster 501
err_checkpoint_aborted 502
err_checkpoint_committed 502
err_checkpoint_not_inner 502
err_cluster_full 502
err_cluster_is_deleted 502
err_cluster_mismatch 502
err_cluster_transient 502
err_commit_abort_only 502
err_commit_aborted 502
err_commit_with_children 502
err_conflicting_failover_
configuration 502
err_connection_closed 502
err_cross_db_pointer 502
err_cross_server_rename 190
err_cursor_at_end 502
err_cursor_not_at_object 502
err_database_exists 502
err_database_is_deleted 502
err_database_lock_conflict 502
err_database_not_found 502
err_database_not_open 502
err_database_not_open_update 502
err_database_segment 152
err_database_transient 502
err_database_wrong_version 502
err_datagram_error 503
err_db_already_open_multi_db_mvcc 503
err_db_already_open_single_db_mvcc 503
err_db_cannot_change_open 503
err_db_going_offline 503
err_db_is_offline 503
524
err_db_kill_clients_failed 503
err_deadlock 503
err_default_cluster 503
err_default_segment 503
err_deref_transient_pointer 503
err_directory_exists 503
err_directory_not_empty 503
err_directory_not_found 503
err_DLL_not_loaded 61
err_DLL_not_unloaded 94
err_DLL_symbol_not_found 78
err_explicit_commit_stack_txn 503
err_file_error 503
err_file_not_db 503
err_file_not_local 504
err_file_pathname 504
err_hardware 504
err_illegal_acquire_lock 504
err_illegal_pointer 339
err_inconsistent_db 504
err_indigestible_pna 504
err_insufficient_virtual_memory 504
err_internal 504
err_invalid_deletion 504
err_invalid_for_application_schema 347
err_invalid_pathname 504
err_invalid_pathname_encoding 90
err_invalid_rename 190
err_invalid_root_value 504
err_license_limit 504
err_link_not_found 504
err_locator_file_id 504
err_locator_misc 88
err_locator_read_only 504
err_locator_syntax 504
err_lock_timeout 504
err_log_data_segment_full 505
err_misc 505
err_mop 509
err_mop_cannot_neutralize 254
err_mop_forward_definition 509
err_mop_illegal_cast 509
err_mop_not_neutral 254
err_mvcc_incoherent 505
err_mvcc_nested 505
err_net_cant_connect 505
err_net_connect_timeout 505
err_net_connection_refused 505
C++ A P I Reference
Index
err_net_host_down 505
err_net_no_server 505
err_network 505
err_network_failure 505
err_no_credentials 505
err_no_query_trans 505
err_no_rawfs 505
err_no_schema 102
err_no_service_on_net 505
err_no_session 54
err_no_such_host 506
err_no_trans 506
err_not_a_database 506
err_not_a_directory 506
err_not_a_link 189
err_not_assigned 506
err_not_auth_db_kill 506
err_not_supported 79
err_null_pointer 506
err_opened_read_only 149, 154
err_operation_not_supported 506
err_operator_new_args 506
err_os_auth_reg_string_array_too_
small 506
err_os_auth_reg_string_invalid 506
err_os_auth_reg_string_too_long 506
err_os_compaction 506
err_os_query_evaluation_error 339
err_osbr_ path_exists 510
err_osbr_cant_open_db 509
err_osbr_cant_open_exclusive 509
err_osbr_directory_not_found 509
err_osbr_invalid_backup_data 509
err_osbr_misc 509
err_osbr_not_supported 509
err_osbr_restore_deadlocked 509
err_osbr_sync_timed_out 509
err_permission_denied 506
err_prepare_to_commit 506
err_protocol_not_supported 506
err_rawfs_not_upgraded 506
err_read_only_file_system 506
err_reference_not_found 507
err_reference_syntax 507
err_reference_to_transient 507
err_restartable 507
err_root_exists 507
err_rpc_auth_badcred 511
Release 6.3
err_rpc_auth_badverf 511
err_rpc_auth_failed 511
err_rpc_auth_invalidresp 511
err_rpc_auth_ok 511
err_rpc_auth_rejectedcred 511
err_rpc_auth_rejectedverf 511
err_rpc_auth_tooweak 511
err_rpc_autherror 511
err_rpc_cantdecodeargs 511
err_rpc_cantdecoderes 511
err_rpc_cantencodeargs 511
err_rpc_cantrecv 511
err_rpc_cantsend 511
err_rpc_failed 511
err_rpc_pmapfailure 511
err_rpc_procunavail 511
err_rpc_prognotregistered 511
err_rpc_progunavail 511
err_rpc_progversmismatch 511
err_rpc_success 511
err_rpc_systemerror 511
err_rpc_timedout 511
err_rpc_unknownhost 511
err_rpc_unknownproto 512
err_rpc_versmismatch 512
err_schema_database 507
err_schema_evolution 339
err_schema_key 86, 150
err_schema_not_found 61
err_schema_not_loaded 347
err_schema_validation_error 507
err_schema_validation_failed 507
err_se_ambiguous_subtype_evolution 508
err_se_ambiguous_void_pointer 508
err_se_cannot_delete_class 508
err_se_cross_database_pointer 508
err_se_deleted_component 508
err_se_deleted_object 509
err_se_illegal_pointer 509
err_se_invalid_subtype_evolution 509
err_se_pointer_type_mismatch 509
err_se_transient_object 509
err_se_unnecessary 509
err_segment_is_deleted 507
err_segment_transient 507
err_server_address_in_use 507
err_server_cannot_open_cache 507
err_server_full 507
525
F
err_server_not_superuser 507
err_server_refused_connection 507
err_server_restarted 507
err_string_too_long 507
err_too_many_cross_svr_links 507
err_too_many_links 507
err_too_many_retries 507
err_trans 508
err_trans_wrong_type 508
err_transient_pointer 508
err_typespec_mismatch 508
err_uninitialized 508
err_unknown_pointer 508
err_user_aborted_simple_
authentication 508
err_write_during_query 508
err_write_permission_denied 508
general ObjectStore 501
handling 469
metaobject protocol 509
ObjectStore internal errors 494
parent 454
predefined 499
remote procedure call (RPC) mechanism 511
schema evolution 508
signaling 96
expand_global()
os_dbutil, defined by 182
export_object()
objectstore, defined by 60
F
fault handler macros
OS_END_FAULT_HANDLER 479
OS_END_TXN() 480
OS_ESTABLISH_FAULT_HANDLER 481
Field_variable
os_member, defined by 240
file_db_pathname()
os_dbutil, defined by 183
find()
os_database_root, defined by 172
find_base_class()
os_class_type, defined by 120
find_DLL_schema()
objectstore, defined by 61
find_member_variable()
os_class_type, defined by 120
526
find_namespace()
os_mop, defined by 255
find_reference()
os_Database_table, defined by 176
find_root()
os_database, defined by 153
find_type()
os_mop, defined by 255
os_schema, defined by 330
first()
os_object_cursor, defined by 268
fixup()
os_Type_fixup_loader, defined by 430
os_Type_loader, defined by 434
fixup_data
os_Type_fixup_info, defined by 429
Float
os_type, defined by 418
force_full_initialization()
os_session, defined by 370
format_and_print_statistics()
os_replicator_statistic_info, defined
by 322
format_statistics()
os_replicator_statistic_info, defined
by 322
fragmentation
os_cluster::set_size() 136
os_database::get_fragmentation() 157
os_database::set_size() 170
os_database::set_size_in_sectors() 171
fragmentationos_database::set_size()database
fragmentationos_database::set_
size() 170
fragmentationos_database::set_size_in_
sectors()database fragmentationos_
database::set_size_in_sectors() 171
fragmentationos_dbutil, the
class::ossize()database
fragmentationos_dbutil, the
class::ossize() 136, 187
free_memory()
objectstore, defined by 61
freeze_schema_key()
os_database, defined by 153
Function
os_member, defined by 240
os_template, defined by 399
C++ A P I Reference
Index
os_type, defined by 418
G
get()
os_app_schema, defined by 102
os_cluster_with, defined by 140
os_comp_schema, defined by 147
os_database_schema, defined by 175
os_Database_table, defined by 176
os_DLL_finder, defined by 205
os_schema_handle, defined by 347
os_schema_info, defined by 350
os_Type_fixup_loader, defined by 430
os_Type_loader, defined by 434
get_abs_path()
os_rawfs_entry, defined by 283
get_access()
os_base_class, defined by 116
os_member, defined by 240
get_access_control()
os_segment, defined by 352
get_access_of_get_os_typespec_function()
os_class_type, defined by 121
get_address_space_generation_number()
objectstore, defined by 62
get_affiliated_databases()
os_database, defined by 154
get_affiliation_index_of()
os_database, defined by 154
get_alignment()
os_type, defined by 419
get_all()
os_schema_handle, defined by 347
get_all_clusters()
os_segment, defined by 353
get_all_databases()
os_database, defined by 154
get_all_roots()
os_database, defined by 155
get_all_segments()
os_database, defined by 155
get_all_segments_and_permissions()
os_database, defined by 155
get_all_servers()
objectstore, defined by 62
get_all_sessions()
os_session, defined by 370
get_allocated_virtual_base_classes()
Release 6.3
os_class_type, defined by 121
get_allocation_strategy()
objectstore, defined by 62
os_cluster, defined by 131
os_database, defined by 156
os_segment, defined by 353
get_always_check_server_connection_at_
commit()
objectstore, defined by 63
get_application_info()
os_database, defined by 156
os_segment, defined by 353
get_application_names()
os_deadlock_exception, defined by 203
os_lock_timeout_exception, defined by 238
get_application_schema_handle()
os_schema_handle, defined by 348
get_application_schema_pathname()
objectstore, defined by 64
get_arg_list()
os_function_type, defined by 227
get_arg_list_kind()
os_function_type, defined by 227
get_args()
os_template, defined by 399
os_template_instantiation, defined by 405
get_as_intervals()
objectstore, defined by 64
get_asmarkers_useless()
objectstore, defined by 64
get_auto_open_mode()
objectstore, defined by 64
get_autoload_DLLs_function()
objectstore, defined by 64
get_base_classes()
os_class_type, defined by 121
get_base_member()
os_access_modifier, defined by 97
get_cache_file()
objectstore, defined by 65
get_cache_size()
objectstore, defined by 65
get_call_linkage()
os_member_function, defined by 244
get_char()
os_typespec, defined by 440
get_char_value()
os_literal, defined by 235
527
G
get_class()
os_base_class, defined by 116
get_class_kind()
os_class_type, defined by 122
get_classes()
os_schema, defined by 330
get_client_name()
objectstore, defined by 65
os_dbutil, defined by 183
get_cluster()
os_segment, defined by 353
get_clusters()
os_segment, defined by 354
get_comment()
os_segment, defined by 354
get_converted_size()
os_str_conv, defined by 392
get_copy_member_functions()
os_schema_install_options, defined by 351
get_creation_time()
os_rawfs_entry, defined by 283
get_current()
os_address_space_marker, defined by 99
os_cluster_cursor, defined by 138
os_export_id_cursor, defined by 220
os_segment_cursor, defined by 365
os_session, defined by 370
os_transaction, defined by 411
tix_handler, defined by 456
get_current_archive_file_name()
os_archiver, defined by 104
get_database()
os_Dumper_reference, defined by 208
os_notification, defined by 260
os_reference_cross_session, defined by 298
os_reference_internal, defined by 301
os_reference_protected_internal, defined
by 306
os_soft_pointer32_base, defined by 374
os_soft_pointer64_base, defined by 378
os_subscription, defined by 397
get_database_key()
os_reference_internal, defined by 301
os_reference_protected_internal, defined
by 307
os_soft_pointer32_base, defined by 374
os_soft_pointer64_base, defined by 378
get_database_number()
528
os_Dumper_reference, defined by 208
get_databases()
os_server, defined by 368
get_decache_soft_pointers_after_address_
space_release()
objectstore, defined by 65
get_default()
os_segment_access, defined by 362
get_default_cluster()
os_segment, defined by 354
get_default_partition_size()
objectstore, defined by 65
get_default_segment()
os_database, defined by 156
get_defining_class()
os_member, defined by 240
get_dispatch_table_pointer_offset()
os_class_type, defined by 122
get_dispatch_table_pointer_offset_other_
compiler()
os_class_type, defined by 122
get_DLL_identifiers()
os_schema_handle, defined by 348
os_schema_info, defined by 350
get_double()
os_typespec, defined by 440
get_element_type()
os_array_type, defined by 108
get_enclosing_class()
os_type, defined by 419
get_enclosing_namespace()
os_namespace, defined by 258
get_enclosing_object()
os_schema_evolution, defined by 340
get_enum_literal()
os_literal, defined by 235
get_enumerator()
os_enum_type, defined by 215
get_enumerators()
os_enum_type, defined by 215
get_evolved_schema()
os_schema_evolution, defined by 340
get_evolved_schema_db_name()
os_schema_evolution, defined by 340
get_exception()
basic_undo, defined by 52
os_untranslatable_pointer_handler, defined
by 448
C++ A P I Reference
Index
tix_handler, defined by 456
get_explanation()
os_untranslatable_pointer_handler, defined
by 448
get_explanation_level()
os_schema_evolution, defined by 340
get_export_id()
objectstore, defined by 66
get_export_ids()
os_segment, defined by 355
get_failure_classes()
os_mop, defined by 255
get_fault_addr()
os_deadlock_exception, defined by 204
os_lock_timeout_exception, defined by 238
_get_fd()
os_notification, defined by 260
get_fetch_policy()
objectstore, defined by 66
os_cluster, defined by 131
os_database, defined by 156
os_segment, defined by 355
get_file_host_name()
os_database, defined by 157
get_final_offset()
os_untranslatable_pointer_handler, defined
by 449
get_float()
os_typespec, defined by 440
get_for_update()
os_database_schema, defined by 175
get_fragmentation()
os_database, defined by 157
get_function_kind()
os_member_function, defined by 244
get_group_name()
os_rawfs_entry, defined by 283
get_high()
os_int64, defined by 231
os_unsigned_int64, defined by 446
get_host_name()
os_database, defined by 158
os_server, defined by 368
get_hostnames()
os_deadlock_exception, defined by 204
os_lock_timeout_exception, defined by 239
get_incremental_schema_installation()
objectstore, defined by 67
Release 6.3
os_database, defined by 158
get_indirect_virtual_base_classes()
os_class_type, defined by 122
get_instantiation()
os_instantiated_class_type, defined by 230
get_int()
os_typespec, defined by 440
get_kind()
os_literal, defined by 235
os_member, defined by 240
os_notification, defined by 260
os_schema, defined by 330
os_template, defined by 399
os_template_actual_arg, defined by 401
os_template_formal_arg, defined by 403
os_type, defined by 419
get_kind_string()
os_type, defined by 420
get_level()
os_address_space_marker, defined by 99
get_link_host()
os_rawfs_entry, defined by 283
get_link_path()
os_rawfs_entry, defined by 283
get_literal()
os_literal_template_actual_arg, defined
by 237
get_location()
os_notification, defined by 261
get_locator_file()
objectstore, defined by 67
get_lock_option()
objectstore, defined by 68
os_cluster, defined by 132
os_database, defined by 158
os_segment, defined by 356
get_lock_status()
objectstore, defined by 68
get_lock_timeout()
objectstore, defined by 68
get_lock_type()
os_deadlock_exception, defined by 204
os_lock_timeout_exception, defined by 239
get_log_file()
objectstore, defined by 69
get_logical_server_hostname()
os_failover_server, defined by 222
get_long()
529
G
os_typespec, defined by 441
get_long_double()
os_typespec, defined by 441
get_low()
os_int64, defined by 231
os_unsigned_int64, defined by 446
get_members()
os_class_type, defined by 123
os_namespace, defined by 258
get_most_derived_class()
os_class_type, defined by 123
get_n_clusters()
os_segment, defined by 356
get_n_databases()
os_database, defined by 159
os_server, defined by 368
get_n_roots()
os_database, defined by 159
get_n_sectors()
os_rawfs_entry, defined by 283
get_n_segments()
os_database, defined by 159
get_n_servers()
objectstore, defined by 69
get_n_sessions()
os_session, defined by 371
get_name()
os_class_type, defined by 125
os_database_root, defined by 172
os_enum_type, defined by 215
os_enumerator_literal, defined by 217
os_member_function, defined by 245
os_member_variable, defined by 250
os_named_indirect_type, defined by 257
os_namespace, defined by 258
os_pointer_literal, defined by 279
os_rawfs_entry, defined by 283
os_session, defined by 371
os_template_formal_arg, defined by 403
os_transaction, defined by 411
os_typespec, defined by 441
get_namespace()
os_member_namespace, defined by 248
get_neutralized_classes()
os_mop, defined by 255
get_new_segment_reference_policy()
os_database, defined by 159
get_next()
530
os_address_space_marker, defined by 99
get_nt_registry_location()
os_authentication, defined by 109
get_null_illegal_pointers()
objectstore, defined by 69
os_cluster, defined by 132
os_database, defined by 159
os_segment, defined by 356
get_number()
os_cluster, defined by 133
os_segment, defined by 357
get_number_elements()
os_Fixup_dumper, defined by 225
get_number_of_elements()
os_array_type, defined by 108
get_object_range()
objectstore, defined by 69
get_object_to_fix()
os_Fixup_dumper, defined by 225
get_offset()
os_base_class, defined by 116
os_Dumper_reference, defined by 208
os_field_member_variable, defined by 224
os_member_variable, defined by 250
get_online_server_hostname()
os_failover_server, defined by 222
get_open_database()
os_reference_internal, defined by 302
os_soft_pointer32_base, defined by 374
os_soft_pointer64_base, defined by 378
get_open_mode()
os_database, defined by 160
get_original_location()
os_Type_info, defined by 432
get_os_deadlock_exception()
tix_exception, defined by 454
get_os_int16()
os_typespec, defined by 441
get_os_int64()
os_typespec, defined by 441
get_os_int32()
os_typespec, defined by 441
get_os_lock_timeout_exception()
tix_exception, defined by 454
get_os_signed_int8()
os_typespec, defined by 442
get_os_typespec()
defined by user-defined class 440
C++ A P I Reference
Index
os_Reference<T>, defined by 293
os_Reference_cross_session<T>, defined
by 295
os_Reference_protected<T>, defined by 304
get_os_unsigned_int16()
os_typespec, defined by 442
get_os_unsigned_int32()
os_typespec, defined by 442
get_os_unsigned_int64()
os_typespec, defined by 442
get_os_unsigned_int8()
os_typespec, defined by 442
get_page_size()
objectstore, defined by 70
get_parent()
os_transaction, defined by 411
get_path_to()
os_database, defined by 160
get_path_to_member()
os_schema_evolution, defined by 340
get_pathname()
os_database, defined by 160
get_permission()
os_rawfs_entry, defined by 283
get_pids()
os_deadlock_exception, defined by 204
os_lock_timeout_exception, defined by 239
get_pointer()
os_typespec, defined by 443
get_pointer_literal()
os_literal, defined by 236
get_pointer_numbers()
objectstore, defined by 70
get_pragmas()
os_class_type, defined by 125
os_enum_type, defined by 215
get_previous()
os_address_space_marker, defined by 99
get_primary_group()
os_segment_access, defined by 362
get_propagate_on_commit()
objectstore, defined by 70
get_reconnect_retry_interval()
os_failover_server, defined by 222
get_reconnect_timeout()
os_failover_server, defined by 222
get_related_class()
os_relationship_member_variable, defined
Release 6.3
by 311
get_related_member()
os_relationship_member_variable, defined
by 311
get_replacing_database()
os_Type_info, defined by 432
get_replacing_location()
os_Type_info, defined by 432
get_replacing_segment()
os_Type_info, defined by 432
get_replica_ID()
os_replicator_statistic_info, defined
by 322
get_report()
tix_handler, defined by 456
get_report0()
tix_handler, defined by 456
get_required_DLL_identifiers()
os_database, defined by 160
get_retain_persistent_addresses()
objectstore, defined by 71
get_return_type()
os_function_type, defined by 228
get_root()
os_path_to_data, defined by 271
get_schema_database()
os_database, defined by 161
os_schema_handle, defined by 348
get_schema_database_pathname()
os_schema_handle, defined by 348
os_schema_info, defined by 350
get_schema_info()
os_schema_handle, defined by 348
get_scope()
os_transaction, defined by 411
get_sector_size()
os_database, defined by 161
os_dbutil, defined by 183
get_segment()
os_database, defined by 161
os_Dumper_reference, defined by 208
get_segment_number()
os_Dumper_reference, defined by 208
get_segments()
os_database, defined by 161
get_server_host()
os_rawfs_entry, defined by 284
get_short()
531
G
os_typespec, defined by 443
get_signed_char()
os_typespec, defined by 443
get_signed_int()
os_typespec, defined by 443
get_signed_integral_value()
os_literal, defined by 236
get_signed_long()
os_typespec, defined by 443
get_signed_short()
os_typespec, defined by 443
get_simple_auth_ui()
objectstore, defined by 71
get_size()
os_base_class, defined by 117
os_field_member_variable, defined by 224
os_member_variable, defined by 250
os_type, defined by 420
get_size_as_base()
os_class_type, defined by 125
get_source_cluster()
os_untranslatable_pointer_handler, defined
by 448
get_source_offset()
os_untranslatable_pointer_handler, defined
by 448
get_source_path()
os_untranslatable_pointer_handler, defined
by 448
get_source_position()
os_class_type, defined by 125
os_enum_type, defined by 216
os_member_function, defined by 245
os_member_variable, defined by 251
os_named_indirect_type, defined by 257
get_specialization_name()
os_Dumper_specialization, defined by 211
get_statistics()
os_replicator, defined by 316
get_status()
os_archiver, defined by 104
os_backup, defined by 110
os_recover, defined by 287
os_restore, defined by 323
os_schema_handle, defined by 348
get_storage_class()
os_member_variable, defined by 251
get_string()
532
os_Dumper_reference, defined by 208
os_notification, defined by 261
os_pragma, defined by 282
os_type, defined by 420
get_suppress_invalid_hard_pointer_errors()
objectstore, defined by 71
get_target_class()
os_pointer_to_member_type, defined by 280
get_target_cluster()
os_untranslatable_pointer_handler, defined
by 448
get_target_export_id()
os_untranslatable_pointer_handler, defined
by 449
get_target_exported()
os_untranslatable_pointer_handler, defined
by 449
get_target_offset()
os_untranslatable_pointer_handler, defined
by 449
get_target_path()
os_untranslatable_pointer_handler, defined
by 449
get_target_segment()
os_untranslatable_pointer_handler, defined
by 449
get_target_type()
os_anonymous_indirect_type, defined by 101
os_indirect_type, defined by 229
os_pointer_type, defined by 281
get_template()
os_template_instantiation, defined by 405
get_thread_absorption()
os_session, defined by 371
get_total_number_of_elements()
os_path_to_data, defined by 272
get_transaction_max_retries()
objectstore, defined by 71
get_transaction_priority()
objectstore, defined by 71
get_transient_cluster()
os_cluster, defined by 133
get_transient_database()
os_database, defined by 161
get_transient_delete_function()
objectstore, defined by 72
get_transient_schema()
os_mop, defined by 256
C++ A P I Reference
Index
get_transient_segment()
os_segment, defined by 357
get_type()
os_Fixup_dumper, defined by 226
os_literal, defined by 236
os_member_function, defined by 245
os_member_type, defined by 249
os_member_variable, defined by 251
os_pointer_literal, defined by 279
os_rawfs_entry, defined by 284
os_template_value_formal, defined by 408
os_transaction, defined by 411
os_Type_info, defined by 433
os_type_template, defined by 436
os_type_template_actual_arg, defined by 437
os_typed_pointer_void, defined by 439
get_typespec()
os_database_root, defined by 172
get_unevolved_schema()
os_schema_evolution, defined by 341
get_union_variant()
objectstore, defined by 72
get_unsigned_char()
os_typespec, defined by 444
get_unsigned_int()
os_typespec, defined by 444
get_unsigned_integral_value()
os_literal, defined by 236
get_unsigned_long()
os_typespec, defined by 444
get_unsigned_short()
os_typespec, defined by 444
get_user_name()
os_rawfs_entry, defined by 284
get_value()
os_database_root, defined by 172
os_enumerator_literal, defined by 217
os_export_id, defined by 219
tix_handler, defined by 456
get_virtual_base_class_pointer_offset()
os_base_class, defined by 117
get_wchar_t_value()
os_literal, defined by 236
get_work_database()
os_schema_evolution, defined by 341
global functions
operator delete() 458
operator new() 459
Release 6.3
os_fetch() 461
os_fetch_address() 464
os_store() 465
H
handle_xxx()
os_untranslatable_pointer_handler, defined
by 450
handling TIX exceptions 469
has_affiliation_to()
os_database, defined by 162
has_array_components()
os_path_to_data, defined by 272
has_constructor()
os_class_type, defined by 126
has_destructor()
os_class_type, defined by 126
has_dispatch_table()
os_class_type, defined by 126
has_dispatch_table_other_compiler()
os_class_type, defined by 126
has_exception()
basic_undo, defined by 52
hash()
os_reference_internal, defined by 302
os_reference_protected_internal, defined
by 307
os_soft_pointer32_base, defined by 374
os_soft_pointer64_base, defined by 378
hostof()
os_dbutil, defined by 183
I
ignore_locator_file()
objectstore, defined by 72
illegal pointers 44
initial segment
returning 156
setting 168
initialize()
objectstore, defined by 72
os_compact, defined by 143
os_dbutil, defined by 183
os_mop, defined by 256
os_schema_evolution, defined by 341
initialize_for_sessions()
objectstore, defined by 73
533
I
initialize_object_metadata()
os_mop, defined by 256
insert()
os_Database_table, defined by 176
os_dynamic_extent, defined by 213
insert_required_DLL_identifier()
os_database, defined by 162
insert_required_DLL_identifiers()
os_database, defined by 162
os_schema_handle, defined by 349
install()
os_database_schema, defined by 175
install_backrest_control_c_handler()
os_dbutil, defined by 183
Instantiated_class
os_type, defined by 420
Integer
os_type, defined by 420
integrity control 44
introduces_virtual_functions()
os_class_type, defined by 126
is_aborted()
os_transaction, defined by 411
is_abstract()
os_class_type, defined by 126
is_base_path()
os_path_to_data, defined by 272
is_class_type()
os_type, defined by 420
is_committed()
os_transaction, defined by 412
is_const()
os_anonymous_indirect_type, defined by 101
os_member_function, defined by 245
os_type, defined by 420
is_damaged_dope_repair_enabled()
objectstore, defined by 75
is_db()
os_rawfs_entry, defined by 284
is_deleted()
os_cluster, defined by 133
os_segment, defined by 357
is_dir()
os_rawfs_entry, defined by 284
is_DLL_schema_enabled()
objectstore, defined by 75
is_empty()
os_cluster, defined by 133
534
os_segment, defined by 357
is_failover()
os_server, defined by 369
is_field()
os_member_variable, defined by 251
is_forward_definition()
os_class_type, defined by 126
is_ignored()
os_Database_table, defined by 177
is_indirect_type()
os_type, defined by 420
is_inline()
os_member_function, defined by 245
is_integral_type()
os_type, defined by 420
is_link()
os_rawfs_entry, defined by 284
is_lock_contention()
os_transaction, defined by 412
is_member_variable_path()
os_path_to_data, defined by 272
is_multiple_session_mode()
objectstore, defined by 75
is_null()
os_export_id, defined by 219
os_string, defined by 394
is_open()
os_database, defined by 162
is_open_multi_db_mvcc()
os_database, defined by 162
is_open_mvcc()
os_database, defined by 163
is_open_read_only()
os_database, defined by 163
is_open_single_db_mvcc()
os_database, defined by 163
is_open_update()
os_database, defined by 163
is_overloaded()
os_member_function, defined by 245
is_persistent()
objectstore, defined by 75
os_class_type, defined by 126
os_member_variable, defined by 251
is_pointer_type()
os_type, defined by 421
is_prepared()
os_transaction, defined by 412
C++ A P I Reference
Index
is_PTOM()
os_untranslatable_pointer_handler, defined
by 450
is_pure_virtual()
os_member_function, defined by 245
is_real_type()
os_type, defined by 421
is_recognized()
os_pragma, defined by 282
is_signed()
os_integral_type, defined by 233
is_single_session_mode()
objectstore, defined by 75
is_static()
os_member_function, defined by 245
os_member_variable, defined by 251
is_template_class()
os_class_type, defined by 126
is_transient_cluster()
os_cluster, defined by 133
is_transient_database()
os_database, defined by 163
is_transient_segment()
os_segment, defined by 357
is_unassigned_contiguous_address_space()
objectstore, defined by 76
is_unspecified()
os_member, defined by 241
os_template, defined by 399
os_type, defined by 421
is_valid()
os_Dumper_reference, defined by 209
is_virtual()
os_base_class, defined by 117
os_member_function, defined by 246
is_volatile()
os_anonymous_indirect_type, defined by 101
os_member_function, defined by 246
os_type, defined by 421
K
Known
os_function_type, defined by 227
L
list_directory()
os_dbutil, defined by 184
Release 6.3
load()
os_reference_cross_session, defined by 298
os_reference_internal, defined by 302
os_reference_protected_internal, defined
by 307
os_soft_pointer32_base, defined by 374
os_soft_pointer64_base, defined by 378
os_Type_fixup_loader, defined by 431
os_Type_loader, defined by 435
load_DLL()
objectstore, defined by 76
os_DLL_finder, defined by 205
local_path()
os_path_to_data, defined by 272
lock_as_used
objectstore, defined by 76
lock_cluster_read
objectstore, defined by 77
lock_cluster_write
objectstore, defined by 77
lock_database_read
objectstore, defined by 77
lock_database_write
objectstore, defined by 77
lock_page_write
objectstore, defined by 78
lock_segment_read
objectstore, defined by 78
lock_segment_write
objectstore, defined by 78
Long_double
os_type, defined by 421
lookup()
os_database, defined by 163
lookup_DLL_symbol()
objectstore, defined by 78
M
macros, system-supplied 469
collections facility macros 469
DECLARE_EXCEPTION() 471
DEFINE_EXCEPTION() 472
OS_BEGIN_TXN() 474
OS_BEGIN_TXN_NAMED() 478
OS_END_FAULT_HANDLER 479
OS_END_TXN() 480
OS_ESTABLISH_FAULT_HANDLER 481
OS_MARK_SCHEMA_TYPE() 482
535
N
OS_MARK_SCHEMA_TYPESPEC() 483
OS_REFERENCE_NOCLASS() 484
OS_REFERENCE_PROTECTED_NOCLASS() 485
OS_REPORT_DLL_LOAD_AND_UNLOAD() 486
OS_SCHEMA_DLL_ID() 487
OS_SCHEMA_INFO_NAME() 488
os_soft_pointer 489
OS_SOFT_POINTER32_NOCLASS() 490
OS_SOFT_POINTER64_NOCLASS() 491
TIX_END_HANDLE 492
TIX_EXCEPTION 493
TIX_HANDLE() 494
TIX_HANDLE_IF() 497
make()
os_path_to_data, defined by 272
make_link()
os_dbutil, defined by 184
-make_reachable_source_classes_persistent
option to ossg
OS_MARK_SCHEMA_TYPESPEC(), the macro 483
MAX_REGISTRY_STRING_LENGTH
os_authentication::get_nt_registry_
location() 109
os_authentication::set_nt_registry_
location() 109
metaobject protocol 45
exceptions 509
metatypes 45
minor_subscript()
os_path_to_data, defined by 272
mkdir()
os_dbutil, defined by 185
more()
os_object_cursor, defined by 268
multiversion concurrency control 45
multidatabase 165
open_multi_db_mvcc() 165
open_mvcc() 166
single-database 166
MVCC
See multiversion concurrency control
N
name()
os_path_to_data, defined by 272
Named_indirect
os_type, defined by 421
Namespace
536
os_member, defined by 241
nested TIX exception handlers 494
nested transactions 475
network_servers_available()
objectstore, defined by 79
new, the operator 458
next()
os_cluster_cursor, defined by 138
os_export_id_cursor, defined by 220
os_object_cursor, defined by 268
os_segment_cursor, defined by 365
no_access
os_segment_access, defined by 362
notify_immediate()
os_notification, defined by 261
notify_on_commit()
os_notification, defined by 262
number_of_blockers()
os_deadlock_exception, defined by 204
os_lock_timeout_exception, defined by 239
O
ObjectStore exceptions
See exceptions
objectstore, the class 54
acquire_address_space() 54
acquire_lock() 54
add_missing_dispatch_table_handler() 57
change_type() 58
clear_persistent_to_transient_
pointers() 58
embedded_server_available() 59
enable_damaged_dope_repair() 59
enable_DLL_schema() 60
export_object() 60
find_DLL_schema() 61
free_memory() 61
get_address_space_generation_number() 62
get_all_servers() 62
get_always_check_server_connection_at_
commit() 63
get_application_schema_pathname() 64
get_as_intervals() 64
get_asmarkers_useless() 64
get_auto_open_mode() 64
get_autoload_DLLs_function() 64
get_cache_file() 65
get_cache_size() 65
C++ A P I Reference
Index
get_client_name() 65
get_decache_soft_pointers_after_address_
space_release() 65
get_default_partition_size() 65
get_export_id() 66
get_incremental_schema_installation() 67
get_locator_file() 67
get_lock_status() 68
get_lock_timeout() 68
get_log_file() 69
get_n_servers() 69
get_null_illegal_pointers() 69
get_object_range() 69
get_page_size() 70
get_pointer_numbers() 70
get_propagate_on_commit() 70
get_retain_persistent_addresses() 71
get_simple_auth_ui() 71
get_suppress_invalid_hard_pointer_
errors() 71
get_transaction_priority() 71
get_transient_delete_function() 72
get_union_variant() 72
ignore_locator_file() 72
initialize() 72
initialize_for_sessions() 73
is_damaged_dope_repair_enabled() 75
is_DLL_schema_enabled() 75
is_multiple_session_mode() 75
is_persistent() 75
is_single_session_mode() 75
is_unassigned_contiguous_address_
space() 76
load_DLL() 76
lock_as_used 76
lock_cluster_read 77
lock_cluster_write 77
lock_database_read 77
lock_database_write 77
lock_page_write 78
lock_segment_read 78
lock_segment_write 78
lookup_DLL_symbol() 78
network_servers_available() 79
own_page_write 79
propagate_log() 79
release_cleared_persistent_to_transient_
pointers() 79
Release 6.3
release_maintenance() 80
release_major() 80
release_minor() 80
release_name() 81
release_persistent_addresses() 81
reset_persistent_addresses() 81
retain_persistent_addresses() 81
return_all_pages() 81
return_memory() 81
set_allocation_strategy() 82
set_always_check_server_connection_at_
commit() 82
set_always_null_illegal_pointers() 83
set_application_schema_pathname() 83
set_asmarkers_useless() 83
set_auto_open_mode() 83
set_autoload_DLLs_function() 83
set_cache_file() 85
set_cache_size() 85
set_client_name() 85
set_current_schema_key() 86
set_decache_soft_pointers_after_address_
space_release() 86
set_default_address_space_partition_
size() 87
set_fetch_policy() 87
set_handle_transient_faults() 88
set_incremental_schema_installation() 88
set_locator_file() 88
set_lock_option() 88
set_lock_timeout() 89
set_log_file() 89
set_null_illegal_pointers() 90
set_pathname_encoding() 90
set_persistent_to_transient_pointer() 90
set_propagate_on_commit() 91
set_reserve_as_mode() 91
set_retain_persistent_addresses() 91
set_simple_auth_ui() 92
set_suppress_invalid_hard_pointer_
errors() 92
set_transaction_max_retries() 92
set_transaction_priority() 92
set_transient_delete_function() 93
set_union_variant() 94
shutdown() 94
unload_DLL() 94
which_product() 94
537
O
objectstore_exception, the class 96
signal() 96
vsignal() 96
of()
os_address_space_marker, defined by 99
os_cluster, defined by 133
os_database, defined by 163
os_segment, defined by 357
os_session, defined by 371
open()
os_database, defined by 164
open_multi_db_mvcc()
os_database, defined by 165
open_mvcc()
os_database, defined by 165
operator !()
os_Dumper_reference, defined by 210
os_Reference<T>, defined by 294
os_reference_cross_session, defined by 298
os_reference_internal, defined by 302
os_reference_protected_internal, defined
by 307
os_soft_pointer32_base, defined by 375
os_soft_pointer64_base, defined by 379
operator !=()
os_Dumper_reference, defined by 209
os_reference_cross_session, defined by 298
os_reference_internal, defined by 302
os_reference_protected_internal, defined
by 307
os_soft_pointer32_base, defined by 375
os_soft_pointer64_base, defined by 379
operator ()()
os_Dumper_specialization, defined by 211
os_Planning_action, defined by 278
os_Type_fixup_loader, defined by 431
os_Type_loader, defined by 435
operator <()
os_Dumper_reference, defined by 209
os_reference_cross_session, defined by 299
os_reference_internal, defined by 302
os_reference_protected_internal, defined
by 308
os_soft_pointer32_base, defined by 375
os_soft_pointer64_base, defined by 379
operator <=()
os_Dumper_reference, defined by 210
os_reference_cross_session, defined by 299
538
os_reference_internal, defined by 303
os_reference_protected_internal, defined
by 308
os_soft_pointer32_base, defined by 376
os_soft_pointer64_base, defined by 380
operator =()
os_Dumper_reference, defined by 209
os_rawfs_entry, defined by 284
os_Reference<T>, defined by 294
os_reference_cross_session, defined by 298
os_Reference_cross_session<T>, defined
by 295
os_Reference_protected<T>, defined by 304
os_segment_access, defined by 363
os_soft_pointer32<T>, defined by 382
os_soft_pointer64<T>, defined by 385
os_string, defined by 394
operator ==()
os_Dumper_reference, defined by 209
os_export_id, defined by 219
os_reference_cross_session, defined by 298
os_reference_internal, defined by 302
os_reference_protected_internal, defined
by 307
os_soft_pointer32_base, defined by 375
os_soft_pointer64_base, defined by 379
os_typespec, defined by 444
operator ->()
os_Reference<T>, defined by 294
os_Reference_cross_session<T>, defined
by 296
os_Reference_protected<T>, defined by 305
os_soft_pointer32<T>, defined by 382
os_soft_pointer64<T>, defined by 385
operator >()
os_Dumper_reference, defined by 209
os_reference_cross_session, defined by 299
os_reference_internal, defined by 303
os_reference_protected_internal, defined
by 308
os_soft_pointer32_base, defined by 375
os_soft_pointer64_base, defined by 379
operator >=()
os_Dumper_reference, defined by 210
os_reference_cross_session, defined by 299
os_reference_internal, defined by 303
os_reference_protected_internal, defined
by 308
C++ A P I Reference
Index
os_soft_pointer32_base, defined by 376
os_soft_pointer64_base, defined by 380
operator const char*()
os_string, defined by 394
operator const os_access_modifier&()
os_member, defined by 241
operator const os_anonymous_indirect_
type&()
os_type, defined by 421
operator const os_app_schema&()
os_schema, defined by 330
operator const os_array_type&()
os_type, defined by 422
operator const os_class_type&()
os_type, defined by 422
operator const os_comp_schema&()
os_schema, defined by 330
operator const os_database_schema&()
os_schema, defined by 331
operator const os_enum_type&()
os_type, defined by 422
operator const os_field_member_variable&()
os_member, defined by 241
os_member_variable, defined by 252
operator const os_function_type&()
os_type, defined by 422
operator const os_instantiated_class_
type&()
os_type, defined by 422
operator const os_integral_type&()
os_type, defined by 422
operator const os_literal_template_actual_
arg&()
os_template_actual_arg, defined by 401
operator const os_member_function&()
os_member, defined by 241
operator const os_member_type&()
os_member, defined by 241
operator const os_member_variable&()
os_member, defined by 241
operator const os_named_indirect_type&()
os_type, defined by 422
operator const os_pointer_to_member_type&()
os_type, defined by 422
operator const os_pointer_type&()
os_type, defined by 423
operator const os_real_type&()
os_type, defined by 423
Release 6.3
operator const os_reference_type&()
os_type, defined by 423
operator const os_relationship_member_
variable&()
os_member, defined by 242
os_member_variable, defined by 252
operator const os_template_type_formal&()
os_template_formal_arg, defined by 403
operator const os_template_value_formal&()
os_template_formal_arg, defined by 403
operator const os_type_template&()
os_template, defined by 399
operator const os_type_template_actual_
arg&()
os_template_actual_arg, defined by 401
operator const os_type_type&()
os_type, defined by 423
operator const os_void_type&()
os_type, defined by 423
operator delete()
os_session, defined by 371
operator delete(), the global function 458
operator new(), the global function 459
operator os_access_modifier&()
os_member, defined by 242
operator os_anonymous_indirect_type&()
os_type, defined by 423
operator os_app_schema&()
os_schema, defined by 331
operator os_array_type&()
os_type, defined by 423
operator os_class_type&()
os_type, defined by 423
operator os_comp_schema&()
os_schema, defined by 331
operator os_database_schema&()
os_schema, defined by 331
operator os_enum_type&()
os_type, defined by 424
operator os_field_member_variable&()
os_member, defined by 242
os_member_variable, defined by 252
operator os_function_type&()
os_type, defined by 424
operator os_instantiated_class_type&()
os_class_type, defined by 127
os_type, defined by 424
operator os_integral_type&()
539
O
os_type, defined by 424
operator os_literal_template_actual_arg&()
os_template_actual_arg, defined by 401
operator os_member_function&()
os_member, defined by 242
operator os_member_type&()
os_member, defined by 242
operator os_member_variable&()
os_member, defined by 242
operator os_named_indirect_type&()
os_type, defined by 424
operator os_pointer_to_member_type&()
os_type, defined by 424
operator os_pointer_type&()
os_type, defined by 424
operator os_real_type&()
os_type, defined by 424
operator os_reference_type&()
os_type, defined by 425
operator os_relationship_member_variable&()
os_member, defined by 242
os_member_variable, defined by 252
operator os_template_type_formal&()
os_template_formal_arg, defined by 403
operator os_template_value_formal&()
os_template_formal_arg, defined by 403
operator os_type_template&()
os_template, defined by 400
operator os_type_template_actual_arg&()
os_template_actual_arg, defined by 402
operator os_type_type&()
os_type, defined by 425
operator os_void_type&()
os_type, defined by 425
operator T*()
os_Reference<T>, defined by 294
os_Reference_cross_session<T>, defined
by 295
os_Reference_protected<T>, defined by 305
os_soft_pointer32<T>, defined by 382
os_soft_pointer64<T>, defined by 385
operator void*()
os_Dumper_reference, defined by 209
os_typed_pointer_void, defined by 439
os_access_modifier, the class 97
create() 97
get_base_member() 97
set_base_member() 97
540
~os_address_space_marker()
os_address_space_marker, defined by 100
os_address_space_marker()
os_address_space_marker, defined by 99
os_address_space_marker, the class 98
get_current() 99
get_level() 99
get_next() 99
get_previous() 99
of() 99
~os_address_space_marker() 100
os_address_space_marker() 99
release() 99
retain() 100
os_allocation_strategy_least_space
enumerator 63
os_allocation_strategy_least_wait
enumerator 63
os_anonymous_indirect_type, the class 101
create() 101
get_target_type() 101
is_const() 101
is_volatile() 101
set_is_const() 101
set_is_volatile() 101
os_app_schema, the class 102
get() 102
os_application_schema_info, the class 103
os_archiver()
os_archiver, defined by 104
os_archiver, the class 104
~os_archiver() 104
add_db_to_archive() 104
change_time_interval() 104
get_current_archive_file_name() 104
get_status() 104
os_archiver() 104
remove_db_from_archive() 105
start_archiver() 105
stop_archiver() 105
take_a_snapshot() 105
os_archiver_options()
os_archiver_options, defined by 107
os_archiver_options, the class 106
~os_archiver_options() 107
os_archiver_options() 107
reset() 107
os_array_type, the class 108
C++ A P I Reference
Index
create() 108
get_element_type() 108
get_number_of_elements() 108
set_element_type() 108
set_number_of_elements() 108
os_authentication, the class 109
get_nt_registry_location() 109
os_backup()
os_backup, defined by 110
os_backup, the class 110
~os_backup() 110
get_status() 110
os_backup() 110
start_and_run_backup() 110
start_backup() 111
stop_backup() 111
os_backup_options()
os_backup_options, defined by 115
os_backup_options, the class 112
~os_backup_options() 115
os_backup_options() 115
reset() 115
os_base_class, the class 116
create() 116
get_access() 116
get_class() 116
get_offset() 116
get_size() 117
get_virtual_base_class_pointer_
offset() 117
is_virtual() 117
Private 117
Protected 117
Public 117
set_access() 117
set_class() 117
set_offset() 118
set_virtual_base_class_no_pointer() 118
set_virtual_base_class_pointer_
offset() 118
set_virtuals_redefined() 118
virtual_base_class_has_pointer() 118
virtuals_redefined() 118
OS_BEGIN_TXN(), the macro 474
OS_BEGIN_TXN_NAMED(), the macro 478
os_boolean 47
OS_CACHE_FILE environment variable
objectstore::set_cache_file 85
Release 6.3
os_class_type, the class 119
Anonymous_union 119
Class 119
create() 119
declares_get_os_typespec_function() 120
defines_virtual_functions() 120
find_base_class() 120
find_member_variable() 120
get_access_of_get_os_typespec_
function() 121
get_allocated_virtual_base_classes() 121
get_base_classes() 121
get_class_kind() 122
get_dispatch_table_pointer_offset() 122
get_dispatch_table_pointer_offset_other_
compiler() 122
get_indirect_virtual_base_classes() 122
get_members() 123
get_most_derived_class() 123
get_name() 125
get_pragmas() 125
get_size_as_base() 125
get_source_position() 125
has_constructor() 126
has_destructor() 126
has_dispatch_table() 126
has_dispatch_table_other_compiler() 126
introduces_virtual_functions() 126
is_abstract() 126
is_forward_definition() 126
is_persistent() 126
is_template_class() 126
operator os_instantiated_class_
type&() 127
set_access_of_get_os_typespec_
function() 127
set_base_classes() 127
set_class_kind() 127
set_declares_get_os_typespec_
function() 127
set_defines_virtual_functions() 127
set_dispatch_table_pointer_offset() 128
set_has_constructor() 128
set_has_destructor() 128
set_indirect_virtual_base_classes() 128
set_introduces_virtual_functions() 128
set_is_abstract() 128
set_is_forward_definition() 128
541
O
set_is_persistent() 128
set_members() 128
set_name() 129
set_pragmas() 129
set_source_position() 129
Union 129
os_class_typeStruct 129
os_close_database, the class 130
os_cluster, the class 131
database_of() 131
destroy() 131
get_allocation_strategy() 131
get_fetch_policy() 131
get_lock_option() 132
get_null_illegal_pointers() 132
get_number() 133
get_transient_cluster() 133
is_deleted() 133
is_empty() 133
is_transient_cluster() 133
of() 133
release_pointer() 133
retain_pointer() 134
return_memory() 134
segment_of() 134
session_of() 134
set_allocation_strategy() 135
set_fetch_policy() 135
set_lock_option() 135
set_null_illegal_pointers() 136
set_size() 136
size() 137
with() 137
os_cluster_cursor()
os_cluster, defined by 138
os_cluster_cursor, the class 138
get_current() 138
next() 138
os_cluster_cursor() 138
reset() 139
os_cluster_with, the class 140
get() 140
os_comp_schema, the class 147
get() 147
os_compact, the class 141
augment_cluster_split_avoidance() 141
augment_post_compact_transformers() 141
compact() 142
542
initialize() 143
set_address_space_release_interval() 144
set_avoid_page_boundary() 144
set_explanation_level() 144
set_malloc_size() 145
set_maplet_size() 145
set_maximum_cluster_size() 145
set_maximum_memory_size() 145
shutdown() 146
os_database, the class 148
affiliate() 148
change_affiliation() 149
change_schema_key() 149
close() 150
create() 150
create_root() 152
create_segment() 152
destroy() 153
find_root() 153
freeze_schema_key() 153
get_affiliated_databases() 154
get_affiliation_index_of() 154
get_all_databases() 154
get_all_roots() 155
get_all_segments() 155
get_all_segments_and_permissions() 155
get_allocation_strategy() 156
get_application_info() 156
get_default_segment() 156
get_fetch_policy() 156
get_file_host_name() 157
get_fragmentation() 157
get_host_name() 158
get_incremental_schema_
installation() 158
get_lock_option() 158
get_n_databases() 159
get_n_roots() 159
get_n_segments() 159
get_new_segment_reference_policy() 159
get_null_illegal_pointers() 159
get_open_mode() 160
get_path_to() 160
get_pathname() 160
get_required_DLL_identifiers() 160
get_schema_database() 161
get_sector_size() 161
get_segment() 161
C++ A P I Reference
Index
get_segments() 161
get_transient_database() 161
has_affiliation_to() 162
insert_required_DLL_identifier() 162
insert_required_DLL_identifiers() 162
is_open() 162
is_open_multi_db_mvcc() 162
is_open_mvcc() 163
is_open_read_only() 163
is_open_single_db_mvcc() 163
is_open_update() 163
is_transient_database() 163
lookup() 163
of() 163
open() 164
open_multi_db_mvcc() 165
open_mvcc() 165
release_pointer() 166
remove_required_DLL_identifier() 167
retain_pointer() 167
return_memory() 167
session_of() 167
set_allocation_strategy() 168
set_application_info() 168
set_default_segment() 168
set_fetch_policy() 169
set_incremental_schema_
installation() 169
set_lock_option() 169
set_new_segment_reference_policy() 170
set_null_illegal_pointers() 170
set_schema_database() 170
set_size() 170
set_size_in_sectors() 171
size() 171
size_in_sectors() 171
time_created() 171
~os_database_root()
os_database_root, defined by 174
os_database_root, the class 172
destroy() 172
find() 172
get_name() 172
get_typespec() 172
get_value() 172
~os_database_root() 174
release_pointer() 173
retain_pointer() 173
Release 6.3
set_value() 174
os_database_schema, the class 175
get() 175
get_for_update() 175
install() 175
os_Database_table, the class 176
find_reference() 176
get() 176
insert() 176
is_ignored() 177
os_dbcontrol_options, the class
argument to osdbcontrol() 185
os_dbutil, the class 178
chgrp() 178
chmod() 178
chown() 178
close_all_connections() 179
close_all_server_connections() 179
close_server_connection() 179
cmgr_remove_file() 179
cmgr_shutdown() 179
cmgr_stat() 179
compare_schemas() 181
copy_database() 182
disk_free() 182
expand_global() 182
file_db_pathname() 183
get_client_name() 183
get_sector_size() 183
hostof() 183
initialize() 183
install_backrest_control_c_handler() 183
list_directory() 184
make_link() 184
mkdir() 185
ossize() 186
osverifydb() 187
osverifydb_one_segment() 188
rehost_all_links() 189
rehost_link() 189
remove() 190
rename() 190
rmdir() 190
set_application_schema_path() 190
set_client_name() 191
split_pathname() 191
start_backrest_logging() 191
stat() 192
543
O
stop_backrest_logging() 192
svr_checkpoint() 192
svr_client_kill() 192
svr_debug() 193
svr_machine() 193
svr_ping() 194
svr_shutdown() 194
svr_stat() 194
os_deadlock_exception, the class 203
get_application_names() 203
get_fault_addr() 204
get_hostnames() 204
get_lock_type() 204
get_pids() 204
number_of_blockers() 204
OS_DEF_EXCEPT_ACTION environment variable
objectstore_exception::signal() 96
objectstore_exception::vsignal() 96
os_DLL_finder, the class 205
equal_DLL_identifiers() 205
equal_DLL_identifiers_same_prefix() 205
get() 205
load_DLL() 205
register_() 205
unregister() 205
os_DLL_schema_info, the class 206
add_DLL_identifier() 206
DLL_loaded() 206
DLL_unloaded() 207
os_Dumper_reference()
os_Dumper_reference, defined by 210
os_Dumper_reference, the class 208
get_database() 208
get_database_number() 208
get_offset() 208
get_segment() 208
get_segment_number() 208
get_string() 208
is_valid() 209
operator !() 210
operator !=() 209
operator <() 209
operator <=() 210
operator =() 209
operator ==() 209
operator >() 209
operator >=() 210
operator void*() 209
544
os_Dumper_reference() 210
resolve() 210
os_Dumper_specialization, the class 211
get_specialization_name() 211
operator ()() 211
should_use_default_constructor() 212
~os_dynamic_extent()
os_dynamic_extent, defined by 214
os_dynamic_extent()
os_dynamic_extent, defined by 213
os_dynamic_extent, the class 213
insert() 213
~os_dynamic_extent() 214
os_dynamic_extent() 213
remove() 214
OS_END_FAULT_HANDLER, the macro 479
OS_END_TXN(), the macro 480
os_enum_type, the class 215
create() 215
get_enumerator() 215
get_enumerators() 215
get_name() 215
get_pragmas() 215
get_source_position() 216
set_enumerators() 216
set_name() 216
set_pragmas() 216
set_source_position() 216
os_enumerator_literal, the class 217
create() 217
get_name() 217
get_value() 217
set_name() 217
set_value() 217
OS_ESTABLISH_FAULT_HANDLER, the macro 481
os_evolve_subtype_fun_binding()
os_evolve_subtype_fun_binding, defined
by 218
os_evolve_subtype_fun_binding, the class 218
os_evolve_subtype_fun_binding() 218
os_export_id, the class 219
get_value() 219
is_null() 219
operator ==() 219
~os_export_id_cursor()
os_export_id_cursor, defined by 221
os_export_id_cursor()
os_export_id_cursor, defined by 220
C++ A P I Reference
Index
os_export_id_cursor, the class 220
get_current() 220
next() 220
~os_export_id_cursor() 221
os_export_id_cursor() 220
reset() 221
os_failover_server, the class 222
get_logical_server_hostname() 222
get_online_server_hostname() 222
get_reconnect_retry_interval() 222
get_reconnect_timeout() 222
set_reconnect_timeout_and_interval() 223
os_fetch(), the global function 461
os_fetch_address(), the global function 464
os_fetch_cluster enumerator 67
os_fetch_page enumerator 67
os_fetch_stream enumerator 67
os_field_member_variable, the class 224
create() 224
get_offset() 224
get_size() 224
set_size() 224
~os_Fixup()
os_Fixup_dumper, defined by 226
os_Fixup_dumper()
os_Fixup_dumper, defined by 226
os_Fixup_dumper, the class 225
dump_info() 225
duplicate() 225
get_number_elements() 225
get_object_to_fix() 225
get_type() 226
~os_Fixup() 226
os_Fixup_dumper() 226
os_function_type, the class 227
create() 227
equal_signature() 227
get_arg_list() 227
get_arg_list_kind() 227
get_return_type() 228
Known 227
set_arg_list() 228
set_arg_list_kind() 228
set_return_type() 228
Unknown 227
Variable 227
os_indirect_type, the class 229
get_target_type() 229
Release 6.3
set_target_type() 229
os_instantiated_class_type, the class 230
create() 230
get_instantiation() 230
set_instantiation() 230
os_int64()
os_int64, defined by 231
os_int64, the class 231
get_high() 231
get_low() 231
os_int64() 231
sprint() 231
os_integral_type, the class 232
create() 232
create_defaulted_char() 232
create_int() 232
create_long() 232
create_short() 233
create_signed_char() 233
create_unsigned_char() 233
is_signed() 233
os_int16
typespec for 441
os_int64 47
typespec for 441
os_int32 47
typespec for 441
os_literal, the class 234
create_char() 234
create_enum_literal() 234
create_pointer_literal() 234
create_signed_char() 234
create_signed_int() 234
create_signed_long() 234
create_signed_short() 234
create_unsigned_char() 234
create_unsigned_int() 235
create_unsigned_long() 235
create_unsigned_short() 235
create_wchar_t() 235
get_char_value() 235
get_enum_literal() 235
get_kind() 235
get_pointer_literal() 236
get_signed_integral_value() 236
get_type() 236
get_unsigned_integral_value() 236
get_wchar_t_value() 236
545
O
os_literal_template_actual_arg, the class 237
create() 237
get_literal() 237
set_literal() 237
os_lock_timeout exception 89
os_lock_timeout_exception, the class 238
get_application_names() 238
get_fault_addr() 238
get_hostnames() 239
get_lock_type() 239
get_pids() 239
number_of_blockers() 239
OS_LOG_FILE environment variable
and objectstore::set_log_file() 89
OS_MARK_SCHEMA_TYPE(), the macro 482
OS_MARK_SCHEMA_TYPESPEC(), the macro 483
os_member, the class 240
Access_modifier 240
Field_variable 240
Function 240
get_access() 240
get_defining_class() 240
get_kind() 240
is_unspecified() 241
Namespace 241
operator const os_access_modifier&() 241
operator const os_field_member_
variable&() 241
operator const os_member_function&() 241
operator const os_member_type&() 241
operator const os_member_variable&() 241
operator const os_relationship_member_
variable&() 242
operator os_access_modifier&() 242
operator os_field_member_variable&() 242
operator os_member_function&() 242
operator os_member_type&() 242
operator os_member_variable&() 242
operator os_relationship_member_
variable&() 242
Private 242
Protected 243
Public 243
Relationship 243
set_access() 243
Type 243
Variable 243
os_member_function, the class 244
546
create() 244
get_call_linkage() 244
get_function_kind() 244
get_name() 245
get_source_position() 245
get_type() 245
is_const() 245
is_inline() 245
is_overloaded() 245
is_pure_virtual() 245
is_static() 245
is_virtual() 246
is_volatile() 246
set_call_linkage() 246
set_is_const() 246
set_is_inline() 246
set_is_overloaded() 246
set_is_pure_virtual() 246
set_is_static() 246
set_is_virtual() 247
set_is_volatile() 247
set_name() 247
set_source_position() 247
set_type() 247
os_member_namespace, the class 248
create() 248
get_namespace() 248
set_namespace() 248
os_member_type, the class 249
create() 249
get_type() 249
set_type() 249
os_member_variable, the class 250
create() 250
get_name() 250
get_offset() 250
get_size() 250
get_source_position() 251
get_storage_class() 251
get_type() 251
is_field() 251
is_persistent() 251
is_static() 251
operator const os_field_member_
variable&() 252
operator const os_relationship_member_
variable&() 252
operator os_field_member_variable&() 252
C++ A P I Reference
Index
operator os_relationship_member_
variable&() 252
Persistent 251
Regular 251
set_name() 252
set_offset() 252
set_source_position() 252
set_storage_class() 253
set_type() 253
Static 251
os_mop, the class 254
bind() 254
copy_classes() 255
current() 255
find_namespace() 255
find_type() 255
get_failure_classes() 255
get_neutralized_classes() 255
get_transient_schema() 256
initialize() 256
initialize_object_metadata() 256
reset() 256
os_named_indirect_type, the class 257
create() 257
get_name() 257
get_source_position() 257
set_name() 257
set_source_position() 257
os_namespace, the class 258
create() 258
get_enclosing_namespace() 258
get_members() 258
get_name() 258
set_enclosing_namespace() 258
set_members() 258
set_name() 259
os_notification()
os_notification, defined by 263
os_notification, the class 260
assign() 260
get_database() 260
_get_fd() 260
get_kind() 260
get_location() 261
get_string() 261
notify_immediate() 261
notify_on_commit() 262
os_notification() 263
Release 6.3
queue_status() 263
receive() 264
set_queue_size() 265
subscribe() 265
unsubscribe() 266
~os_object_cursor()
os_object_cursor, defined by 270
os_object_cursor()
os_object_cursor, defined by 269
os_object_cursor, the class 268
current() 268
first() 268
more() 268
next() 268
~os_object_cursor() 270
os_object_cursor() 269
release_address_space() 269
reset() 269
set() 270
os_path_to_data, the class 271
add() 271
bit_offset() 271
byte_offset() 271
get_root() 271
get_total_number_of_elements() 272
has_array_components() 272
is_base_path() 272
is_member_variable_path() 272
local_path() 272
make() 272
minor_subscript() 272
name() 272
outer_collocated_path() 273
outer_path() 273
pop() 273
to_bit_field() 273
to_dope() 273
to_static_member() 273
to_subscript() 273
type() 273
unique_name() 273
os_pathname_and_segment_number()
os_pathname_and_segment_number, defined
by 275
os_pathname_segment_cluster, defined by 276
os_pathname_and_segment_number, the class 275
database_pathname 275
os_pathname_and_segment_number() 275
547
O
segment_number 275
os_pathname_segment_cluster, the class 276
cluster_number 276
database_pathname 276
os_pathname_and_segment_number() 276
segment_number 276
os_persistent_to_transient_pointer_manager,
the class
release() 277
os_persistent_to_transient_pointer_manger,
the class 277
os_Planning_action, the class 278
operator ()() 278
os_pointer_literal, the class 279
create() 279
get_name() 279
get_type() 279
set_name() 279
set_type() 279
os_pointer_to_member_type, the class 280
create() 280
get_target_class() 280
set_target_class() 280
os_pointer_type, the class 281
create() 281
get_target_type() 281
set_target_type() 281
os_pragma, the class 282
create() 282
get_string() 282
is_recognized() 282
~os_rawfs_entry()
os_rawfs_entry, defined by 285
os_rawfs_entry()
os_rawfs_entry, defined by 284
os_rawfs_entry, the class 283
get_abs_path() 283
get_creation_time() 283
get_group_name() 283
get_link_host() 283
get_link_path() 283
get_n_sectors() 283
get_name() 283
get_permission() 283
get_server_host() 284
get_type() 284
get_user_name() 284
is_db() 284
548
is_dir() 284
is_link() 284
operator =() 284
~os_rawfs_entry() 285
os_rawfs_entry() 284
OSU_DATABASE 285
OSU_DIRECTORY 285
OSU_LINK 285
os_real_type, the class 286
create() 286
create_double() 286
create_float() 286
create_long_double() 286
os_recover()
os_recover, defined by 287
os_recover, the class
~os_recover() 287
get_status() 287
os_recover() 287
start_and_run_recover() 287
start_recover() 288
stop_recover() 288
os_recover_options()
os_recover_options, defined by 292
os_recover_options, the class 289
~os_recover_options() 292
os_recover_options() 292
reset() 292
os_Reference()
os_Reference<T>, defined by 294
os_Reference<T>, the class 293
get_os_typespec() 293
operator !() 294
operator =() 294
operator ->() 294
operator T*() 294
os_Reference() 294
resolve() 294
os_Reference_cross_session()
os_Reference_cross_session<T>, defined
by 296
~os_reference_cross_session()
os_reference_cross_session, defined by 299
os_reference_cross_session()
os_reference_cross_session, defined by 299
os_reference_cross_session, the class 297
dump() 298
get_database() 298
C++ A P I Reference
Index
load() 298
operator !() 298
operator !=() 298
operator <() 299
operator <=() 299
operator =() 298
operator ==() 298
operator >() 299
operator >=() 299
~os_reference_cross_session() 299
os_reference_cross_session() 299
resolve() 300
os_Reference_cross_session<T>, the class 295
get_os_typespec() 295
operator =() 295
operator ->() 296
operator T*() 295
os_Reference_cross_session() 296
resolve() 296
~os_reference_internal()
os_reference_internal, defined by 303
os_reference_internal, the class 301
dump() 301
get_database() 301
get_database_key() 301
get_open_database() 302
hash() 302
load() 302
operator !() 302
operator !=() 302
operator <() 302
operator <=() 303
operator ==() 302
operator >() 303
operator >=() 303
~os_reference_internal() 303
resolve() 303
OS_REFERENCE_NOCLASS(), the macro 484
os_Reference_protected()
os_Reference_protected<T>, defined by 305
os_Reference_protected<T>, the class 304
get_os_typespec() 304
operator =() 304
operator ->() 305
operator T*() 305
os_Reference_protected() 305
resolve() 305
~os_reference_protected_internal()
Release 6.3
os_reference_protected_internal, defined
by 308
os_reference_protected_internal, the class 306
dump() 306
get_database() 306
get_database_key() 307
hash() 307
load() 307
operator !() 307
operator !=() 307
operator <() 308
operator <=() 308
operator ==() 307
operator >() 308
operator >=() 308
~os_reference_protected_internal() 308
resolve() 309
OS_REFERENCE_PROTECTED_NOCLASS(), the
macro 485
os_reference_type, the class 310
create() 310
os_relationship_member_variable, the class 311
get_related_class() 311
get_related_member() 311
os_release_cluster_pointer, the class 312
os_release_database_pointer, the class 313
os_release_root_pointer, the class 314
os_release_segment_pointer, the class 315
~os_replicator()
os_replicator, defined by 316
os_replicator()
os_replicator, defined by 316
os_replicator, the class 316
change_time_interval() 316
get_statistics() 316
get_status() 317
os_replicator() 316
reset_statistics() 317
start_replicator() 317
stop_replicator() 317
~os_replicator_options()
os_replicator_options, defined by 320
os_replicator_options()
os_replicator_options, defined by 320
os_replicator_options, the class 318
os_replicator_options() 320
reset() 320
~os_replicator_statistic_info()
549
O
os_replicator_statistic_info, defined
by 322
os_replicator_statistic_info()
os_replicator_statistic_info, defined
by 321
os_replicator_statistic_info, the class
format_and_print_statistics() 322
format_statistics() 322
get_replica_ID() 322
os_replicator_statistic_info() 321
OS_REPORT_DLL_LOAD_AND_UNLOAD(), the
macro 486
os_restore()
os_restore, defined by 323
os_restore, the class 287, 323
~os_restore() 323
get_status() 323
os_restore() 323
start_and_run_restore() 324
start_restore() 324
stop_restore() 324
os_restore_options()
os_restore_options, defined by 328
os_restore_options, the class 325
~os_restore_options() 328
os_restore_options() 328
reset() 328
os_retain_address()
os_retain_address, defined by 329
os_retain_address, the class 329
os_retain_address() 329
release() 329
retaining() 329
set_retain() 329
os_schema, the class 330
Application_schema 330
Compilation_schema 330
Database_schema 330
find_type() 330
get_classes() 330
get_kind() 330
operator const os_app_schema&() 330
operator const os_comp_schema&() 330
operator const os_database_schema&() 331
operator os_app_schema&() 331
operator os_comp_schema&() 331
operator os_database_schema&() 331
OS_SCHEMA_DLL_ID(), the macro 487
550
os_schema_evolution, the class 332
augment_classes_to_be_recycled() 335
augment_classes_to_be_removed() 335
augment_cluster_split_avoidance() 335
augment_dll_schema_db_names() 335
augment_optional_classes() 336
augment_post_evol_transformers() 336
evolve() 337
get_enclosing_object() 340
get_evolved_schema() 340
get_evolved_schema_db_name() 340
get_explanation_level() 340
get_path_to_member() 340
get_unevolved_schema() 341
get_work_database() 341
initialize() 341
set_address_space_release_interval() 341
set_avoid_page_boundary() 341
set_disable_transformer_class_
checks() 342
set_evolved_schema_db_name() 342
set_explanation_level() 342
set_malloc_size() 343
set_maplet_size() 343
set_maximum_cluster_size() 145, 343
set_maximum_memory_size() 145, 343
set_obsolete_index_handler() 343
set_obsolete_query_handler() 343
set_optimzie_checkpoints() 345
set_pre_evolution_setup_hook() 345
set_resolve_ambiguous_void_
pointers() 345
set_task_list_file_name() 345
set_untranslatable_pointer_handler() 345
shutdown() 345
task_list() 346
os_schema_handle, the class 347
DLL_unloaded() 347
get() 347
get_all() 347
get_application_schema_handle() 348
get_DLL_identifiers() 348
get_schema_database() 348
get_schema_database_pathname() 348
get_schema_info() 348
get_status() 348
insert_required_DLL_identifiers() 349
set_schema_database_pathname() 349
C++ A P I Reference
Index
os_schema_handle_status, the enumerator 349
os_schema_info, the class 350
get() 350
get_DLL_identifiers() 350
get_schema_database_pathname() 350
set_schema_database_pathname() 350
OS_SCHEMA_INFO_NAME(), the macro 488
os_schema_install_options()
os_schema_install_options, defined by 351
os_schema_install_options, the class 351
get_copy_member_functions() 351
os_schema_install_options() 351
set_copy_member_functions() 351
os_segment, the class 352
create_cluster() 352
database_of() 352
destroy() 352
get_access_control() 352
get_all_clusters() 353
get_allocation_strategy() 353
get_application_info() 353
get_cluster() 353
get_clusters() 354
get_comment() 354
get_default_cluster() 354
get_export_ids() 355
get_fetch_policy() 355
get_lock_option() 356
get_n_clusters() 356
get_null_illegal_pointers() 356
get_number() 357
get_transient_segment() 357
is_deleted() 357
is_empty() 357
is_transient_segment() 357
of() 357
release_pointer() 358
resolve_export_id() 358
retain_pointer() 358
return_memory() 359
session_of() 359
set_access_control() 359
set_allocation_strategy() 359
set_application_info() 360
set_comment() 360
set_default_cluster() 360
set_fetch_policy() 360
set_lock_option() 361
Release 6.3
set_null_illegal_pointers() 361
set_segment_reference_policy() 357
size() 361
~os_segment_access()
os_segment_access, defined by 364
os_segment_access()
os_segment_access, defined by 363
os_segment_access, the class 362
get_default() 362
get_primary_group() 362
no_access 362
operator =() 363
~os_segment_access() 364
os_segment_access() 363
read_access 363
read_write_access 363
set_default() 364
set_primary_group() 364
os_segment_cursor()
os_segment_cursor, defined by 365
os_segment_cursor, the class 365
get_current() 365
next() 365
os_segment_cursor() 365
reset() 366
os_server, the class 367
connection_is_broken() 367
disconnect() 368
get_databases() 368
get_host_name() 368
get_n_databases() 368
is_failover() 369
reconnect() 369
os_session, the class 370
create() 370
force_full_initialization() 370
get_all_sessions() 370
get_current() 370
get_n_sessions() 371
get_name() 371
get_thread_absorption() 371
of() 371
operator delete() 371
set_current() 372
set_thread_absorption() 372
unuse_DLL() 372
use_DLL() 372
os_signed_int8
551
O
typespec for 442
os_size_options, the class
argument to ossize() 187
os_soft_pointer, the macro 489
os_soft_pointer<T>, the class 489
os_soft_pointer32()
os_soft_pointer32<T>, defined by 382
os_soft_pointer32<char>, the class 389
os_soft_pointer32<T>, the class 381
operator =() 382
operator ->() 382
operator T*() 382
os_soft_pointer32() 382
resolve() 383
os_soft_pointer32<void>, the class 387
~os_soft_pointer32_base()
os_soft_pointer32_base, defined by 376
os_soft_pointer32_base, the class 373
decache() 373
dump() 373
get_database() 374
get_database_key() 374
get_open_database() 374
hash() 374
load() 374
operator !() 375
operator !=() 375
operator <() 375
operator <=() 376
operator ==() 375
operator >() 375
operator >=() 376
~os_soft_pointer32_base() 376
resolve() 376
OS_SOFT_POINTER32_NOCLASS(), the macro 490
os_soft_pointer64()
os_soft_pointer64<T>, defined by 385
os_soft_pointer64<char>, the class 390
os_soft_pointer64<T>, the class 384
operator =() 385
operator ->() 385
operator T*() 385
os_soft_pointer64() 385
resolve() 386
os_soft_pointer64<void>, the class 388
~os_soft_pointer64_base()
os_soft_pointer64_base, defined by 380
os_soft_pointer64_base, the class 377
552
decache() 377
dump() 377
get_database() 378
get_database_key() 378
get_open_database() 378
hash() 378
load() 378
operator !() 379
operator !=() 379
operator <() 379
operator <=() 380
operator ==() 379
operator >() 379
operator >=() 380
~os_soft_pointer64_base() 380
resolve() 380
OS_SOFT_POINTER64_NOCLASS(), the macro 491
os_store(), the global function 465
os_str_conv()
os_str_conv, defined by 393
os_str_conv, the class 391
change_mapping() 391
convert() 391
get_converted_size() 392
os_str_conv() 393
~os_string()
os_string, defined by 395
os_string()
os_string, defined by 395
os_string, the class 394
compare() 394
compare_nocase() 394
is_null() 394
operator =() 394
operator const char*() 394
~os_string() 395
os_string() 395
os_subscription()
os_subscription, defined by 398
os_subscription, the class 396
assign() 396
get_database() 397
os_subscription() 398
os_template, the class 399
Function 399
get_args() 399
get_kind() 399
is_unspecified() 399
C++ A P I Reference
Index
operator const os_type_template&() 399
operator os_type_template&() 400
set_args() 400
Type 400
os_template_actual_arg, the class 401
get_kind() 401
operator const os_literal_template_
actual_arg&() 401
operator const os_type_template_actual_
arg&() 401
operator os_literal_template_actual_
arg&() 401
operator os_type_template_actual_
arg&() 402
os_template_formal_arg, the class 403
get_kind() 403
get_name() 403
operator const os_template_type_
formal&() 403
operator const os_template_value_
formal&() 403
operator os_template_type_formal&() 403
operator os_template_value_formal&() 403
set_name() 404
os_template_instantiation, the class 405
create() 405
get_args() 405
get_template() 405
set_args() 405
set_template() 406
os_template_type_formal, the class 407
create() 407
os_template_value_formal, the class 408
create() 408
get_type() 408
set_type() 408
os_transaction, the class 409
abort() 409
abort_top_level() 409
begin() 409
checkpoint() 410
commit() 411
get_current() 411
get_name() 411
get_parent() 411
get_scope() 411
get_type() 411
is_aborted() 411
Release 6.3
is_committed() 412
is_lock_contention() 412
is_prepared() 412
read_only 413
session_of() 413
set_name() 413
top_level() 413
update 414
os_transaction_hook, the class 415
after_begin 415
after_checkpoint 415
after_commit 415
before_abort 415
before_checkpoint 415
before_commit 416
before_retry 416
deregister_hook() 416
register_hook() 416
os_transformer_binding()
os_transformer_binding, defined by 417
os_transformer_binding, the class 417
os_transformer_binding() 417
os_type, the class 418
Anonymous_indirect 418
Array 418
Char 418
Class 418
Double 418
Enum 418
Float 418
Function 418
get_alignment() 419
get_enclosing_class() 419
get_kind() 419
get_kind_string() 420
get_size() 420
get_string() 420
Instantiated_class 420
Integer 420
is_class_type() 420
is_const() 420
is_indirect_type() 420
is_integral_type() 420
is_pointer_type() 421
is_real_type() 421
is_unspecified() 421
is_volatile() 421
Long_double 421
553
O
Named_indirect 421
operator const os_anonymous_indirect_
type&() 421
operator const os_array_type&() 422
operator const os_class_type&() 422
operator const os_enum_type&() 422
operator const os_function_type&() 422
operator const os_instantiated_class_
type&() 422
operator const os_integral_type&() 422
operator const os_named_indirect_
type&() 422
operator const os_pointer_to_member_
type&() 422
operator const os_pointer_type&() 423
operator const os_real_type&() 423
operator const os_reference_type&() 423
operator const os_type_type&() 423
operator const os_void_type&() 423
operator os_anonymous_indirect_
type&() 423
operator os_array_type&() 423
operator os_class_type&() 423
operator os_enum_type&() 424
operator os_function_type&() 424
operator os_instantiated_class_
type&() 424
operator os_integral_type&() 424
operator os_named_indirect_type&() 424
operator os_pointer_to_member_type&() 424
operator os_pointer_type&() 424
operator os_real_type&() 424
operator os_reference_type&() 425
operator os_type_type&() 425
operator os_void_type&() 425
Pointer 425
Pointer_to_member 425
Reference 425
set_alignment() 425
set_size() 425
Signed_char 425
Signed_long 426
Signed_short 426
strip_indirect_types() 426
Type 427
type_at() 427
type_containing() 427
Undefined 427
554
Unsigned_char 427
Unsigned_integer 427
Unsigned_long 428
Unsigned_short 428
Void 428
os_Type_fixup_info()
os_Type_fixup_info, defined by 429
os_Type_fixup_info, the class 429
fixup_data 429
os_Type_fixup_info() 429
os_Type_fixup_loader, the class 430
fixup() 430
get() 430
load() 431
operator ()() 431
os_Type_info()
os_Type_info, defined by 433
os_Type_info, the class 432
data 432
get_original_location() 432
get_replacing_database() 432
get_replacing_location() 432
get_replacing_segment() 432
get_type() 433
os_Type_info() 433
set_replacing_location() 433
os_Type_loader, the class 434
create() 434
fixup() 434
get() 434
load() 435
operator ()() 435
os_type_template, the class 436
create() 436
get_type() 436
set_type() 436
os_type_template_actual_arg, the class 437
create() 437
get_type() 437
set_type() 437
os_type_type, the class 438
os_typed_pointer_void, the class 439
get_type() 439
operator void*() 439
os_typespec()
os_typespec, defined by 444
os_typespec, the class 440
get_char() 440
C++ A P I Reference
Index
get_double() 440
get_float() 440
get_int() 440
get_long() 441
get_long_double() 441
get_name() 441
get_os_int16() 441
get_os_int64() 441
get_os_int32() 441
get_os_signed_int8() 442
get_os_unsigned_int16() 442
get_os_unsigned_int32() 442
get_os_unsigned_int64() 442
get_os_unsigned_int8() 442
get_pointer() 443
get_short() 443
get_signed_char() 443
get_signed_int() 443
get_signed_long() 443
get_signed_short() 443
get_unsigned_char() 444
get_unsigned_int() 444
get_unsigned_long() 444
get_unsigned_short() 444
operator ==() 444
os_typespec() 444
os_unsigned_int16
typespec for 442
os_unsigned_int32
typespec for 442
os_unsigned_int64
typespec for 442
os_unsigned_int64()
os_unsigned_int64, defined by 446
os_unsigned_int64, the class 446
get_high() 446
get_low() 446
os_unsigned_int64() 446
sprint() 447
os_unsigned_int8
typespec for 442
os_unsigned_int32 47
os_untranslatable_pointer_handler, the
class 448
~os_untranslatable_pointer_handler() 451
get_exception() 448
get_explanation() 448
get_final_offset() 449
Release 6.3
get_source_cluster() 448
get_source_offset() 448
get_source_path() 448
get_target_cluster() 448
get_target_export_id() 449
get_target_exported() 449
get_target_offset() 449
get_target_path() 449
get_target_segment() 449
handle_xxx() 450
is_PTOM() 450
set_final_offset() 450
os_verifydb_options, the class
argument to osverifydb() 188
argument to osverifydb_one_segment() 189
os_void_type, the class 451
create() 451
~os_with_mapped()
os_with_mapped, defined by 452
os_with_mapped()
os_with_mapped, defined by 452
os_with_mapped, the class 452
~os_with_mapped() 452
os_with_mapped() 452
ossg utility
OS_MARK_SCHEMA_TYPE(), the macro 482
OS_MARK_SCHEMA_TYPESPEC(), the macro 483
ossize()
os_dbutil, defined by 186
OSU_DATABASE
os_rawfs_entry, defined by 285
OSU_DIRECTORY
os_rawfs_entry, defined by 285
OSU_LINK
os_rawfs_entry, defined by 285
osverifydb()
os_dbutil, defined by 187
osverifydb_one_segment()
osdbutil, defined by 188
outer_collocated_path()
os_path_to_data, defined by 273
outer_path()
os_path_to_data, defined by 273
own_page_write
objectstore, defined by 79
P
permissions 362
555
Q
Persistent
os_member_variable, defined by 251
persistent delete 458
persistent new 459
persistent storage 44
allocating 459
reclaiming using the delete operator 458
persistently allocated objects 44
Pointer
os_type, defined by 425
Pointer_to_member
os_type, defined by 425
pointers
See also cross-database pointers
pop()
os_path_to_data, defined by 273
Private
os_base_class, defined by 117
os_member, defined by 242
programs, examples
See example programs
propagate_log()
objectstore, defined by 79
Protected
os_base_class, defined by 117
os_member, defined by 243
Public
os_base_class, defined by 117
os_member, defined by 243
Q
queue_status()
os_notification, defined by 263
R
read_access
os_segment_access, defined by 363
read_only
os_transaction, defined by 413
read_write_access
os_segment_access, defined by 363
read-only transactions 475
receive()
os_notification, defined by 264
reclaiming storage
using the delete operator 458
reconnect()
556
os_server, defined by 369
reconnecting to servers 367
Reference
os_type, defined by 425
register_()
os_DLL_finder, defined by 205
register_hook()
os_transaction_hook, defined by 416
registry location on Windows 109
Regular
os_member_variable, defined by 251
rehost_all_links()
os_dbutil, defined by 189
rehost_link()
os_dbutil, defined by 189
Relationship
os_member, defined by 243
release()
os_address_space_marker, defined by 99
os_persistent_to_transient_pointer_
manager, defined by 277
os_retain_address, defined by 329
release_address_space()
os_object_cursor, defined by 269
release_cleared_persistent_to_transient_
pointers()
objectstore, defined by 79
release_maintenance()
objectstore, defined by 80
release_major()
objectstore, defined by 80
release_minor()
objectstore, defined by 80
release_name()
objectstore, defined by 81
release_persistent_addresses()
objectstore, defined by 81
release_pointer()
os_cluster, defined by 133
os_database, defined by 166
os_database_root, defined by 173
os_segment, defined by 358
tix_exception, defined by 454
remote schemas 151
remove()
os_dbutil, defined by 190
os_dynamic_extent, defined by 214
remove_db_from_archive()
C++ A P I Reference
Index
os_archiver, defined by 105
remove_required_DLL_identifier()
os_database, defined by 167
rename()
os_dbutil, defined by 190
reset()
os_archiver_options, defined by 107
os_backup_options, defined by 115
os_cluster_cursor, defined by 139
os_export_id_cursor, defined by 221
os_mop, defined by 256
os_object_cursor, defined by 269
os_recover_options, defined by 292
os_replicator_options, defined by 320
os_restore_options, defined by 328
os_segment_cursor, defined by 366
reset_persistent_addresses()
objectstore, defined by 81
reset_statistics()
os_replicator, defined by 317
resolve()
os_Dumper_reference, defined by 210
os_Reference<T>, defined by 294
os_reference_cross_session, defined by 300
os_Reference_cross_session<T>, defined
by 296
os_reference_internal, defined by 303
os_Reference_protected<T>, defined by 305
os_reference_protected_internal, defined
by 309
os_soft_pointer32<T>, defined by 383
os_soft_pointer32_base, defined by 376
os_soft_pointer64<T>, defined by 386
os_soft_pointer64_base, defined by 380
resolve_export_id()
os_segment, defined by 358
retain()
os_address_space_marker, defined by 100
retain_persistent_addresses()
objectstore, defined by 81
retain_pointer()
os_cluster, defined by 134
os_database, defined by 167
os_database_root, defined by 173
os_segment, defined by 358
retaining()
os_retain_address, defined by 329
retrieving data member address using os_fetch_
Release 6.3
address() 464
retrieving data member value using os_
fetch() 461
return_all_pages()
objectstore, defined by 81
return_memory()
objectstore, defined by 81
os_cluster, defined by 134
os_database, defined by 167
os_segment, defined by 359
rmdir()
os_dbutil, defined by 190
RPC exceptions 511
S
schema evolution 46
exceptions 508
transformer functions 333
schema keys
objectstore::set_current_schema_key() 86
os_database::change_schema_key() 149
os_database::freeze_schema_key() 153
schemas
See also component schemas
OS_MARK_SCHEMA_TYPE(), the macro 482
OS_MARK_SCHEMA_TYPESPEC(), the macro 483
remote 151
segment_number
os_pathname_and_segment_number, defined
by 275
os_pathname_segment_cluster, defined by 276
segment_of()
os_cluster, defined by 134
segment-level access control 362
segments 44
default
returning 156
setting 168
initial, returning 156
initial, setting 168
iterating over 365
os_segment, the class 352
transient 357
servers
reconnecting to 367
session_of()
os_cluster, defined by 134
os_database, defined by 167
557
S
os_segment, defined by 359
os_transaction, defined by 413
set()
os_object_cursor, defined by 270
set_access()
os_base_class, defined by 117
os_member, defined by 243
set_access_control()
os_segment, defined by 359
set_access_of_get_os_typespec_function()
os_class_type, defined by 127
set_address_space_release_interval()
os_compact, defined by 144
os_schema_evolution, defined by 341
set_alignment()
os_type, defined by 425
set_allocation_strategy()
objectstore, defined by 82
os_cluster, defined by 135
os_database, defined by 168
os_segment, defined by 359
set_always_check_server_connection_at_
commit()
objectstore, defined by 82
set_always_null_illegal_pointers()
objectstore, defined by 83
set_application_info()
os_database, defined by 168
os_segment, defined by 360
set_application_schema_path()
os_dbutil, defined by 190
set_application_schema_pathname()
objectstore, defined by 83
set_arg_list()
os_function_type, defined by 228
set_arg_list_kind()
os_function_type, defined by 228
set_args()
os_template, defined by 400
os_template_instantiation, defined by 405
set_asmarkers_useless()
objectstore, defined by 83
set_auto_open_mode()
objectstore, defined by 83
set_autoload_DLLs_function()
objectstore, defined by 83
set_avoid_page_boundary()
os_compact, defined by 144
558
os_schema_evolution, defined by 341
set_base_classes()
os_class_type, defined by 127
set_base_member()
os_access_modifier, defined by 97
set_cache_file()
objectstore, defined by 85
set_cache_size()
objectstore, defined by 85
set_call_linkage()
os_member_function, defined by 246
set_class()
os_base_class, defined by 117
set_class_kind()
os_class_type, defined by 127
set_client_name()
objectstore, defined by 85
os_dbutil, defined by 191
set_comment()
os_segment, defined by 360
set_copy_member_functions()
os_schema_install_options, defined by 351
set_current()
os_session, defined by 372
set_current_schema_key()
objectstore, defined by 86
set_decache_soft_pointers_after_address_
space_release()
objectstore, defined by 86
set_declares_get_os_typespec_function()
os_class_type, defined by 127
set_default()
os_segment_access, defined by 364
set_default_address_space_partition_size()
objectstore, defined by 87
set_default_cluster()
os_segment, defined by 360
set_default_segment()
os_database, defined by 168
set_defines_virtual_functions()
os_class_type, defined by 127
set_disable_transformer_class_checks()
os_schema_evolution, defined by 342
set_dispatch_table_pointer_offset()
os_class_type, defined by 128
set_element_type()
os_array_type, defined by 108
set_enclosing_namespace()
C++ A P I Reference
Index
os_namespace, defined by 258
set_enumerators()
os_enum_type, defined by 216
set_evolved_schema_db_name()
os_schema_evolution, defined by 342
set_explanation_level()
os_compact, defined by 144
os_schema_evolution, defined by 342
set_fetch_policy()
objectstore, defined by 87
os_cluster, defined by 135
os_database, defined by 169
os_segment, defined by 360
set_final_offset()
os_untranslatable_pointer_handler, defined
by 450
set_handle_transient_faults()
objectstore, defined by 88
set_has_constructor()
os_class_type, defined by 128
set_has_destructor()
os_class_type, defined by 128
set_incremental_schema_installation()
objectstore, defined by 88
os_database, defined by 169
set_indirect_virtual_base_classes()
os_class_type, defined by 128
set_instantiation()
os_instantiated_class_type, defined by 230
set_introduces_virtual_functions()
os_class_type, defined by 128
set_is_abstract()
os_class_type, defined by 128
set_is_const()
os_anonymous_indirect_type, defined by 101
os_member_function, defined by 246
set_is_forward_definition()
os_class_type, defined by 128
set_is_inline()
os_member_function, defined by 246
set_is_overloaded()
os_member_function, defined by 246
set_is_persistent()
os_class_type, defined by 128
set_is_pure_virtual()
os_member_function, defined by 246
set_is_static()
os_member_function, defined by 246
Release 6.3
set_is_virtual()
os_member_function, defined by 247
set_is_volatile()
os_anonymous_indirect_type, defined by 101
os_member_function, defined by 247
set_literal()
os_literal_template_actual_arg, defined
by 237
set_locator_file()
objectstore, defined by 88
set_lock_option()
objectstore, defined by 88
os_cluster, defined by 135
os_database, defined by 169
os_segment, defined by 361
set_lock_timeout()
objectstore, defined by 89
set_log_file()
objectstore, defined by 89
set_malloc_size()
os_compact, defined by 145
os_schema_evolution, defined by 343
set_maplet_size()
os_compact, defined by 145
os_schema_evolution, defined by 343
set_maximum_cluster_size()
os_compact, defined by 145
os_schema_evolution, defined by 145, 343
set_maximum_memory_size()
os_compact, defined by 145
os_schema_evolution, defined by 145, 343
set_members()
os_class_type, defined by 128
os_namespace, defined by 258
set_name()
os_class_type, defined by 129
os_enum_type, defined by 216
os_enumerator_literal, defined by 217
os_member_function, defined by 247
os_member_variable, defined by 252
os_named_indirect_type, defined by 257
os_namespace, defined by 259
os_pointer_literal, defined by 279
os_template_formal_arg, defined by 404
os_transaction, defined by 413
set_namespace()
os_member_namespace, defined by 248
set_new_segment_reference_policy()
559
S
os_database, defined by 170
set_null_illegal_pointers()
objectstore, defined by 90
os_cluster, defined by 136
os_database, defined by 170
os_segment, defined by 361
set_number_of_elements()
os_array_type, defined by 108
set_obsolete_index_handler()
os_schema_evolution, defined by 343
set_obsolete_query_handler()
os_schema_evolution, defined by 343
set_offset()
os_base_class, defined by 118
os_member_variable, defined by 252
set_optimzie_checkpoints()
os_schema_evolution, defined by 345
set_pathname_encoding()
objectstore, defined by 90
set_persistent_to_transient_pointer()
objectstore, defined by 90
set_pragmas()
os_class_type, defined by 129
os_enum_type, defined by 216
set_pre_evolution_setup_hook()
os_schema_evolution, defined by 345
set_primary_group()
os_segment_access, defined by 364
set_propagate_on_commit()
objectstore, defined by 91
set_queue_size()
os_notification, defined by 265
set_reconnect_timeout_and_interval()
os_failover_server, defined by 223
set_replacing_location()
os_Type_info, defined by 433
set_reserve_as_mode()
objectstore, defined by 91
set_resolve_ambiguous_void_pointers()
os_schema_evolution, defined by 345
set_retain()
os_retain_address, defined by 329
set_retain_persistent_addresses()
objectstore, defined by 91
set_return_type()
os_function_type, defined by 228
set_schema_database()
os_database, defined by 170
560
set_schema_database_pathname()
os_schema_handle, defined by 349
os_schema_info, defined by 350
set_segment_reference_policy()
os_segment, defined by 357
set_simple_auth_ui()
objectstore, defined by 92
set_size()
os_cluster, defined by 136
os_database, defined by 170
os_field_member_variable, defined by 224
os_type, defined by 425
set_size_in_sectors()
os_database, defined by 171
set_source_position()
os_class_type, defined by 129
os_enum_type, defined by 216
os_member_function, defined by 247
os_member_variable, defined by 252
os_named_indirect_type, defined by 257
set_storage_class()
os_member_variable, defined by 253
set_suppress_invalid_hard_pointer_errors()
objectstore, defined by 92
set_target_class()
os_pointer_to_member_type, defined by 280
set_target_type()
os_indirect_type, defined by 229
os_pointer_type, defined by 281
set_task_list_file_name()
os_schema_evolution, defined by 345
set_template()
os_template_instantiation, defined by 406
set_thread_absorption()
os_session, defined by 372
set_transaction_max_retries()
objectstore, defined by 92
set_transaction_priority()
objectstore, defined by 92
set_transient_delete_function()
objectstore, defined by 93
set_type()
os_member_function, defined by 247
os_member_type, defined by 249
os_member_variable, defined by 253
os_pointer_literal, defined by 279
os_template_value_formal, defined by 408
os_type_template, defined by 436
C++ A P I Reference
Index
os_type_template_actual_arg, defined by 437
set_unhandled_exception_hook()
tix_exception, defined by 455
set_union_variant()
objectstore, defined by 94
set_untranslatable_pointer_handler()
os_schema_evolution, defined by 345
set_value()
os_database_root, defined by 174
os_enumerator_literal, defined by 217
set_virtual_base_class_no_pointer()
os_base_class, defined by 118
set_virtual_base_class_pointer_offset()
os_base_class, defined by 118
set_virtuals_redefined()
os_base_class, defined by 118
should_use_default_constructor()
os_Dumper_specialization, defined by 212
shutdown()
objectstore, defined by 94
os_compact, defined by 146
os_schema_evolution, defined by 345
signal()
objectstore_exception, defined by 96
Signed_char
os_type, defined by 425
Signed_long
os_type, defined by 426
Signed_short
os_type, defined by 426
size()
os_cluster, defined by 137
os_database, defined by 171
os_segment, defined by 361
size_in_sectors()
os_database, defined by 171
soft-pointer decaching 86
split_pathname()
os_dbutil, defined by 191
sprint()
os_int64, defined by 231
os_unsigned_int64, defined by 447
stack unwind 52
start_and_run_backup()
os_backup, defined by 110
start_and_run_recover()
os_recover, defined by 287
start_and_run_restore()
Release 6.3
os_restore, defined by 324
start_archiver()
os_archiver, defined by 105
start_backrest_logging()
os_dbutil, defined by 191
start_backup()
os_backup, defined by 111
start_recover()
os_recover, defined by 288
start_replicator()
os_replicator, defined by 317
start_restore()
os_restore, defined by 324
stat()
os_dbutil, defined by 192
Static
os_member_variable, defined by 251
stop_archiverp()
os_archiver, defined by 105
stop_backrest_logging()
os_dbutil, defined by 192
stop_backup()
os_backup, defined by 111
stop_recover()
os_recover, defined by 288
stop_replicator()
os_replicator, defined by 317
stop_restore()
os_restore, defined by 324
storage
allocating 459
strip_indirect_types()
os_type, defined by 426
Struct
os_class_type, defined by 129
subscribe()
os_notification, defined by 265
svr_checkpoint()
os_dbutil, defined by 192
svr_client_kill()
os_dbutil, defined by 192
svr_debug()
os_dbutil, defined by 193
svr_machine()
os_dbutil, defined by 193
svr_ping()
os_dbutil, defined by 194
svr_shutdown()
561
T
os_dbutil, defined by 194
svr_stat()
os_dbutil, defined by 194
T
take_a_snapshot()
os_archiver, defined by 105
task_list()
os_schema_evolution, defined by 346
time_created()
os_database, defined by 171
TIX exception macros
TIX_END_HANDLE 492
TIX_EXCEPTION 493
TIX_HANDLE() 494
TIX_HANDLE_IF() 497
TIX exceptions
See also exceptions
DECLARE_EXCEPTION(), the macro 471
DEFINE_EXCEPTION(), the macro 472
tix_context, the class 453
TIX_END_HANDLE, the macro 492
tix_exception, the class 454
ancestor_of() 454
get_os_deadlock_exception() 454
get_os_lock_timeout_exception() 454
release_pointer() 454
set_unhandled_exception_hook() 455
TIX_EXCEPTION, the macro 493
TIX_HANDLE(), the macro 494
TIX_HANDLE_IF(), the macro 497
tix_handler, the class 456
get_current() 456
get_exception() 456
get_report() 456
get_report0() 456
get_value() 456
to_bit_field()
os_path_to_data, defined by 273
to_dope()
os_path_to_data, defined by 273
to_static_member()
os_path_to_data, defined by 273
to_subscript()
os_path_to_data, defined by 273
top_level()
os_transaction, defined by 413
transactions
562
nesting 475
OS_BEGIN_TXN(), the macro 474
OS_BEGIN_TXN_NAMED(), the macro 478
read-only 475
update 475
transformer functions 333
transient segments 357
transient storage
allocating 459
transiently allocated objects
and clustering 459
creating 459
Type
os_member, defined by 243
os_template, defined by 400
os_type, defined by 427
type()
os_path_to_data, defined by 273
type_at()
os_type, defined by 427
type_containing()
os_type, defined by 427
typespecs
os_typespec class 440
U
Undefined
os_type, defined by 427
Union
os_class_type, defined by 129
unique_name()
os_path_to_data, defined by 273
Unknown
os_function_type, defined by 227
unload_DLL()
objectstore, defined by 94
unregister()
os_DLL_finder, defined by 205
Unsigned_char
os_type, defined by 427
Unsigned_integer
os_type, defined by 427
Unsigned_long
os_type, defined by 428
Unsigned_short
os_type, defined by 428
unsubscribe()
os_notification, defined by 266
C++ A P I Reference
Index
unuse_DLL()
os_session, defined by 372
unwind, stack 52
update
os_transaction, defined by 414
update transactions 475
use_DLL()
os_session, defined by 372
utility API 178
V
Variable
os_function_type, defined by 227
os_member, defined by 243
virtual_base_class_has_pointer()
os_base_class, defined by 118
virtuals_redefined()
os_base_class, defined by 118
Void
os_type, defined by 428
vsignal()
objectstore_exception, defined by 96
W
which_product()
objectstore, defined by 94
Windows registry location 109
with()
os_cluster, defined by 137
Release 6.3
563
W
564
C++ A P I Reference