C++ A P I Reference -...

C++ A P I Reference

Release 6.3

C++ A P I ReferenceObjectStore 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43ObjectStore Database Services . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 2 Class Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47ObjectStore classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47basic_undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

basic_undo::basic_undo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

basic_undo::get_exception() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

basic_undo::has_exception() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

basic_undo::~basic_undo() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

objectstore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54objectstore::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

4

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

objectstore::lock_cluster_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

4 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

6

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96objectstore_exception::signal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

objectstore_exception::vsignal() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

os_access_modifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97os_access_modifier::create(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

os_access_modifier::get_base_member() . . . . . . . . . . . . . . . . . . . . . . .97

os_access_modifier::set_base_member() . . . . . . . . . . . . . . . . . . . . . . .97

os_address_space_marker. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 101os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102os_app_schema::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102


Contents

os_application_schema_info . . . . . . . . . . . . . . . . . . . . . . . . . . . 103os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106os_archiver_options::os_archiver_options(). . . . . . . . . . . . . . . . . . . . .107

os_archiver_options::~os_archiver_options() . . . . . . . . . . . . . . . . . . .107

os_archiver_options::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107

os_array_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109os_authentication::get_nt_registry_location() . . . . . . . . . . . . . . . . . . .109

os_authentication::set_nt_registry_location() . . . . . . . . . . . . . . . . . . .109

os_backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112os_backup_options::os_backup_options() . . . . . . . . . . . . . . . . . . . . . .115

os_backup_options::~os_backup_options() . . . . . . . . . . . . . . . . . . . . .115

os_backup_options::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115

os_base_class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116os_base_class::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

os_base_class::get_access() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

os_base_class::get_class() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116

Release 6.3 7

Contents

8

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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119os_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

os_class_type::has_dispatch_table_other_compiler() . . . . . . . . . . . . . . 126


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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130os_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

10

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140os_cluster_with::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

os_compact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147os_comp_schema::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

os_database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148os_database::affiliate(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

os_database::change_affiliation() . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

os_database::change_schema_key() . . . . . . . . . . . . . . . . . . . . . . . . . 149

os_database::close() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

os_database::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

os_database::create_root(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152


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

12

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175os_database_schema::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

os_database_schema::get_for_update() . . . . . . . . . . . . . . . . . . . . . . . 175


Contents

os_database_schema::install(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175

os_Database_table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176os_Database_table::find_reference() . . . . . . . . . . . . . . . . . . . . . . . . .176

os_Database_table::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176

os_Database_table::insert() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176

os_Database_table::is_ignored() . . . . . . . . . . . . . . . . . . . . . . . . . . . .177

os_dbutil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178os_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

14

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205os_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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206os_DLL_schema_info::add_DLL_identifier(). . . . . . . . . . . . . . . . . . . . . 206

os_DLL_schema_info::DLL_loaded(). . . . . . . . . . . . . . . . . . . . . . . . . . 206

os_DLL_schema_info::DLL_unloaded() . . . . . . . . . . . . . . . . . . . . . . . . 207

os_Dumper_reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208os_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

os_Dumper_reference::operator ==() . . . . . . . . . . . . . . . . . . . . . . . . 209


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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211os_Dumper_specialization::get_specialization_name() . . . . . . . . . . . . .211

os_Dumper_specialization::operator ()() . . . . . . . . . . . . . . . . . . . . . . .211

os_Dumper_specialization::should_use_default_constructor() . . . . . . . .212

os_dynamic_extent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217os_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 . . . . . . . . . . . . . . . . . . . . . . . . 218os_evolve_subtype_fun_binding::os_evolve_subtype_fun_binding(). . . .218

os_export_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219os_export_id::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219

os_export_id::get_value() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219

os_export_id::is_null() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219

Release 6.3 15

Contents

16

os_export_id::operator ==() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

os_export_id_cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229os_indirect_type::get_target_type(). . . . . . . . . . . . . . . . . . . . . . . . . . 229

os_indirect_type::set_target_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 229

os_instantiated_class_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230os_instantiated_class_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . 230

os_instantiated_class_type::get_instantiation() . . . . . . . . . . . . . . . . . . 230


Contents

os_instantiated_class_type::set_instantiation() . . . . . . . . . . . . . . . . . .230

os_int64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231os_int64::os_int64() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231

os_int64::get_high(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231

os_int64::get_low() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231

os_int64::sprint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231

os_integral_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234os_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 . . . . . . . . . . . . . . . . . . . . . . . . . 237os_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

18

os_lock_timeout_exception . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240os_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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244os_member_function::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

os_member_function::get_call_linkage() . . . . . . . . . . . . . . . . . . . . . . 244

os_member_function::get_function_kind() . . . . . . . . . . . . . . . . . . . . . 244

os_member_function::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . 245


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248os_member_namespace::create() . . . . . . . . . . . . . . . . . . . . . . . . . . .248

os_member_namespace::get_namespace(). . . . . . . . . . . . . . . . . . . . .248

os_member_namespace::set_namespace() . . . . . . . . . . . . . . . . . . . . .248

os_member_type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249os_member_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249

os_member_type::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249

os_member_type::set_type() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249

os_member_variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250os_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

20

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260os_notification::assign() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

os_notification::get_database() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

os_notification::get_kind() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

os_notification::_get_fd() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

os_notification::get_location() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271os_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

22

os_path_to_data::unique_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

os_pathname_and_segment_number . . . . . . . . . . . . . . . . . . . . . 275os_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 . . . . . . . . . . . . . . . . . . . . . . . . . 276os_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. . . . . . . . . . . . . . . . 277os_persistent_to_transient_pointer_manager::release() . . . . . . . . . . . . 277

os_Planning_action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278os_Planning_action::operator ()() . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

os_pointer_literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 280os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281os_pointer_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

os_pointer_type::get_target_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 281

os_pointer_type::set_target_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 281

os_pragma. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282os_pragma::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

os_pragma::get_string(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

os_pragma::is_recognized() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

os_rawfs_entry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283os_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

os_rawfs_entry::get_n_sectors() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

os_rawfs_entry::get_name() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289os_recover_options::os_recover_options() . . . . . . . . . . . . . . . . . . . . .292

os_recover_options::~os_recover_options() . . . . . . . . . . . . . . . . . . . .292

os_recover_options::reset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .292

os_Reference<T> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293os_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>. . . . . . . . . . . . . . . . . . . . . . . . 295os_Reference_cross_session<T>::get_os_typespec() . . . . . . . . . . . . . .295

os_Reference_cross_session<T>::operator =() . . . . . . . . . . . . . . . . . .295

Release 6.3 23

Contents

24

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301os_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> . . . . . . . . . . . . . . . . . . . . . . . . . . . 304os_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

os_Reference_protected<T>::os_Reference_protected() . . . . . . . . . . . 305


Contents

os_Reference_protected<T>::resolve(). . . . . . . . . . . . . . . . . . . . . . . .305

os_reference_protected_internal . . . . . . . . . . . . . . . . . . . . . . . . 306os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310os_reference_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310

os_relationship_member_variable . . . . . . . . . . . . . . . . . . . . . . . 311os_relationship_member_variable::get_related_class(). . . . . . . . . . . . .311

os_relationship_member_variable::get_related_member() . . . . . . . . . .311

os_release_cluster_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312os_release_database_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . 313os_release_root_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314os_release_segment_pointer. . . . . . . . . . . . . . . . . . . . . . . . . . . 315os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318os_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

26

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325os_restore_options::os_restore_options() . . . . . . . . . . . . . . . . . . . . . . 328

os_restore_options::~os_restore_options(). . . . . . . . . . . . . . . . . . . . . 328

os_restore_options::reset(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

os_retain_address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329os_retain_address::os_retain_address() . . . . . . . . . . . . . . . . . . . . . . . 329

os_retain_address::release(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

os_retain_address::retaining() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

os_retain_address::set_retain(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

os_schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332os_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

os_schema_evolution::get_enclosing_object(). . . . . . . . . . . . . . . . . . . 340


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347os_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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350os_schema_info::get() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .350

Release 6.3 27

Contents

28

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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352os_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

os_segment::set_comment(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365os_segment_cursor::os_segment_cursor() . . . . . . . . . . . . . . . . . . . . .365

os_segment_cursor::get_current() . . . . . . . . . . . . . . . . . . . . . . . . . . .365

os_segment_cursor::next() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .365

os_segment_cursor::reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .366

os_server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370os_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

30

os_session::set_thread_absorption() . . . . . . . . . . . . . . . . . . . . . . . . . 372

os_session::unuse_DLL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

os_session::use_DLL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

os_soft_pointer32_base. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373os_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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377os_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>. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381os_soft_pointer32<T>::operator =() . . . . . . . . . . . . . . . . . . . . . . . . . 382

os_soft_pointer32<T>::operator T*(). . . . . . . . . . . . . . . . . . . . . . . . . 382


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> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384os_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> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387os_soft_pointer64<void> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388os_soft_pointer32<char> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389os_soft_pointer64<char> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396os_subscription::assign() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396

os_subscription::get_database() . . . . . . . . . . . . . . . . . . . . . . . . . . . .397

os_subscription::operator=() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397

os_subscription::os_subscription() . . . . . . . . . . . . . . . . . . . . . . . . . . .398

os_template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399os_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

32

os_template_actual_arg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407os_template_type_formal::create() . . . . . . . . . . . . . . . . . . . . . . . . . . 407

os_template_value_formal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408os_template_value_formal::create() . . . . . . . . . . . . . . . . . . . . . . . . . 408

os_template_value_formal::get_type(). . . . . . . . . . . . . . . . . . . . . . . . 408

os_template_value_formal::set_type() . . . . . . . . . . . . . . . . . . . . . . . . 408

os_transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409os_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

os_transaction::is_lock_contention() . . . . . . . . . . . . . . . . . . . . . . . . . 412


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417os_transformer_binding::os_transformer_binding() . . . . . . . . . . . . . . .417

os_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418os_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

34

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

os_type::Signed_char. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425


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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429os_Type_fixup_info::fixup_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .429

os_Type_fixup_info::os_Type_fixup_info() . . . . . . . . . . . . . . . . . . . . .429

os_Type_fixup_loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430os_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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436os_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

36

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438os_typed_pointer_void . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

os_typed_pointer_void::get_type() . . . . . . . . . . . . . . . . . . . . . . . . . . 439

os_typed_pointer_void::operator void*() . . . . . . . . . . . . . . . . . . . . . . 439

os_typespec. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440os_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_signed_int8() . . . . . . . . . . . . . . . . . . . . . . . . . . 442

os_typespec::get_os_unsigned_int8() . . . . . . . . . . . . . . . . . . . . . . . . 442

os_typespec::get_os_unsigned_int16() . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446os_unsigned_int64::os_unsigned_int64() . . . . . . . . . . . . . . . . . . . . . . 446

os_unsigned_int64::get_high() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

os_unsigned_int64::get_low() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446

os_unsigned_int64::sprint() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447


Contents

os_untranslatable_pointer_handler . . . . . . . . . . . . . . . . . . . . . . 448os_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451os_void_type::create() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451

os_with_mapped . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452os_with_mapped::os_with_mapped() . . . . . . . . . . . . . . . . . . . . . . . . .452

os_with_mapped::~os_with_mapped() . . . . . . . . . . . . . . . . . . . . . . . .452

tix_context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453tix_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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456tix_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 . . . . . . . . . . . . . . . 457Global C++ Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457::operator delete(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

void ::operator delete(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .458

::operator new() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

Release 6.3 37

Contents

38

::os_fetch() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461::os_fetch_address() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464::os_store() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

Chapter 4 System-Supplied Macros. . . . . . . . . . . . . . . . . . . . . .469ObjectStore Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469DECLARE_EXCEPTION(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471DEFINE_EXCEPTION() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472OS_BEGIN_TXN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474OS_BEGIN_TXN_NAMED() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478OS_END_FAULT_HANDLER . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479OS_END_TXN() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480OS_ESTABLISH_FAULT_HANDLER . . . . . . . . . . . . . . . . . . . . . . . 481OS_MARK_SCHEMA_TYPE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482OS_MARK_SCHEMA_TYPESPEC() . . . . . . . . . . . . . . . . . . . . . . . . 483OS_REFERENCE_NOCLASS() . . . . . . . . . . . . . . . . . . . . . . . . . . . 484OS_REFERENCE_PROTECTED_NOCLASS() . . . . . . . . . . . . . . . . . . 485OS_REPORT_DLL_LOAD_AND_UNLOAD() . . . . . . . . . . . . . . . . . . 486OS_SCHEMA_DLL_ID() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487OS_SCHEMA_INFO_NAME() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488os_soft_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489OS_SOFT_POINTER32_NOCLASS() . . . . . . . . . . . . . . . . . . . . . . . 490OS_SOFT_POINTER64_NOCLASS() . . . . . . . . . . . . . . . . . . . . . . . 491TIX_END_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492TIX_EXCEPTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493TIX_HANDLE() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494TIX_HANDLE_IF() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497

Chapter 5 Predefined TIX Exceptions. . . . . . . . . . . . . . . . . . . . .499Parent Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500General ObjectStore Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . 501Schema Evolution Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . 508Metaobject Protocol Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . 509Database Copy Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509RPC Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511Component Schema Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . 512

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .513


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 OrganizedThis 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 system-supplied 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 ConventionsThis 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 Italic Courier font indicates the name of an argument or variable for which you must supply a value.

Release 6.3 39

Preface

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 WebThe 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.

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.

Convention Meaning


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


Chapter 1Introduction

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 ServicesThis section summarizes the functionality of ObjectStore database services.

PersistenceObjectStore 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 ControlMany 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

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,

44

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 cross-database 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 ControlObjectStore 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 ControlThe 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 ToleranceObjectStore’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 AccessObjectStore’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 EvolutionThe 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 CompactionObjectStore 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 2Class 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 classesThe following list includes all the ObjectStore API classes available for you to use in developing your ObjectStore applications.

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

Release 6.3 47

ObjectStore classes

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


Chapter 2: Class Library

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

Release 6.3 49

ObjectStore classes

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



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

Release 6.3 51

basic_undo

basic_undoIn 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().



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

objectstoreThis 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.



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.






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 top-level transaction.

Locking a segment is equivalent to acquiring locks on all the pages of the segment. So, for example, acquiring a read lock on a segment is equivalent to acquiring read locks on all the pages of the segment. Acquiring a lock on a segment does not preclude clients from requesting separate locks on individual pages of the database.







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 top-level 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.




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.


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 re-fetched. 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);



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 top-level 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



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();



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();



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.



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



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 top-level 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.



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)



• 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 process-wide 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()



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.



objectstore::lock_cluster_read This enumerator is a possible argument to





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





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





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





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





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





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





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.



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





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.



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( );



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.



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:

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 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.

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.



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 soft-pointer 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.



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,



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::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:

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.

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.




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



);

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();



Always returns ostore_cpp.

Release 6.3 95

objectstore_exception

objectstore_exceptionAll 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.



os_access_modifierclass 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_markerTo 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.



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.



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_schemaThis 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.



os_application_schema_infoThis 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.


You must include the header file <ostore/nreloc/schftyps.hh>.

Release 6.3 103

os_archiver

os_archiverThe 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.


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

-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.



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_optionsThe 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.


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 archive-image 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.



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.

network_timeout Sets the timeout value in seconds that the archiver process will wait for osserver to respond.

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.

import_file 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

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.

Release 6.3 107

os_array_type

os_array_typeclass 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.



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.



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.



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_backupThe 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.



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:

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.


-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_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_optionsThe 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.


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;


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 backup-image 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



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-of-media 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.


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.



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() {}


os_backup_options::reset() void reset();


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.

Release 6.3 115

os_base_class

os_base_classThis 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).




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 The following overloading for get_offset() is supported:



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::PrivateThis enumerator is a possible return value from os_base_class::get_access( ), indicating private access.

os_base_class::ProtectedThis enumerator is a possible return value from os_base_class::get_access( ), indicating protected access.

os_base_class::PublicThis 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.



os_class_typeclass 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.




os_class_type::Anonymous_unionThis enumerator is a possible return value from os_class_type::get_class_kind( ). It indicates an anonymous union type.

os_class_type::ClassThis 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 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);

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

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:

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.

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 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.


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.


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.


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.



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.


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:

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.

First Argument (object)

Second Argument (most_derived_object)

Return Value (os_class_type)

pic pC C

pid pD D

pib pD D



Given the following:

C1 c1;C1 * pc1 = & c1;B0 * pb0 = (B0 *)pc1;C0 * 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.



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.


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.



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::StructThis enumerator is a possible return value from os_class_type::get_class_kind( ). It indicates a struct.

os_class_type::UnionThis 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



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.



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










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.



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



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






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










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.



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.




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.



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.



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.



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.


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.


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

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



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);



Specifies the level of debugging information that is output during compaction. The level argument can be one of the following enumerators:

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.

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.

Release 6.3 145

os_compact

os_compact::shutdown()static void shutdown();

After completion shutdown() must be called to clean up ObjectStore resources.



os_comp_schemaThis 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.



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_databaseInstances 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 per-session 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.



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.



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



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).



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(



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,};


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_



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 };




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










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:

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);


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.



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.



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 );



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.


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.


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();


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.



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.



• 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();


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






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.



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









Release 6.3 169

os_database


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.



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_rootAn 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.




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



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();


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.



• 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();


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*).



os_database_schemaThis 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.



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_tableThe 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.


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().



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.



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.



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:

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.

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 class os_cmgr_stat_client has the following public data members:

The class os_cmgr_stat_svr has the following public data members:

The class os_cmgr_stat_file_usage has the following public data members:

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.


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;


char *host_name;

os_int32 client_pid;

char *status_str;


char *file_name;

os_unsigned_int32 file_length;

os_boolean is_free;

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:

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


os_unsigned_int32 free_blocks;

os_unsigned_int32 file_system_size;

os_unsigned_int32 used_blocks;



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.



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 Display database status; corresponds to the osdbcontrol utility’s -status option.

Release 6.3 185

os_dbutil

The os_dbcontrol_options class has the following public method:

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:

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

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().

void reset() Reset all the options.

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



);

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:

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).


os_boolean flag_all; /* -a */

os_boolean flag_segments; /* -c */

os_boolean flag_total_database; /* -C */

os_boolean flag_fragmentation; /* -f */

os_unsigned_int32 one_segment_number; /* -n */

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 */

Release 6.3 187

os_dbutil

The class os_verifydb_options has the following public data members:

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).

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;



The class os_verifydb_options has the following public data members:

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.

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;

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.



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:






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_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);



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:

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 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

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.

Release 6.3 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.



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:

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_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;


Release 6.3 195

os_dbutil

The class os_svr_stat_svr_parameters has the following public data members. (There is no member corresponding to the Failover Script server parameter.)

char* os_release_name;

os_unsigned_int32 server_major_version;

os_unsigned_int32 server_minor_version;

char* compilation;


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;



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:

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

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;


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 */

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_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;



The class os_svr_stat_client_info has the following public data members:

The class os_svr_stat_open_database_info has the following public data members:

The class os_svr_stat_client_process has the following public data members:

The class os_svr_stat_client_state has the following public data members:


os_svr_stat_client_process* process;

os_svr_stat_client_state* state;

os_svr_stat_client_meters* meters;


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


char* host_name;

os_unsigned_int32 process_id;

char* client_name;

os_unsigned_int32 client_id;


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;

Release 6.3 199

os_dbutil

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:

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 };


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;



The class os_svr_stat_extension has the following public data members:

The class os_svr_log_stat_sample has the following public data members:

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;

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;


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;

Release 6.3 201

os_dbutil

Example 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.

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;



os_deadlock_exceptionInstances 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.


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.



os_DLL_finderThis 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.


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_infoThis 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.


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



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_referenceInstances 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;



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.


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*.


os_Dumper_reference ( os_unsigned_int32 database_number, os_unsigned_int32 seg_num, os_unsigned_int32 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.



os_Dumper_specializationThis 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.


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.



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.


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.


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.


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.



os_enum_typeclass 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.




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.



os_enumerator_literalThis class is part of the ObjectStore metaobject protocol (MOP), which provides access to ObjectStore schemas. An instance of this class represents a C++ enumerator.


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_bindingInstances 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.


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.



os_export_idclass 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_cursorAn 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.



os_export_id_cursor::reset()void reset();

Positions the cursor immediately before the first export ID in the cursor’s associated segment.


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_serverclass os_failover_server : public os_server

This class is derived from os_server.



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.



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_variableclass 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.




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.



os_Fixup_dumperThis 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.


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.


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.



os_function_typeclass 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.



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.



os_indirect_typeclass 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_typeclass 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.


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.


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.



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.




os_int64::os_int64() os_int64(os_int64 num);

Constructs a copy of num.


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_typeclass 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


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.



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_literalclass 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.



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.


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.


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;


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;


os_literal::get_wchar_t_value()wchar_t get_wchar_t_value( ) const;




os_literal_template_actual_argclass 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_exceptionInstances 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.


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( );



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_memberThis class is part of the ObjectStore metaobject protocol (MOP), which provides access to ObjectStore schemas. An instance of this class represents a class member.



os_member::Access_modifierThis 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_variableThis 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::FunctionThis 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.


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_



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::PrivateThis enumerator is a possible return value from os_member::get_access( ), indicating private access.



os_member::ProtectedThis enumerator is a possible return value from os_member::get_access( ), indicating protected access.

os_member::PublicThis enumerator is a possible return value from os_member::get_access( ), indicating public access.

os_member::RelationshipThis 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::TypeThis 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::VariableThis 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_functionThis 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.




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};



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.


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 non-const.

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.



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_namespaceThis 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.



os_member_typeThis 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.


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_variableThis 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.




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:

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.

Attribute Value

storage_class os_member_variable::Regular

is_field 0

is_static 0

is_persistent 0



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.


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.



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_mopThis class is part of the ObjectStore metaobject protocol (MOP), which provides access to ObjectStore schemas. The members provided concern the transient schema.



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.



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 union-discriminant 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.



os_named_indirect_typeThis 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_namespaceThis 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.


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.


os_namespace* get_enclosing_namespace();

os_namespace::get_members()os_const_members get_members() const;

Returns the members of the namespace.


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.


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.



os_namespace::set_name()void set_name(const char* name);

Sets the name of the namespace.

Release 6.3 259

os_notification

os_notificationObjects of class os_notification represent notifications for sending and receiving. A notification object embodies a database location (os_soft_pointer), a signed 32-bit 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 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.



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()



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.


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:

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

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::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 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.

Release 6.3 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);



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_cursorAn 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



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.


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.



os_path_to_dataAn 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.



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.



os_pathname_and_segment_numberThis 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.


Programs using this function must include <ostore/compact.hh>.

os_pathname_and_segment_number::database_pathnameconst 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_numberos_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.


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.



os_persistent_to_transient_pointer_managerThe 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 application-specific 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_actionThis 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.


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.)




os_pointer_literalThis 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.


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_typeThis class is part of the ObjectStore metaobject protocol (MOP), which provides access to ObjectStore schemas. An instance of this class represents a C++ pointer-to-member 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.


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.



os_pointer_typeclass 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_pragmaThis 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.



os_rawfs_entryThe 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.



os_rawfs_entry::~os_rawfs_entry()~os_rawfs_entry( );

Frees storage associated with the specified os_rawfs_entry.

os_rawfs_entry::OSU_DATABASEEnumerator 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_DIRECTORYEnumerator 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_LINKEnumerator 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_typeclass 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.



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.



os_recoverThe 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.



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:

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.


-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.

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.



os_recover_optionsThe 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.


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;


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.


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,2073045581].osarchiv"

previous_image "ID: 20021105135831.[2158298816,349657348,2073045217].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.



Member functions

The following functions are public members of the os_recover_options class:

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.

Release 6.3 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() {}


os_recover_options::reset() void reset();




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>&);


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;


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;




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.




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;


Release 6.3 295

os_Reference_cross_session<T>

os_Reference_cross_session<T>::operator –>()T* operator –>( ) const;


os_Reference_cross_session<T>::os_Reference_cross_session()os_Reference_cross_session();


os_Reference_cross_session(T* hard_ptr);


os_Reference_cross_session(os_Reference_cross_session<T> const& ref);


os_Reference_cross_session<T>::resolve()T* resolve( ) const;




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.


Release 6.3 297

os_reference_cross_session



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.



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.



os_reference_internalThis 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;



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;


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);


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.


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



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();


os_reference_internal::resolve()void* resolve( ) const;


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>&);



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.



os_Reference_protected<T>::operator T*()operator T*( ) const;



os_Reference_protected<T>::operator –>()T* operator –>( ) const;



os_Reference_protected<T>::os_Reference_protected()os_Reference_protected();



os_Reference_protected(T* hard_ptr);


os_Reference_protected(os_Reference_protected<T> const& ref);


os_Reference_protected<T>::resolve()T* resolve( ) const;



Release 6.3 305

os_reference_protected_internal

os_reference_protected_internalThis 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. 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;




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. 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.


os_reference_protected_internal::operator ==()os_boolean operator ==( os_reference_protected_internal const& right_arg) const;


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;


os_reference_protected_internal::operator <()os_boolean operator <( os_reference_protected_internal const& right_arg) const;


os_reference_protected_internal::operator >()os_boolean operator >( os_reference_protected_internal const& right_arg) const;


os_reference_protected_internal::operator <=()os_boolean operator <=( os_reference_protected_internal const& right_arg) const;


os_reference_protected_internal::operator >=()os_boolean operator >=( os_reference_protected_internal const& right_arg) const;


os_reference_protected_internal::~os_reference_protected_internal()

~os_reference_protected_internal();




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.


Release 6.3 309

os_reference_type

os_reference_typeclass 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.



os_relationship_member_variableThis 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.


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.


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.



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.



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_replicatorThe 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.



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.



os_replicator::get_status() os_int32 os_replicator::get_status()

Returns the current status of the replica. The possible return values are:

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.


-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.

Release 6.3 317

os_replicator_options

os_replicator_optionsThe 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.


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.


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.



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 non-exclusive 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.


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 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.

Release 6.3 319

os_replicator_options

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();


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_statistic_infoThe 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.


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:

os_replicator_statistic_info::os_replicator_statistic_info()os_replicator_statistic_info();

The constructor function for the os_replicator_statistic_info class.

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.

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.



os_restoreThe 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.



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.



os_restore_optionsThe 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.


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.


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.



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 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.

Release 6.3 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() {}


os_restore_options::reset() void reset();




os_retain_addressThe 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_schemaThis 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.



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.



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_evolutionThis 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.



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.



Programs using this class must include <ostore/ostore.hh>, followed by <ostore/coll.hh> (if used), followed by <ostore/schmevol.hh>.



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.


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.


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.


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&);



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.


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.



Untranslatable pointers and references can be processed by an untranslatable-pointer 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 class-valued members of the given class (in declaration order), after which the transformer for the given class itself is executed.


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:

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.

Enumerator Meaning


phase_level Output information about the phases of schema evolution for each cluster, segment, and database.






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:

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().

Enumerator Meaning


phase_level Output information about the phases of schema evolution for each cluster, segment, and database.






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.



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 untranslatable-pointer 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 class-name@[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.


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( ).



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.



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.



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 255-character 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.



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 255-character limit and copies over the existing path name.



os_schema_install_optionsType 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_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.




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.



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,};


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.



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 };


Returns the locking behavior currently in effect for the specified segment.

For information about the return value, see










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.



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();


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.



• 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();


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.



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






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.



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










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_accessInstances 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_accessThis 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::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::read_write_access.


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_accessThis 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_accessThis 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::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:





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::~os_segment_access()The destructor frees memory associated with the deleted instance of os_segment_access.



os_segment_cursor Instances of the class os_segment_cursor can be used to iterate over segments in a database.




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.


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.



os_serverInstances 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.



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();



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.



os_soft_pointer32_baseThis 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 objectB* 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.



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.


os_soft_pointer32_base::get_database()os_database* get_database( ) const;


os_soft_pointer32_base::get_database_key()char* get_database_key(const char* dump_str);


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. 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.




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;


os_soft_pointer32_base::operator !()os_boolean operator !(void 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_pointer32_base::operator !=()os_boolean operator !=(void const* right_arg) const;

os_boolean operator !=( os_soft_pointer32_base const& right_arg) const;



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_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::operator <=()os_boolean operator <=(void const* right_arg) const;

os_boolean operator <=( os_soft_pointer32_base const& right_arg) const;



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_soft_pointer32_base::~os_soft_pointer32_base()~os_soft_pointer32();


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.



os_soft_pointer64_baseThis 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 objectB* 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.



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


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.


os_soft_pointer64_base::get_database()os_database* get_database( ) const;


os_soft_pointer64_base::get_database_key()char* get_database_key(const char* dump_str);


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. 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.




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;


os_soft_pointer64_base::operator !()os_boolean operator !(void 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_soft_pointer64_base::operator <()os_boolean operator <(void const* right_arg) const;




os_soft_pointer64_base::operator >()os_boolean operator >(void const* right_arg) const;


Release 6.3 379




os_soft_pointer64_base::operator <=()os_boolean operator <=(void const* right_arg) const;




os_soft_pointer64_base::operator >=()os_boolean operator >=(void const* right_arg) const;




os_soft_pointer64_base::~os_soft_pointer64_base()~os_soft_pointer64();


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.



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 soft-pointer 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&);



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;


os_soft_pointer32<T>::operator –>()T* operator –>( ) const;


os_soft_pointer32<T>::os_soft_pointer32()os_soft_pointer32();

Constructs a null soft pointer.


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);




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;


Release 6.3 383


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 soft-pointer 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.



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&);



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;


os_soft_pointer64<T>::operator –>()T* operator –>( ) const;


os_soft_pointer64<T>::os_soft_pointer64()os_soft_pointer64();

Constructs a null soft pointer.


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.



Release 6.3 385


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;




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




os_soft_pointer32<char>class os_soft_pointer32_void : public os_soft_pointer32_base


Release 6.3 389

os_soft_pointer64<char>

os_soft_pointer64<char>class os_soft_pointer64_void : public os_soft_pointer64_base




os_str_convThis 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.


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.



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:

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.

Release 6.3 393

os_string

os_stringInstances 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.



os_string::os_string()os_string();

Constructs a null string.


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_subscriptionObjects 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.



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.



os_templateThis 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::FunctionThis 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::TypeThis enumerator is a possible return value from os_template::get_kind( ), indicating a type template.



os_template_actual_argThis 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.



os_template_formal_argThis 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.



os_template_instantiationThis 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.


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.


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.



os_template_type_formalThis 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_formalThis 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.



os_transactionInstances 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.




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.


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.


static checkpoint(os_transaction*);



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.



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_onlyThis 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::updateThis 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.



os_transaction_hookThis 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.


Programs using this class must include <ostore/ostore.hh>, followed by <ostore/tranhook.hh>.

os_transaction_hook::after_beginThis 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.


os_transaction_hook::after_commitThis enumerator is used as an argument to register_hook( ) to specify that a hook function is to be invoked immediately after each transaction commit.


os_transaction_hook::before_abortThis enumerator is used as an argument to register_hook( ) to specify that a hook function is to be invoked immediately before each transaction abort.


os_transaction_hook::before_checkpointThis 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.


Release 6.3 415

os_transaction_hook

os_transaction_hook::before_commitThis enumerator is used as an argument to register_hook( ) to specify that a hook function is to be invoked immediately before each transaction commit.


os_transaction_hook::before_retryThis 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.


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 Do not abort or commit the current transaction from within a hook function.



os_transformer_bindingInstances 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_typeThis class is part of the ObjectStore metaobject protocol (MOP), which provides access to ObjectStore schemas. Instances of this class represent C++ types.




os_type::Anonymous_indirectThis enumerator indicates a const or volatile type. It is a possible return value from os_type::get_kind( ).

os_type::ArrayThis enumerator indicates an array type. It is a possible return value from os_type::get_kind( ).

os_type::CharThis enumerator indicates a character type. It is a possible return value from os_type::get_kind( ).

os_type::ClassThis enumerator indicates a class. It is a possible return value from os_type::get_kind( ).

os_type::DoubleThis enumerator indicates the type double. It is a possible return value from os_type::get_kind( ).

os_type::EnumThis enumerator indicates an enumeration type. It is a possible return value from os_type::get_kind( ).

os_type::FloatThis enumerator indicates the type float. It is a possible return value from os_type::get_kind( ).

os_type::FunctionThis enumerator indicates a function type. It is a possible return value from os_type::get_kind( ).



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_classThis 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::IntegerThis 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;



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_doubleThis enumerator indicates the type long double. It is a possible return value from os_type::get_kind( ).

os_type::Named_indirectThis 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.



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.



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::PointerThis enumerator indicates a pointer type. It is a possible return value from os_type::get_kind( ).

os_type::Pointer_to_memberThis enumerator indicates a pointer-to-member type. It is a possible return value from os_type::get_kind( ).

os_type::ReferenceThis 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_charThis 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_longThis enumerator indicates the type long. It is a possible return value from os_type::get_kind( ).

os_type::Signed_shortThis 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( )).


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



const part, which would be the result of os_indirect_type::get_target_type( )).

os_type::TypeThis 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::UndefinedThis enumerator indicates a type whose kind cannot be determined. It is a possible return value from os_type::get_kind( ).

os_type::Unsigned_charThis enumerator indicates the type unsigned char. It is a possible return value from os_type::get_kind( ).

os_type::Unsigned_integerThis 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_longThis enumerator indicates the type unsigned long. It is a possible return value from os_type::get_kind( ).

os_type::Unsigned_shortThis enumerator indicates the type unsigned short. It is a possible return value from os_type::get_kind( ).

os_type::VoidThis enumerator indicates the type void. It is a possible return value from os_type::get_kind( ).



os_Type_fixup_infoThis 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.


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_datatype_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_loaderThis 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.


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.



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.


Release 6.3 431

os_Type_info

os_Type_infoThis 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.


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::datatype_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.



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.


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_loaderThis 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.


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.



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.


Release 6.3 435

os_type_template

os_type_templateclass 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.



os_type_template_actual_argclass 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.


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_typeclass 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.



os_typed_pointer_voidInstances 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_typespecInstances 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.



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.



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.





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( );


os_typespec::get_os_unsigned_int32() static os_typespec* get_os_unsigned_int32( );


os_typespec::get_os_unsigned_int64() static os_typespec* get_os_unsigned_int64( );




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.



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.




os_unsigned_int64::os_unsigned_int64() os_unsigned_int64(os_unsigned_uint64 num);

Constructs a copy of num.


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.



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_handlerThis 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.



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 os_path_to_data* handle_ambiguous_void_pointer();virtual os_path_to_data* handle_deleted_sub_object();virtual os_path_to_data* handle_evolved_to_bit_field();virtual os_path_to_data* handle_evolved_to_incompatible_type();virtual os_path_to_data* handle_evolved_to_smaller();virtual os_path_to_data* handle_evolved_to_static();virtual os_path_to_data* 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-to-Member 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.



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.



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.



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.



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 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.

Release 6.3 455

tix_handler

tix_handlerA 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.


Chapter 3System-Supplied Global Functions

Some system-supplied interface functions are not members of any class but are global C++ functions.

Global C++ FunctionsThese 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.



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.


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.



::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);


long os_fetch( const void* obj, const os_member_variable& mem, long& val);


unsigned int os_fetch( const void* obj, const os_member_variable& mem, unsigned int& val);


int os_fetch( const void* obj, const os_member_variable& mem, int& val);


unsigned short os_fetch( const void* obj, const os_member_variable& mem, unsigned short& val

Release 6.3 461

::os_fetch()

);


short os_fetch( const void* obj, const os_member_variable& mem, short& val);


unsigned char os_fetch( const void* obj, const os_member_variable& mem, unsigned char& val);


char os_fetch( const void* obj, const os_member_variable& mem, char& val);


float os_fetch( const void* obj, const os_member_variable& mem, float& val);


double os_fetch( const void* obj, const os_member_variable& mem, double& val);


long double os_fetch( const void* obj, const os_member_variable& mem, long double& 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.



::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);


void os_store( void* obj, const os_member_variable& mem, const long val);


void os_store( void* obj, const os_member_variable& mem, const unsigned int val);


void os_store( void* obj, const os_member_variable& mem, const int val);


void os_store( void* obj, const os_member_variable& mem, const unsigned short val

Release 6.3 465

::os_store()

);


void os_store( void* obj, const os_member_variable& mem, const short val);


void os_store( void* obj, const os_member_variable& mem, const unsigned char val);


void os_store( void* obj, const os_member_variable& mem, const char val);


void os_store( void* obj, const os_member_variable& mem, const float val);


void os_store( void* obj, const os_member_variable& mem, const double val);


void os_store( void* obj, const os_member_variable& mem, const long double val



);


Release 6.3 467

::os_store()


Chapter 4System-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 MacrosThe 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


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 exception-handling 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 {



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)


• 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 user-defined exceptions.

txn-type

This is one of the following enumerators:



- 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 5main( ){

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;}



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.


• $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.



OS_END_FAULT_HANDLER Use this macro with the OS_ESTABLISH_FAULT_HANDLER macro to delimit a fault-handler 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.



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.


• 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



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.


• 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.



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);


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.


• Component schemas, see Component Schemas in Chapter 9 of the C++ A P I User Guide

• The ossg utility, see Managing ObjectStore



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 platform-specific 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.




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.






os_soft_pointerThe 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.


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>



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.


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.



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 handle-exception-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 ) {



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


• $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.



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-blockhandle-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()


Chapter 5Predefined 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:

• 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.

all_exceptions

err_objectstore

err_rpc

General exceptions err_coll

err_mop

err_schema_evolution

err_osbr

err_allocator_framework


Chapter 5: Predefined TIX Exceptions

General ObjectStore ExceptionsThe 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



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


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



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


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.



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 cross-database 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.



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 ExceptionsThe 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 ExceptionsThe 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.



RPC ExceptionsThe 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 ExceptionsThe following exceptions exist:

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”


Release 6.3

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

Aabort()

os_transaction, defined by 409abort_top_level()

os_transaction, defined by 409access control

approaches to 45os_segment_access, the class 362

Access_modifier

os_member, defined by 240acquire_address_space()

objectstore, defined by 54acquire_lock()

objectstore, defined by 54add()

os_path_to_data, defined by 271add_db_to_archive()

os_archiver, defined by 104add_DLL_identifier()

os_DLL_schema_info, defined by 206add_missing_dispatch_table_handler()

objectstore, defined by 57address-space markers, disabling 83affiliate()

os_database, defined by 148affiliation API

os_database::affiliate() 148os_database::change_affiliation() 149os_database::get_affiliated_

databases() 154os_database::get_affiliation_index_

of() 154os_database::get_path_to() 160os_database::has_affiliation_to() 162

after_begin

os_transaction_hook, defined by 415after_checkpoint

os_transaction_hook, defined by 415after_commit

os_transaction_hook, defined by 415allocating storage 459ancestor_of()

tix_exception, defined by 454Anonymous_indirect

os_type, defined by 418Anonymous_union

os_class_type, defined by 119Application_schema

os_schema, defined by 330Array

513

B

os_type, defined by 418assign()

os_notification, defined by 260os_subscription, defined by 396

augment_classes_to_be_recycled()

os_schema_evolution, defined by 335augment_classes_to_be_removed()

os_schema_evolution, defined by 335augment_cluster_split_avoidance()

os_compact, defined by 141os_schema_evolution, defined by 335

augment_dll_schema_db_names()

os_schema_evolution, defined by 335augment_optional_classes()

os_schema_evolution, defined by 336augment_post_compact_transformers()

os_compact, defined by 141augment_post_evol_transformers()

os_schema_evolution, defined by 336authentication

os_authentication 109authorization 362

Bbasic_undo()

basic_undo, defined by 52basic_undo, the class

~basic_undo() 53basic_undo() 52get_exception() data member 52has_exception() data member 52

before_abort

os_transaction_hook, defined by 415before_checkpoint

os_transaction_hook, defined by 415before_commit

os_transaction_hook, defined by 416before_retry

os_transaction_hook, defined by 416begin()

os_transaction, defined by 409binary relationships

modeling 44bind()

os_mop, defined by 254bit_offset()

os_path_to_data, defined by 271byte_offset()

os_path_to_data, defined by 271

Cchange_affiliation()

os_database, defined by 149change_mapping()

os_str_conv, defined by 391change_schema_key()

os_database, defined by 149change_time_interval()

os_archiver, defined by 104os_replicator, defined by 316

change_type()

objectstore, defined by 58Char

os_type, defined by 418checkpoint

os_dbutil::svr_checkpoint() 192os_transaction::checkpoint() 410

checkpoint()

os_transaction, defined by 410chgrp()

os_dbutil, defined by 178chmod()

os_dbutil, defined by 178chown()

os_dbutil, defined by 178Class

os_class_type, defined by 119os_type, defined by 418

class library 47classes, system-supplied

basic_undo 52objectstore 54objectstore_exception 96os_access_modifier 97os_address_space_marker 98os_anonymous_indirect_type 101os_app_schema 102os_application_schema_info 103os_archiver 104os_archiver_options 106os_array_type 108os_authentication 109os_backup 110os_backup_options 112os_base_class 116os_class_type 119


Index

os_close_database 130os_cluster 131os_cluster_cursor 138os_cluster_with 140os_comp_schema 147os_compact 141os_database 148os_database_root 172os_database_schema 175os_Database_table 176os_dbutil 178os_deadlock_exception 203os_DLL_finder 205os_DLL_schema_info 206os_Dumper_reference 208os_Dumper_specialization 211os_dynamic_extent 213os_enum_type 215os_enumerator_literal 217os_evolve_subtype_fun_binding 218os_export_id 219os_export_id_cursor 220os_failover_server 222os_field_member_variable 224os_Fixup_dumper 225os_function_type 227os_indirect_type 229os_instantiated_class_type 230os_int64 231os_integral_type 232os_literal 234os_literal_template_actual_arg 237os_lock_timeout_exception 238os_member 240os_member_function 244os_member_namespace 248os_member_type 249os_member_variable 250os_mop 254os_named_indirect_type 257os_namespace 258os_notification 260os_object_cursor 268os_path_to_data 271os_pathname_and_segment_number 275os_pathname_segment_cluster 276os_persistent_to_transient_pointer_

manager 277

os_Planning_action 278os_pointer_literal 279os_pointer_to_member_type 280os_pointer_type 281os_pragma 282os_rawfs_entry 283os_real_type 286os_recover_options 289os_Reference<T> 293os_reference_cross_session 297os_Reference_cross_session<T> 295os_reference_internal 301os_Reference_protected<T> 304os_reference_protected_internal 306os_reference_type 310os_relationship_member_variable 311os_release_cluster_pointer 312os_release_database_pointer 313os_release_root_pointer 314os_release_segment_pointer 315os_replicator 316os_replicator_options 318os_restore 287, 323os_restore_options 325os_retain_address 329os_schema 330os_schema_evolution 332os_schema_handle 347os_schema_info 350os_schema_install_options 351os_segment 352os_segment_access 362os_segment_cursor 365os_server 367os_session 370os_soft_pointer32<char> 389os_soft_pointer32<T> 381os_soft_pointer32<void> 387os_soft_pointer32_base 373os_soft_pointer64<char> 390os_soft_pointer64<T> 384os_soft_pointer64<void> 388os_soft_pointer64_base 377os_str_conv 391os_string 394os_subscription 396os_template 399os_template_actual_arg 401

Release 6.3 515

C

os_template_formal_arg 403os_template_instantiation 405os_template_type_formal 407os_template_value_formal 408os_transaction 409os_transaction_hook 415os_transformer_binding 417os_type 418os_Type_fixup_info 429os_Type_fixup_loader 430os_Type_info 432os_Type_loader 434os_type_template 436os_type_template_actual_arg 437os_type_type 438os_typed_pointer_void 439os_typespec 440os_unsigned_int64 446os_untranslatable_pointer_handler 448os_void_type 451os_with_ mapped 452tix_context 453tix_exception 454tix_handler 456untranslatable_pointer_handler 448

clear_persistent_to_transient_pointers()

objectstore, defined by 58close()

os_database, defined by 150close_all_connections()

os_dbutil, defined by 179close_all_server_connections()

os_dbutil, defined by 179close_server_connection()

os_dbutil, defined by 179cluster_number

os_pathname_segment_cluster, defined by 276clustering 44

specifying using operator new() 459clusters 44

defaultreturning 354setting 360

iterating over 138transient 133

cmgr_remove_file()

os_dbutil, defined by 179cmgr_shutdown()

os_dbutil, defined by 179cmgr_stat()

os_dbutil, defined by 179collections facility macros 469commit()

os_transaction, defined by 411compact()

os_compact, defined by 142compaction 46compare()

os_string, defined by 394compare_nocase()

os_string, defined by 394compare_schemas()

os_dbutil, defined by 181Compilation_schema

os_schema, defined by 330component schemas

objectstore::enable_damaged_dope_

repair() 59objectstore::enable_DLL_schema() 60objectstore::find_DLL_schema() 61objectstore::get_autoload_DLLs_

function() 65objectstore::is_damaged_dope_repair_

enabled() 75objectstore::is_DLL_schema_enabled() 75objectstore::load_DLL() 76objectstore::set_autoload_DLLs_

function() 83OS_REPORT_DLL_LOAD_AND_UNLOAD(), the

macro 486OS_SCHEMA_DLL_ID(), the macro 487os_schema_info 350OS_SCHEMA_INFO_NAME(), the macro 488

connection_is_broken()

os_server, defined by 367convert()

os_str_conv, defined by 391copy_classes()

os_mop, defined by 255copy_database()

os_dbutil, defined by 182create()

os_access_modifier, defined by 97os_anonymous_indirect_type, defined by 101os_array_type, defined by 108os_base_class, defined by 116


Index

os_class_type, defined by 119os_database, defined by 150os_enum_type, defined by 215os_enumerator_literal, defined by 217os_field_member_variable, defined by 224os_function_type, defined by 227os_instantiated_class_type, defined by 230os_integral_type, defined by 232os_literal_template_actual_arg, defined

by 237os_member_function, defined by 244os_member_namespace, defined by 248os_member_type, defined by 249os_member_variable, defined by 250os_named_indirect_type, defined by 257os_namespace, defined by 258os_pointer_literal, defined by 279os_pointer_to_member_type, defined by 280os_pointer_type, defined by 281os_pragma, defined by 282os_real_type, defined by 286os_reference_type, defined by 310os_session, defined by 370os_template_instantiation, defined by 405os_template_type_formal, defined by 407os_template_value_formal, defined by 408os_Type_loader, defined by 434os_type_template, defined by 436os_type_template_actual_arg, defined by 437os_void_type, defined by 451

create_char()

os_literal, defined by 234create_cluster()

os_segment, defined by 352create_defaulted_char()

os_integral_type, defined by 232create_double()

os_real_type, defined by 286create_enum_literal()

os_literal, defined by 234create_float()

os_real_type, defined by 286create_int()

os_integral_type, defined by 232create_long()

os_integral_type, defined by 232create_long_double()

os_real_type, defined by 286

create_pointer_literal()

os_literal, defined by 234create_root()

os_database, defined by 152create_segment()

os_database, defined by 152create_short()

os_integral_type, defined by 233create_signed_char()

os_integral_type, defined by 233os_literal, defined by 234

create_signed_int()

os_literal, defined by 234create_signed_long()

os_literal, defined by 234create_signed_short()

os_literal, defined by 234create_unsigned_char()

os_integral_type, defined by 233os_literal, defined by 234

create_unsigned_int()

os_literal, defined by 235create_unsigned_long()

os_literal, defined by 235create_unsigned_short()

os_literal, defined by 235create_wchar_t()

os_literal, defined by 235creating objects 459cross-database pointers

affiliating databases 148getting list of affiliated databases 154retrieving path to affiliated database 160

cross-transaction pointersdisabling 81enabling 81

current()

os_mop, defined by 255os_object_cursor, defined by 268

Ddata

os_Type_info, defined by 432data member pairs 44database access control 362database fragmention

os_database::get_fragmentation() 157database permissions 362

Release 6.3 517

E

database utility API 178database_of()

os_cluster, defined by 131os_segment, defined by 352

database_pathname

os_pathname_and_segment_number, defined by 275

os_pathname_segment_cluster, defined by 276Database_schema

os_schema, defined by 330databases

and persistent data 148decache()

os_soft_pointer32_base, defined by 373os_soft_pointer64_base, defined by 377

decaching soft pointers 86DECLARE_EXCEPTION() macro

objectstore_exception, the class 96DECLARE_EXCEPTION(), the macro 471declares_get_os_typespec_function()

os_class_type, defined by 120default cluster

in a segment 131returning 354setting 360

default segmentreturning 156setting 168

DEFINE_EXCEPTION() macroobjectstore_exception, the class 96

DEFINE_EXCEPTION(), the macro 472defines_virtual_functions()

os_class_type, defined by 120delete, the operator 458deregister_hook()

os_transaction_hook, defined by 416destroy()

os_cluster, defined by 131os_database, defined by 153os_database_root, defined by 172os_segment, defined by 352

destructors and exceptions 52disconnect()

os_server, defined by 368disk_free()

os_dbutil, defined by 182DLL_loaded()

os_DLL_schema_info, defined by 206

DLL_unloaded()

os_DLL_schema_info, defined by 207os_schema_handle, defined by 347

Double

os_type, defined by 418dump()

os_reference_cross_session, defined by 298os_reference_internal, defined by 301os_reference_protected_internal, defined

by 306os_soft_pointer32_base, defined by 373os_soft_pointer64_base, defined by 377

dump_info()

os_Fixup_dumper, defined by 225duplicate()

os_Fixup_dumper, defined by 225

Eembedded_server_available()

objectstore, defined by 59enable_damaged_dope_repair()

objectstore, defined by 59enable_DLL_schema()

objectstore, defined by 60entry points 172Enum

os_type, defined by 418enumerators

Namespace 241no_access 362objectstore::lock_as_used 76objectstore::lock_cluster_read 77objectstore::lock_cluster_write 77objectstore::lock_database_read 77objectstore::lock_database_write 77objectstore::lock_page_write 78objectstore::lock_segment_read 78objectstore::lock_segment_write 78objectstore::os_no_lock 54objectstore::os_read_lock 54objectstore::os_write_lock 54objectstore::own_page_write 79os_allocation_strategy_least_space 63os_allocation_strategy_least_wait 63os_base_class::Private 117os_base_class::Protected 117os_base_class::Public 117os_class_type::Anonymous_union 119


Index

os_class_type::Class 119os_class_type::Struct 129os_class_type::Union 129os_dbutil::os_svr_ping_is_alive 194os_dbutil::os_svr_ping_no_such_host 194os_dbutil::os_svr_ping_not_reachable 194os_fetch_cluster 67os_fetch_page 67os_fetch_stream 67os_formal_actual_arg::Value 403os_function_type::Known 227os_function_type::Unknown 227os_function_type::Variable 227os_member::Access_modifier 240os_member::Field_variable 240os_member::Function 240os_member::Namespace 241os_member::Private 242os_member::Protected 243os_member::Public 243os_member::Relationship 243os_member::Type 243os_member::Variable 243os_rawfs_entry::OSU_DATABASE 285os_rawfs_entry::OSU_DIRECTORY 285os_rawfs_entry::OSU_LINK 285os_segment_access::no_access 362os_segment_access::read_access 363os_segment_access::read_write_access 363os_svr_stat::get_client_info_others 195os_svr_stat::get_svr_meter_samples 195os_svr_stat::get_svr_parameters 195os_svr_stat::get_svr_usage 195os_template::Function 399os_template::Type 400os_template_actual_arg::literal_

actual 401os_template_actual_arg::type_actual 401os_template_formal_arg::Typel 403os_transaction::read_only 413os_transaction::update 414os_transaction_hook::after_begin 415os_transaction_hook::after_commit 415os_transaction_hook::before_abort 415os_transaction_hook::before_commit 415,

416os_transaction_hook::before_retry 416os_type::Anonymous_indirect 418

os_type::Array 418os_type::Char 418os_type::Class 418os_type::Double 418os_type::Enum 418os_type::Float 418os_type::Function 418os_type::Instantiated_class 420os_type::Integer 420os_type::Long_double 421os_type::Named_indirect 421os_type::Pointer 425os_type::Pointer_to_member 425os_type::Reference 425os_type::Signed_char 425os_type::Signed_long 426os_type::Signed_short 426os_type::Type 427os_type::Undefined 427os_type::Unsigned_char 427os_type::Unsigned_integer 427os_type::Unsigned_long 428os_type::Unsigned_short 428os_type::Void 428OSU_DATABASE 285OSU_DIRECTORY 285OSU_LINK 285read_access 363read_write_access 363

equal_DLL_identifiers()

os_DLL_finder, defined by 205equal_DLL_identifiers_same_prefix()

os_DLL_finder, defined by 205equal_signature()

os_function_type, defined by 227err_abort_committed exception 501err_address_space_full exception 501

objectstore::acquire_address_space() 54objectstore::set_default_address_space_

partition_size() 87os_session::create() 370os_session::force_full_

initialization() 370err_alignment exception 501err_architecture_mismatch exception 501err_authentication_failure exception 501err_awaiting_recovery exception 501err_beyond_segment_length exception 501

Release 6.3 519

E

err_broken_connection exceptionos_dbutil::svr_ping() 194

err_broken_server_connection exception 501handling with os_server 367os_transaction::prepare_to_commit() 412

err_cache_manager_not_responding exception 501

err_cannot_commit exception 501err_cannot_open_application_schema

exception 501err_cannot_shrink_cluster exception 501

os_cluster::set_size() 136err_checkpoint_aborted exception 502err_checkpoint_committed exception 502err_checkpoint_not_inner exception 502err_cluster_full exception

described 502os_cluster, the class 459os_cluster_with, the class 140

err_cluster_is_deleted exceptiondescribed 502os_cluster::destroy() 131

err_cluster_mismatch exception 502err_cluster_transient exception 502err_commit_abort_only exception 502err_commit_aborted exception 502err_commit_with_children exception 502err_conflicting_failover_configuration

exception 502err_connection_closed exception 502err_cross_db_pointer exception 502err_cross_server_rename exception

os_dbutil::rename() 190err_cursor_at_end exception 502err_cursor_not_at_object exception 502err_database_exists exception 502

os_database::create() 151os_dbutil::make_link() 184os_dbutil::mkdir() 185os_dbutil::rename() 190

err_database_is_deleted exception 502returned by os_database::destroy() 153

err_database_lock_conflict exception 502err_database_not_found exception 502

returned by os_database::destroy() 153returned by os_database::lookup() 163returned by os_database::open() 164

err_database_not_open exception 502

objectstore::set_auto_open_mode() 84os_database::create_root() 152

err_database_not_open_update exception 502err_database_segment exception

returned by os_database::create_segment() 152

err_database_transient exception 502err_database_wrong_version exception 502err_datagram_error exception 503err_db_already_open_multi_db_mvcc

exception 503err_db_already_open_single_db_mvcc

exception 503err_db_cannot_change_open exception 503

returned by os_database::open() 164err_db_going_offline exception 503err_db_is_offline exception 503err_db_kill_clients_failed exception 503err_deadlock exception 503

objectstore::acquire_lock() 55os_transaction::prepare_to_commit() 412tix_exception::release_pointer() 454tix_exception::set_unhandled_exception_

hook() 455err_default_cluster exception 503err_default_segment exception 503err_deref_transient_pointer exception 503err_directory_exists exception 503

os_dbutil::make_link() 184os_dbutil::mkdir() 185os_dbutil::rename() 190

err_directory_not_empty exception 503os_dbutil::rmdir() 190

err_directory_not_found exception 503os_dbutil::mkdir() 185

err_DLL_not_loaded exceptionobjectstore::find_DLL_schema() 61objectstore::load_DLL() 76

err_DLL_not_unloaded exceptionobjectstore::unload_DLL() 94

err_DLL_symbol_not_found exceptionobjectstore::lookup_DLL_symbol() 78

err_explicit_commit_stack_txn exception 503err_file_error exception 503

os_dbutil::remove() 190err_file_not_db exception 503err_file_not_local exception 504

os_dbutil::remove() 190


Index

err_file_pathname exception 504err_hardware exception 504err_illegal_acquire_lock exception 504err_illegal_pointer exception

returned by os_schema_evolution::evolve() 339

err_inconsistent_db exception 504err_indigestible_pna exception 504err_insufficient_virtual_memory

exception 504err_internal exception 504

objectstore::set_cache_file() 85err_invalid_deletion exception 504

delete operator 458err_invalid_for_application_schema exception

os_schema_handle::DLL_unloaded() 347err_invalid_pathname exception 504err_invalid_pathname_encoding exception 90err_invalid_rename exception

os_dbutil::rename() 190err_invalid_root_value exception 504

os_database_root::set_value() 174err_license_limit exception 504err_link_not_found exception 504err_locator_file_id exception 504err_locator_misc exception

objectstore::set_locator_file() 88err_locator_read_only exception 504err_locator_syntax exception 504err_lock_timeout exception 504

tix_exception::release_pointer() 454err_log_data_segment_full exception

described 505err_misc exception

described 505objectstore::acquire_address_space() 54objectstore::initialize_for_

sessions() 73objectstore::set_default_address_space_

partition_size() 87os_database::size() 171os_database::size_in_sectors() 171os_dbutil::cmgr_stat() 180os_dbutil::disk_free() 182os_dbutil::svr_stat() 195os_schema_info::get() 350os_segment, the class 459os_server class 367

os_session::create() 370err_mop exception 509

os_class_type::get_dispatch_table_

pointer_offset() 122os_class_type::get_dispatch_table_

pointer_offset_other_compiler() 122os_class_type::get_most_derived_

class() 123os_member_variable::get_offset() 250os_member_variable::get_size() 250os_member_variable::set_offset() 252os_void_type, the class 451

err_mop_cannot_neutralize exceptionos_mop::bind() 254os_mop::get_failure_classes() 255os_mop::get_neutralized_classes() 255

err_mop_forward_definition exception 509os_class_type::find_base_class() 120os_class_type::find_member_

variable() 120os_class_type::get_base_classes() 121os_class_type::get_indirect_virtual_

base_classes() 122os_class_type::get_members() 123

err_mop_illegal_cast exception 509os_class_type::operator os_instantiated_

class_type&() 127os_member operators 241os_member_variable operators 252os_schema operators 330os_template operators 399, 400os_template_actual_arg operators 401os_template_formal_arg operators 403os_type operators 421

err_mop_not_neutral exceptionos_mop::bind() 254

err_mvcc_incoherent exceptiondescribed 505

err_mvcc_nested exception 505returned by os_database::open_mvcc() 166

err_net_cant_connect exception 505err_net_connect_timeout exception 505err_net_connection_refused exception 505err_net_host_down exception 505err_net_no_server exception 505err_network exception 505err_network_failure exception 505err_no_credentials exception 505

Release 6.3 521

E

err_no_query_trans exception 505err_no_rawfs exception 505err_no_schema exception

os_app_schema::get() 102os_database_schema::get() 175os_database_schema::get_for_update() 175

err_no_service_on_net exception 505err_no_session exception

objectstore::acquire_address_space() 54objectstore::initialize_for_

sessions() 74os_segment::get_current() 371

err_no_such_host exception 506err_no_trans exception 506err_not_a_database exception 506

os_dbutil::remove() 190err_not_a_directory exception 506

os_dbutil::list_directory() 184os_dbutil::rmdir() 190

err_not_a_link exceptionos_dbutil::rehost_link() 189

err_not_assigned exception 506err_not_auth_db_kill exception 506err_not_supported exception

objectstore::propagate_log() 79err_null_pointer exception 506err_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() 166err_operation_not_supported exception 506err_operator_new_args exception 506err_os_auth_reg_string_array_too_small

exception 506thrown by os_authentication::get_nt_

registry_location() 109err_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 506err_os_query_evaluation_error exception

returned by os_schema_

evolution::evolve() 339err_osbr_all_exceptions exception 509err_osbr_cant_open_db exception 509err_osbr_cant_open_exclusive exception 509err_osbr_directory_not_found exception 509err_osbr_incomplete_backup_data

exception 509err_osbr_invalid_backup_data exception 509err_osbr_misc exception 509err_osbr_not_supported exception 509err_osbr_path_exists exception 510err_osbr_restore_deadlocked exception 509err_osbr_sync_timed_out exception 509err_permission_denied exception 506err_prepare_to_commit exception 506

os_transaction::prepare_to_commit() 413err_protocol_not_supported exception 506err_rawfs_not_upgraded exception 506err_read_only_file_system exception 506err_reference_not_found exception 507err_reference_syntax exception

described 507os_reference_cross_session::load() 298os_reference_internal::get_database_

key() 301os_reference_internal::load() 302os_reference_protected::get_database_

key() 307os_reference_protected_

internal::load() 307os_soft_pointer32_base::get_database_

key() 374os_soft_pointer32_base::load() 375os_soft_pointer64_base::get_database_

key() 378os_soft_pointer64_base::load() 379

err_reference_to_transient exception 507err_restartable exception 507err_root_exists exception 507

os_database::create_root() 152err_rpc_auth_badcred exception 511err_rpc_auth_badverf exception 511err_rpc_auth_failed exception 511err_rpc_auth_invalidresp exception 511err_rpc_auth_ok exception 511err_rpc_auth_rejectedcred exception 511err_rpc_auth_rejectedverf exception 511err_rpc_auth_tooweak exception 511


Index

err_rpc_autherror exception 511err_rpc_cantdecodeargs exception 511err_rpc_cantdecoderes exception 511err_rpc_cantencodeargs exception 511err_rpc_cantrecv exception 511err_rpc_cantsend exception 511err_rpc_failed exception 511err_rpc_pmapfailure exception 511err_rpc_procunavail exception 511err_rpc_prognotregistered exception 511err_rpc_progunavail exception 511err_rpc_progversmismatch exception 511err_rpc_success exception 511err_rpc_systemerror exception 511err_rpc_timedout exception 511err_rpc_unknownhost exception 511err_rpc_unknownproto exception 512err_rpc_versmismatch exception 512err_schema_database exception 507

os_database::create() 151os_database::open() 165os_database::set_schema_database() 170

err_schema_evolution exceptionreturned by os_schema_

evolution::evolve() 339err_schema_key exception

objectstore::set_current_schema_key() 86os_database::change_schema_key() 150returned by os_database::freeze_schema_

key() 154err_schema_not_found exception

objectstore::find_DLL_schema() 61err_schema_not_loaded exception

os_schema_handle::get() 347err_schema_validation_error exception 507err_schema_validation_failed exception 507err_se_ambiguous_subtype_evolution

exception 508err_se_ambiguous_void_pointer exception 508err_se_cannot_delete_class exception 508

returned by os_schema_evolution::augment_classes_to_be_removed() 335

err_se_cross_database_pointer exception 508err_se_deleted_component exception 508err_se_deleted_object exception 509err_se_illegal_pointer exception 509err_se_invalid_subtype_evolution

exception 509

err_se_pointer_type_mismatch exception 509err_se_transient_object exception 509err_se_unnecessary exception 509err_segment_is_deleted exception 507

os_segment::destroy() 352err_segment_transient exception 507

os_segment::create_cluster() 352err_server_address_in_use exception 507err_server_cannot_open_cache exception 507err_server_full exception 507

os_transaction::prepare_to_commit() 412err_server_not_superuser exception 507err_server_refused_connection exception 507

os_server::reconnect() 369err_server_restarted exception 507err_string_too_long exception 507err_too_many_cross_svr_links exception 507err_too_many_links exception 507err_too_many_retries exception 507err_trans exception 508

os_server::disconnect() 368os_transaction::is_lock_contention() 412

err_trans_wrong_type exception 508err_transient_pointer exception 508err_typespec_mismatch exception 508err_uninitialized exception 508err_unknown_pointer exception 508err_user_aborted_simple_authentication

exception 508err_write_during_query exception 508err_write_permission_denied exception 508evolve()

os_schema_evolution, defined by 337example programs

DEFINE_EXCEPTION(), the macro 472OS_BEGIN_TXN(), the macro 475TIX_HANDLE(), the macro 495

exception facility classesbasic_undo 52objectstore_exception 96tix_context 453tix_exception 454tix_handler 456

exceptionsSee also TIX exceptionsaction when no handler for 96ancestor 454database copy 509

Release 6.3 523

E

descendant 454destructors invoked 52err_abort_committed 501err_address_space_full 501err_alignment 501err_all_exceptions 509err_architecture_mismatch 501err_authentication_failure 501err_awaiting_recovery 501err_beyond_segment_length 501err_broken_connection 194err_broken_server_connection 501err_cache_manager_not_responding 501err_cannot_commit 501err_cannot_open_application_schema 501err_cannot_shrink_cluster 501err_checkpoint_aborted 502err_checkpoint_committed 502err_checkpoint_not_inner 502err_cluster_full 502err_cluster_is_deleted 502err_cluster_mismatch 502err_cluster_transient 502err_commit_abort_only 502err_commit_aborted 502err_commit_with_children 502err_conflicting_failover_

configuration 502err_connection_closed 502err_cross_db_pointer 502err_cross_server_rename 190err_cursor_at_end 502err_cursor_not_at_object 502err_database_exists 502err_database_is_deleted 502err_database_lock_conflict 502err_database_not_found 502err_database_not_open 502err_database_not_open_update 502err_database_segment 152err_database_transient 502err_database_wrong_version 502err_datagram_error 503err_db_already_open_multi_db_mvcc 503err_db_already_open_single_db_mvcc 503err_db_cannot_change_open 503err_db_going_offline 503err_db_is_offline 503

err_db_kill_clients_failed 503err_deadlock 503err_default_cluster 503err_default_segment 503err_deref_transient_pointer 503err_directory_exists 503err_directory_not_empty 503err_directory_not_found 503err_DLL_not_loaded 61err_DLL_not_unloaded 94err_DLL_symbol_not_found 78err_explicit_commit_stack_txn 503err_file_error 503err_file_not_db 503err_file_not_local 504err_file_pathname 504err_hardware 504err_illegal_acquire_lock 504err_illegal_pointer 339err_inconsistent_db 504err_indigestible_pna 504err_insufficient_virtual_memory 504err_internal 504err_invalid_deletion 504err_invalid_for_application_schema 347err_invalid_pathname 504err_invalid_pathname_encoding 90err_invalid_rename 190err_invalid_root_value 504err_license_limit 504err_link_not_found 504err_locator_file_id 504err_locator_misc 88err_locator_read_only 504err_locator_syntax 504err_lock_timeout 504err_log_data_segment_full 505err_misc 505err_mop 509err_mop_cannot_neutralize 254err_mop_forward_definition 509err_mop_illegal_cast 509err_mop_not_neutral 254err_mvcc_incoherent 505err_mvcc_nested 505err_net_cant_connect 505err_net_connect_timeout 505err_net_connection_refused 505


Index

err_net_host_down 505err_net_no_server 505err_network 505err_network_failure 505err_no_credentials 505err_no_query_trans 505err_no_rawfs 505err_no_schema 102err_no_service_on_net 505err_no_session 54err_no_such_host 506err_no_trans 506err_not_a_database 506err_not_a_directory 506err_not_a_link 189err_not_assigned 506err_not_auth_db_kill 506err_not_supported 79err_null_pointer 506err_opened_read_only 149, 154err_operation_not_supported 506err_operator_new_args 506err_os_auth_reg_string_array_too_

small 506err_os_auth_reg_string_invalid 506err_os_auth_reg_string_too_long 506err_os_compaction 506err_os_query_evaluation_error 339err_osbr_ path_exists 510err_osbr_cant_open_db 509err_osbr_cant_open_exclusive 509err_osbr_directory_not_found 509err_osbr_invalid_backup_data 509err_osbr_misc 509err_osbr_not_supported 509err_osbr_restore_deadlocked 509err_osbr_sync_timed_out 509err_permission_denied 506err_prepare_to_commit 506err_protocol_not_supported 506err_rawfs_not_upgraded 506err_read_only_file_system 506err_reference_not_found 507err_reference_syntax 507err_reference_to_transient 507err_restartable 507err_root_exists 507err_rpc_auth_badcred 511

err_rpc_auth_badverf 511err_rpc_auth_failed 511err_rpc_auth_invalidresp 511err_rpc_auth_ok 511err_rpc_auth_rejectedcred 511err_rpc_auth_rejectedverf 511err_rpc_auth_tooweak 511err_rpc_autherror 511err_rpc_cantdecodeargs 511err_rpc_cantdecoderes 511err_rpc_cantencodeargs 511err_rpc_cantrecv 511err_rpc_cantsend 511err_rpc_failed 511err_rpc_pmapfailure 511err_rpc_procunavail 511err_rpc_prognotregistered 511err_rpc_progunavail 511err_rpc_progversmismatch 511err_rpc_success 511err_rpc_systemerror 511err_rpc_timedout 511err_rpc_unknownhost 511err_rpc_unknownproto 512err_rpc_versmismatch 512err_schema_database 507err_schema_evolution 339err_schema_key 86, 150err_schema_not_found 61err_schema_not_loaded 347err_schema_validation_error 507err_schema_validation_failed 507err_se_ambiguous_subtype_evolution 508err_se_ambiguous_void_pointer 508err_se_cannot_delete_class 508err_se_cross_database_pointer 508err_se_deleted_component 508err_se_deleted_object 509err_se_illegal_pointer 509err_se_invalid_subtype_evolution 509err_se_pointer_type_mismatch 509err_se_transient_object 509err_se_unnecessary 509err_segment_is_deleted 507err_segment_transient 507err_server_address_in_use 507err_server_cannot_open_cache 507err_server_full 507

Release 6.3 525

F

err_server_not_superuser 507err_server_refused_connection 507err_server_restarted 507err_string_too_long 507err_too_many_cross_svr_links 507err_too_many_links 507err_too_many_retries 507err_trans 508err_trans_wrong_type 508err_transient_pointer 508err_typespec_mismatch 508err_uninitialized 508err_unknown_pointer 508err_user_aborted_simple_

authentication 508err_write_during_query 508err_write_permission_denied 508general ObjectStore 501handling 469metaobject protocol 509ObjectStore internal errors 494parent 454predefined 499remote procedure call (RPC) mechanism 511schema evolution 508signaling 96

expand_global()

os_dbutil, defined by 182export_object()

objectstore, defined by 60

Ffault handler macros

OS_END_FAULT_HANDLER 479OS_END_TXN() 480OS_ESTABLISH_FAULT_HANDLER 481

Field_variable

os_member, defined by 240file_db_pathname()

os_dbutil, defined by 183find()

os_database_root, defined by 172find_base_class()

os_class_type, defined by 120find_DLL_schema()

objectstore, defined by 61find_member_variable()

os_class_type, defined by 120

find_namespace()

os_mop, defined by 255find_reference()

os_Database_table, defined by 176find_root()

os_database, defined by 153find_type()

os_mop, defined by 255os_schema, defined by 330

first()

os_object_cursor, defined by 268fixup()

os_Type_fixup_loader, defined by 430os_Type_loader, defined by 434

fixup_data

os_Type_fixup_info, defined by 429Float

os_type, defined by 418force_full_initialization()

os_session, defined by 370format_and_print_statistics()

os_replicator_statistic_info, defined by 322

format_statistics()


fragmentationos_cluster::set_size() 136os_database::get_fragmentation() 157os_database::set_size() 170os_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 61freeze_schema_key()

os_database, defined by 153Function

os_member, defined by 240os_template, defined by 399


Index

os_type, defined by 418

Gget()

os_app_schema, defined by 102os_cluster_with, defined by 140os_comp_schema, defined by 147os_database_schema, defined by 175os_Database_table, defined by 176os_DLL_finder, defined by 205os_schema_handle, defined by 347os_schema_info, defined by 350os_Type_fixup_loader, defined by 430os_Type_loader, defined by 434

get_abs_path()

os_rawfs_entry, defined by 283get_access()

os_base_class, defined by 116os_member, defined by 240

get_access_control()

os_segment, defined by 352get_access_of_get_os_typespec_function()

os_class_type, defined by 121get_address_space_generation_number()

objectstore, defined by 62get_affiliated_databases()

os_database, defined by 154get_affiliation_index_of()

os_database, defined by 154get_alignment()

os_type, defined by 419get_all()

os_schema_handle, defined by 347get_all_clusters()

os_segment, defined by 353get_all_databases()

os_database, defined by 154get_all_roots()

os_database, defined by 155get_all_segments()

os_database, defined by 155get_all_segments_and_permissions()

os_database, defined by 155get_all_servers()

objectstore, defined by 62get_all_sessions()

os_session, defined by 370get_allocated_virtual_base_classes()

os_class_type, defined by 121get_allocation_strategy()

objectstore, defined by 62os_cluster, defined by 131os_database, defined by 156os_segment, defined by 353

get_always_check_server_connection_at_

commit()

objectstore, defined by 63get_application_info()

os_database, defined by 156os_segment, defined by 353

get_application_names()

os_deadlock_exception, defined by 203os_lock_timeout_exception, defined by 238

get_application_schema_handle()

os_schema_handle, defined by 348get_application_schema_pathname()

objectstore, defined by 64get_arg_list()

os_function_type, defined by 227get_arg_list_kind()

os_function_type, defined by 227get_args()

os_template, defined by 399os_template_instantiation, defined by 405

get_as_intervals()

objectstore, defined by 64get_asmarkers_useless()

objectstore, defined by 64get_auto_open_mode()

objectstore, defined by 64get_autoload_DLLs_function()

objectstore, defined by 64get_base_classes()

os_class_type, defined by 121get_base_member()

os_access_modifier, defined by 97get_cache_file()

objectstore, defined by 65get_cache_size()

objectstore, defined by 65get_call_linkage()

os_member_function, defined by 244get_char()

os_typespec, defined by 440get_char_value()

os_literal, defined by 235

Release 6.3 527

G

get_class()

os_base_class, defined by 116get_class_kind()

os_class_type, defined by 122get_classes()

os_schema, defined by 330get_client_name()

objectstore, defined by 65os_dbutil, defined by 183

get_cluster()

os_segment, defined by 353get_clusters()

os_segment, defined by 354get_comment()

os_segment, defined by 354get_converted_size()

os_str_conv, defined by 392get_copy_member_functions()

os_schema_install_options, defined by 351get_creation_time()

os_rawfs_entry, defined by 283get_current()

os_address_space_marker, defined by 99os_cluster_cursor, defined by 138os_export_id_cursor, defined by 220os_segment_cursor, defined by 365os_session, defined by 370os_transaction, defined by 411tix_handler, defined by 456

get_current_archive_file_name()

os_archiver, defined by 104get_database()

os_Dumper_reference, defined by 208os_notification, defined by 260os_reference_cross_session, defined by 298os_reference_internal, defined by 301os_reference_protected_internal, defined

by 306os_soft_pointer32_base, defined by 374os_soft_pointer64_base, defined by 378os_subscription, defined by 397

get_database_key()

os_reference_internal, defined by 301os_reference_protected_internal, defined


get_database_number()

os_Dumper_reference, defined by 208get_databases()

os_server, defined by 368get_decache_soft_pointers_after_address_

space_release()

objectstore, defined by 65get_default()

os_segment_access, defined by 362get_default_cluster()

os_segment, defined by 354get_default_partition_size()

objectstore, defined by 65get_default_segment()

os_database, defined by 156get_defining_class()

os_member, defined by 240get_dispatch_table_pointer_offset()

os_class_type, defined by 122get_dispatch_table_pointer_offset_other_

compiler()

os_class_type, defined by 122get_DLL_identifiers()

os_schema_handle, defined by 348os_schema_info, defined by 350

get_double()

os_typespec, defined by 440get_element_type()

os_array_type, defined by 108get_enclosing_class()

os_type, defined by 419get_enclosing_namespace()

os_namespace, defined by 258get_enclosing_object()

os_schema_evolution, defined by 340get_enum_literal()

os_literal, defined by 235get_enumerator()

os_enum_type, defined by 215get_enumerators()

os_enum_type, defined by 215get_evolved_schema()

os_schema_evolution, defined by 340get_evolved_schema_db_name()

os_schema_evolution, defined by 340get_exception()

basic_undo, defined by 52os_untranslatable_pointer_handler, defined

by 448


Index

tix_handler, defined by 456get_explanation()


get_explanation_level()

os_schema_evolution, defined by 340get_export_id()

objectstore, defined by 66get_export_ids()

os_segment, defined by 355get_failure_classes()

os_mop, defined by 255get_fault_addr()


_get_fd()

os_notification, defined by 260get_fetch_policy()


get_file_host_name()

os_database, defined by 157get_final_offset()


get_float()

os_typespec, defined by 440get_for_update()

os_database_schema, defined by 175get_fragmentation()

os_database, defined by 157get_function_kind()

os_member_function, defined by 244get_group_name()

os_rawfs_entry, defined by 283get_high()

os_int64, defined by 231os_unsigned_int64, defined by 446

get_host_name()

os_database, defined by 158os_server, defined by 368

get_hostnames()


get_incremental_schema_installation()


os_database, defined by 158get_indirect_virtual_base_classes()

os_class_type, defined by 122get_instantiation()

os_instantiated_class_type, defined by 230get_int()

os_typespec, defined by 440get_kind()

os_literal, defined by 235os_member, defined by 240os_notification, defined by 260os_schema, defined by 330os_template, defined by 399os_template_actual_arg, defined by 401os_template_formal_arg, defined by 403os_type, defined by 419

get_kind_string()

os_type, defined by 420get_level()

os_address_space_marker, defined by 99get_link_host()

os_rawfs_entry, defined by 283get_link_path()

os_rawfs_entry, defined by 283get_literal()

os_literal_template_actual_arg, defined by 237

get_location()

os_notification, defined by 261get_locator_file()

objectstore, defined by 67get_lock_option()


get_lock_status()

objectstore, defined by 68get_lock_timeout()

objectstore, defined by 68get_lock_type()


get_log_file()

objectstore, defined by 69get_logical_server_hostname()

os_failover_server, defined by 222get_long()

Release 6.3 529

G

os_typespec, defined by 441get_long_double()

os_typespec, defined by 441get_low()


get_members()

os_class_type, defined by 123os_namespace, defined by 258

get_most_derived_class()

os_class_type, defined by 123get_n_clusters()

os_segment, defined by 356get_n_databases()

os_database, defined by 159os_server, defined by 368

get_n_roots()

os_database, defined by 159get_n_sectors()

os_rawfs_entry, defined by 283get_n_segments()

os_database, defined by 159get_n_servers()

objectstore, defined by 69get_n_sessions()

os_session, defined by 371get_name()

os_class_type, defined by 125os_database_root, defined by 172os_enum_type, defined by 215os_enumerator_literal, defined by 217os_member_function, defined by 245os_member_variable, defined by 250os_named_indirect_type, defined by 257os_namespace, defined by 258os_pointer_literal, defined by 279os_rawfs_entry, defined by 283os_session, defined by 371os_template_formal_arg, defined by 403os_transaction, defined by 411os_typespec, defined by 441

get_namespace()

os_member_namespace, defined by 248get_neutralized_classes()

os_mop, defined by 255get_new_segment_reference_policy()

os_database, defined by 159get_next()

os_address_space_marker, defined by 99get_nt_registry_location()

os_authentication, defined by 109get_null_illegal_pointers()


get_number()


get_number_elements()

os_Fixup_dumper, defined by 225get_number_of_elements()

os_array_type, defined by 108get_object_range()

objectstore, defined by 69get_object_to_fix()

os_Fixup_dumper, defined by 225get_offset()

os_base_class, defined by 116os_Dumper_reference, defined by 208os_field_member_variable, defined by 224os_member_variable, defined by 250

get_online_server_hostname()

os_failover_server, defined by 222get_open_database()

os_reference_internal, defined by 302os_soft_pointer32_base, defined by 374os_soft_pointer64_base, defined by 378

get_open_mode()

os_database, defined by 160get_original_location()

os_Type_info, defined by 432get_os_deadlock_exception()

tix_exception, defined by 454get_os_int16()

os_typespec, defined by 441get_os_int64()

os_typespec, defined by 441get_os_int32()

os_typespec, defined by 441get_os_lock_timeout_exception()

tix_exception, defined by 454get_os_signed_int8()

os_typespec, defined by 442get_os_typespec()

defined by user-defined class 440


Index

os_Reference<T>, defined by 293os_Reference_cross_session<T>, defined

by 295os_Reference_protected<T>, defined by 304

get_os_unsigned_int16()

os_typespec, defined by 442get_os_unsigned_int32()



os_typespec, defined by 442get_page_size()

objectstore, defined by 70get_parent()

os_transaction, defined by 411get_path_to()

os_database, defined by 160get_path_to_member()

os_schema_evolution, defined by 340get_pathname()

os_database, defined by 160get_permission()

os_rawfs_entry, defined by 283get_pids()


get_pointer()

os_typespec, defined by 443get_pointer_literal()

os_literal, defined by 236get_pointer_numbers()

objectstore, defined by 70get_pragmas()

os_class_type, defined by 125os_enum_type, defined by 215

get_previous()

os_address_space_marker, defined by 99get_primary_group()

os_segment_access, defined by 362get_propagate_on_commit()

objectstore, defined by 70get_reconnect_retry_interval()

os_failover_server, defined by 222get_reconnect_timeout()

os_failover_server, defined by 222get_related_class()

os_relationship_member_variable, defined

by 311get_related_member()

os_relationship_member_variable, defined by 311

get_replacing_database()

os_Type_info, defined by 432get_replacing_location()

os_Type_info, defined by 432get_replacing_segment()

os_Type_info, defined by 432get_replica_ID()


get_report()

tix_handler, defined by 456get_report0()

tix_handler, defined by 456get_required_DLL_identifiers()

os_database, defined by 160get_retain_persistent_addresses()

objectstore, defined by 71get_return_type()

os_function_type, defined by 228get_root()

os_path_to_data, defined by 271get_schema_database()

os_database, defined by 161os_schema_handle, defined by 348

get_schema_database_pathname()


get_schema_info()

os_schema_handle, defined by 348get_scope()

os_transaction, defined by 411get_sector_size()

os_database, defined by 161os_dbutil, defined by 183

get_segment()

os_database, defined by 161os_Dumper_reference, defined by 208

get_segment_number()

os_Dumper_reference, defined by 208get_segments()

os_database, defined by 161get_server_host()

os_rawfs_entry, defined by 284get_short()

Release 6.3 531

G

os_typespec, defined by 443get_signed_char()

os_typespec, defined by 443get_signed_int()

os_typespec, defined by 443get_signed_integral_value()

os_literal, defined by 236get_signed_long()

os_typespec, defined by 443get_signed_short()

os_typespec, defined by 443get_simple_auth_ui()

objectstore, defined by 71get_size()

os_base_class, defined by 117os_field_member_variable, defined by 224os_member_variable, defined by 250os_type, defined by 420

get_size_as_base()

os_class_type, defined by 125get_source_cluster()


get_source_offset()


get_source_path()


get_source_position()

os_class_type, defined by 125os_enum_type, defined by 216os_member_function, defined by 245os_member_variable, defined by 251os_named_indirect_type, defined by 257

get_specialization_name()

os_Dumper_specialization, defined by 211get_statistics()

os_replicator, defined by 316get_status()

os_archiver, defined by 104os_backup, defined by 110os_recover, defined by 287os_restore, defined by 323os_schema_handle, defined by 348

get_storage_class()

os_member_variable, defined by 251get_string()

os_Dumper_reference, defined by 208os_notification, defined by 261os_pragma, defined by 282os_type, defined by 420

get_suppress_invalid_hard_pointer_errors()

objectstore, defined by 71get_target_class()

os_pointer_to_member_type, defined by 280get_target_cluster()


get_target_export_id()


get_target_exported()


get_target_offset()


get_target_path()


get_target_segment()


get_target_type()

os_anonymous_indirect_type, defined by 101os_indirect_type, defined by 229os_pointer_type, defined by 281

get_template()

os_template_instantiation, defined by 405get_thread_absorption()

os_session, defined by 371get_total_number_of_elements()

os_path_to_data, defined by 272get_transaction_max_retries()

objectstore, defined by 71get_transaction_priority()

objectstore, defined by 71get_transient_cluster()

os_cluster, defined by 133get_transient_database()

os_database, defined by 161get_transient_delete_function()

objectstore, defined by 72get_transient_schema()

os_mop, defined by 256


Index

get_transient_segment()

os_segment, defined by 357get_type()

os_Fixup_dumper, defined by 226os_literal, defined by 236os_member_function, defined by 245os_member_type, defined by 249os_member_variable, defined by 251os_pointer_literal, defined by 279os_rawfs_entry, defined by 284os_template_value_formal, defined by 408os_transaction, defined by 411os_Type_info, defined by 433os_type_template, defined by 436os_type_template_actual_arg, defined by 437os_typed_pointer_void, defined by 439

get_typespec()

os_database_root, defined by 172get_unevolved_schema()

os_schema_evolution, defined by 341get_union_variant()

objectstore, defined by 72get_unsigned_char()

os_typespec, defined by 444get_unsigned_int()

os_typespec, defined by 444get_unsigned_integral_value()

os_literal, defined by 236get_unsigned_long()

os_typespec, defined by 444get_unsigned_short()

os_typespec, defined by 444get_user_name()

os_rawfs_entry, defined by 284get_value()

os_database_root, defined by 172os_enumerator_literal, defined by 217os_export_id, defined by 219tix_handler, defined by 456

get_virtual_base_class_pointer_offset()

os_base_class, defined by 117get_wchar_t_value()

os_literal, defined by 236get_work_database()

os_schema_evolution, defined by 341global functions

operator delete() 458operator new() 459

os_fetch() 461os_fetch_address() 464os_store() 465

Hhandle_xxx()


handling TIX exceptions 469has_affiliation_to()

os_database, defined by 162has_array_components()

os_path_to_data, defined by 272has_constructor()

os_class_type, defined by 126has_destructor()

os_class_type, defined by 126has_dispatch_table()

os_class_type, defined by 126has_dispatch_table_other_compiler()

os_class_type, defined by 126has_exception()

basic_undo, defined by 52hash()



hostof()

os_dbutil, defined by 183

Iignore_locator_file()

objectstore, defined by 72illegal pointers 44initial segment

returning 156setting 168

initialize()

objectstore, defined by 72os_compact, defined by 143os_dbutil, defined by 183os_mop, defined by 256os_schema_evolution, defined by 341

initialize_for_sessions()


Release 6.3 533

I

initialize_object_metadata()

os_mop, defined by 256insert()

os_Database_table, defined by 176os_dynamic_extent, defined by 213

insert_required_DLL_identifier()

os_database, defined by 162insert_required_DLL_identifiers()

os_database, defined by 162os_schema_handle, defined by 349

install()

os_database_schema, defined by 175install_backrest_control_c_handler()

os_dbutil, defined by 183Instantiated_class

os_type, defined by 420Integer

os_type, defined by 420integrity control 44introduces_virtual_functions()

os_class_type, defined by 126is_aborted()

os_transaction, defined by 411is_abstract()

os_class_type, defined by 126is_base_path()

os_path_to_data, defined by 272is_class_type()

os_type, defined by 420is_committed()

os_transaction, defined by 412is_const()

os_anonymous_indirect_type, defined by 101os_member_function, defined by 245os_type, defined by 420

is_damaged_dope_repair_enabled()

objectstore, defined by 75is_db()

os_rawfs_entry, defined by 284is_deleted()


is_dir()

os_rawfs_entry, defined by 284is_DLL_schema_enabled()

objectstore, defined by 75is_empty()

os_cluster, defined by 133

os_segment, defined by 357is_failover()

os_server, defined by 369is_field()

os_member_variable, defined by 251is_forward_definition()

os_class_type, defined by 126is_ignored()

os_Database_table, defined by 177is_indirect_type()

os_type, defined by 420is_inline()

os_member_function, defined by 245is_integral_type()

os_type, defined by 420is_link()

os_rawfs_entry, defined by 284is_lock_contention()

os_transaction, defined by 412is_member_variable_path()

os_path_to_data, defined by 272is_multiple_session_mode()

objectstore, defined by 75is_null()

os_export_id, defined by 219os_string, defined by 394

is_open()

os_database, defined by 162is_open_multi_db_mvcc()

os_database, defined by 162is_open_mvcc()

os_database, defined by 163is_open_read_only()

os_database, defined by 163is_open_single_db_mvcc()

os_database, defined by 163is_open_update()

os_database, defined by 163is_overloaded()

os_member_function, defined by 245is_persistent()

objectstore, defined by 75os_class_type, defined by 126os_member_variable, defined by 251

is_pointer_type()

os_type, defined by 421is_prepared()

os_transaction, defined by 412


Index

is_PTOM()


is_pure_virtual()

os_member_function, defined by 245is_real_type()

os_type, defined by 421is_recognized()

os_pragma, defined by 282is_signed()

os_integral_type, defined by 233is_single_session_mode()

objectstore, defined by 75is_static()

os_member_function, defined by 245os_member_variable, defined by 251

is_template_class()

os_class_type, defined by 126is_transient_cluster()

os_cluster, defined by 133is_transient_database()

os_database, defined by 163is_transient_segment()

os_segment, defined by 357is_unassigned_contiguous_address_space()

objectstore, defined by 76is_unspecified()

os_member, defined by 241os_template, defined by 399os_type, defined by 421

is_valid()

os_Dumper_reference, defined by 209is_virtual()

os_base_class, defined by 117os_member_function, defined by 246

is_volatile()

os_anonymous_indirect_type, defined by 101os_member_function, defined by 246os_type, defined by 421

KKnown

os_function_type, defined by 227

Llist_directory()


load()

os_reference_cross_session, defined by 298os_reference_internal, defined by 302os_reference_protected_internal, defined

by 307os_soft_pointer32_base, defined by 374os_soft_pointer64_base, defined by 378os_Type_fixup_loader, defined by 431os_Type_loader, defined by 435

load_DLL()

objectstore, defined by 76os_DLL_finder, defined by 205

local_path()

os_path_to_data, defined by 272lock_as_used

objectstore, defined by 76lock_cluster_read

objectstore, defined by 77lock_cluster_write

objectstore, defined by 77lock_database_read

objectstore, defined by 77lock_database_write

objectstore, defined by 77lock_page_write

objectstore, defined by 78lock_segment_read

objectstore, defined by 78lock_segment_write

objectstore, defined by 78Long_double

os_type, defined by 421lookup()

os_database, defined by 163lookup_DLL_symbol()


Mmacros, system-supplied 469

collections facility macros 469DECLARE_EXCEPTION() 471DEFINE_EXCEPTION() 472OS_BEGIN_TXN() 474OS_BEGIN_TXN_NAMED() 478OS_END_FAULT_HANDLER 479OS_END_TXN() 480OS_ESTABLISH_FAULT_HANDLER 481OS_MARK_SCHEMA_TYPE() 482

Release 6.3 535

N

OS_MARK_SCHEMA_TYPESPEC() 483OS_REFERENCE_NOCLASS() 484OS_REFERENCE_PROTECTED_NOCLASS() 485OS_REPORT_DLL_LOAD_AND_UNLOAD() 486OS_SCHEMA_DLL_ID() 487OS_SCHEMA_INFO_NAME() 488os_soft_pointer 489OS_SOFT_POINTER32_NOCLASS() 490OS_SOFT_POINTER64_NOCLASS() 491TIX_END_HANDLE 492TIX_EXCEPTION 493TIX_HANDLE() 494TIX_HANDLE_IF() 497

make()

os_path_to_data, defined by 272make_link()

os_dbutil, defined by 184-make_reachable_source_classes_persistent

option to ossgOS_MARK_SCHEMA_TYPESPEC(), the macro 483

MAX_REGISTRY_STRING_LENGTH

os_authentication::get_nt_registry_

location() 109os_authentication::set_nt_registry_

location() 109metaobject protocol 45

exceptions 509metatypes 45minor_subscript()

os_path_to_data, defined by 272mkdir()

os_dbutil, defined by 185more()

os_object_cursor, defined by 268multiversion concurrency control 45

multidatabase 165open_multi_db_mvcc() 165open_mvcc() 166single-database 166

MVCCSee multiversion concurrency control

Nname()

os_path_to_data, defined by 272Named_indirect

os_type, defined by 421Namespace

os_member, defined by 241nested TIX exception handlers 494nested transactions 475network_servers_available()

objectstore, defined by 79new, the operator 458next()

os_cluster_cursor, defined by 138os_export_id_cursor, defined by 220os_object_cursor, defined by 268os_segment_cursor, defined by 365

no_access

os_segment_access, defined by 362notify_immediate()

os_notification, defined by 261notify_on_commit()

os_notification, defined by 262number_of_blockers()


OObjectStore exceptions

See exceptionsobjectstore, the class 54

acquire_address_space() 54acquire_lock() 54add_missing_dispatch_table_handler() 57change_type() 58clear_persistent_to_transient_

pointers() 58embedded_server_available() 59enable_damaged_dope_repair() 59enable_DLL_schema() 60export_object() 60find_DLL_schema() 61free_memory() 61get_address_space_generation_number() 62get_all_servers() 62get_always_check_server_connection_at_

commit() 63get_application_schema_pathname() 64get_as_intervals() 64get_asmarkers_useless() 64get_auto_open_mode() 64get_autoload_DLLs_function() 64get_cache_file() 65get_cache_size() 65


Index

get_client_name() 65get_decache_soft_pointers_after_address_

space_release() 65get_default_partition_size() 65get_export_id() 66get_incremental_schema_installation() 67get_locator_file() 67get_lock_status() 68get_lock_timeout() 68get_log_file() 69get_n_servers() 69get_null_illegal_pointers() 69get_object_range() 69get_page_size() 70get_pointer_numbers() 70get_propagate_on_commit() 70get_retain_persistent_addresses() 71get_simple_auth_ui() 71get_suppress_invalid_hard_pointer_

errors() 71get_transaction_priority() 71get_transient_delete_function() 72get_union_variant() 72ignore_locator_file() 72initialize() 72initialize_for_sessions() 73is_damaged_dope_repair_enabled() 75is_DLL_schema_enabled() 75is_multiple_session_mode() 75is_persistent() 75is_single_session_mode() 75is_unassigned_contiguous_address_

space() 76load_DLL() 76lock_as_used 76lock_cluster_read 77lock_cluster_write 77lock_database_read 77lock_database_write 77lock_page_write 78lock_segment_read 78lock_segment_write 78lookup_DLL_symbol() 78network_servers_available() 79own_page_write 79propagate_log() 79release_cleared_persistent_to_transient_

pointers() 79

release_maintenance() 80release_major() 80release_minor() 80release_name() 81release_persistent_addresses() 81reset_persistent_addresses() 81retain_persistent_addresses() 81return_all_pages() 81return_memory() 81set_allocation_strategy() 82set_always_check_server_connection_at_

commit() 82set_always_null_illegal_pointers() 83set_application_schema_pathname() 83set_asmarkers_useless() 83set_auto_open_mode() 83set_autoload_DLLs_function() 83set_cache_file() 85set_cache_size() 85set_client_name() 85set_current_schema_key() 86set_decache_soft_pointers_after_address_

space_release() 86set_default_address_space_partition_

size() 87set_fetch_policy() 87set_handle_transient_faults() 88set_incremental_schema_installation() 88set_locator_file() 88set_lock_option() 88set_lock_timeout() 89set_log_file() 89set_null_illegal_pointers() 90set_pathname_encoding() 90set_persistent_to_transient_pointer() 90set_propagate_on_commit() 91set_reserve_as_mode() 91set_retain_persistent_addresses() 91set_simple_auth_ui() 92set_suppress_invalid_hard_pointer_

errors() 92set_transaction_max_retries() 92set_transaction_priority() 92set_transient_delete_function() 93set_union_variant() 94shutdown() 94unload_DLL() 94which_product() 94

Release 6.3 537

O

objectstore_exception, the class 96signal() 96vsignal() 96

of()

os_address_space_marker, defined by 99os_cluster, defined by 133os_database, defined by 163os_segment, defined by 357os_session, defined by 371

open()

os_database, defined by 164open_multi_db_mvcc()

os_database, defined by 165open_mvcc()

os_database, defined by 165operator !()

os_Dumper_reference, defined by 210os_Reference<T>, defined by 294os_reference_cross_session, defined by 298os_reference_internal, defined by 302os_reference_protected_internal, defined


operator !=()

os_Dumper_reference, defined by 209os_reference_cross_session, defined by 298os_reference_internal, defined by 302os_reference_protected_internal, defined


operator ()()

os_Dumper_specialization, defined by 211os_Planning_action, defined by 278os_Type_fixup_loader, defined by 431os_Type_loader, defined by 435

operator <()



operator <=()

os_Dumper_reference, defined by 210os_reference_cross_session, defined by 299



operator =()

os_Dumper_reference, defined by 209os_rawfs_entry, defined by 284os_Reference<T>, defined by 294os_reference_cross_session, defined by 298os_Reference_cross_session<T>, defined

by 295os_Reference_protected<T>, defined by 304os_segment_access, defined by 363os_soft_pointer32<T>, defined by 382os_soft_pointer64<T>, defined by 385os_string, defined by 394

operator ==()

os_Dumper_reference, defined by 209os_export_id, defined by 219os_reference_cross_session, defined by 298os_reference_internal, defined by 302os_reference_protected_internal, defined

by 307os_soft_pointer32_base, defined by 375os_soft_pointer64_base, defined by 379os_typespec, defined by 444

operator ->()


by 296os_Reference_protected<T>, defined by 305os_soft_pointer32<T>, defined by 382os_soft_pointer64<T>, defined by 385

operator >()



operator >=()


by 308


Index

os_soft_pointer32_base, defined by 376os_soft_pointer64_base, defined by 380

operator const char*()

os_string, defined by 394operator const os_access_modifier&()

os_member, defined by 241operator const os_anonymous_indirect_

type&()

os_type, defined by 421operator const os_app_schema&()

os_schema, defined by 330operator const os_array_type&()

os_type, defined by 422operator const os_class_type&()

os_type, defined by 422operator const os_comp_schema&()

os_schema, defined by 330operator const os_database_schema&()

os_schema, defined by 331operator const os_enum_type&()

os_type, defined by 422operator const os_field_member_variable&()

os_member, defined by 241os_member_variable, defined by 252

operator const os_function_type&()

os_type, defined by 422operator const os_instantiated_class_

type&()

os_type, defined by 422operator const os_integral_type&()

os_type, defined by 422operator const os_literal_template_actual_

arg&()

os_template_actual_arg, defined by 401operator const os_member_function&()

os_member, defined by 241operator const os_member_type&()

os_member, defined by 241operator const os_member_variable&()

os_member, defined by 241operator const os_named_indirect_type&()

os_type, defined by 422operator const os_pointer_to_member_type&()

os_type, defined by 422operator const os_pointer_type&()

os_type, defined by 423operator const os_real_type&()

os_type, defined by 423

operator const os_reference_type&()

os_type, defined by 423operator const os_relationship_member_

variable&()


operator const os_template_type_formal&()

os_template_formal_arg, defined by 403operator const os_template_value_formal&()

os_template_formal_arg, defined by 403operator const os_type_template&()

os_template, defined by 399operator const os_type_template_actual_

arg&()

os_template_actual_arg, defined by 401operator const os_type_type&()

os_type, defined by 423operator const os_void_type&()

os_type, defined by 423operator delete()

os_session, defined by 371operator delete(), the global function 458operator new(), the global function 459operator os_access_modifier&()

os_member, defined by 242operator os_anonymous_indirect_type&()

os_type, defined by 423operator os_app_schema&()

os_schema, defined by 331operator os_array_type&()

os_type, defined by 423operator os_class_type&()

os_type, defined by 423operator os_comp_schema&()

os_schema, defined by 331operator os_database_schema&()

os_schema, defined by 331operator os_enum_type&()

os_type, defined by 424operator os_field_member_variable&()


operator os_function_type&()

os_type, defined by 424operator os_instantiated_class_type&()

os_class_type, defined by 127os_type, defined by 424

operator os_integral_type&()

Release 6.3 539

O

os_type, defined by 424operator os_literal_template_actual_arg&()

os_template_actual_arg, defined by 401operator os_member_function&()

os_member, defined by 242operator os_member_type&()

os_member, defined by 242operator os_member_variable&()

os_member, defined by 242operator os_named_indirect_type&()

os_type, defined by 424operator os_pointer_to_member_type&()

os_type, defined by 424operator os_pointer_type&()

os_type, defined by 424operator os_real_type&()

os_type, defined by 424operator os_reference_type&()

os_type, defined by 425operator os_relationship_member_variable&()


operator os_template_type_formal&()

os_template_formal_arg, defined by 403operator os_template_value_formal&()

os_template_formal_arg, defined by 403operator os_type_template&()

os_template, defined by 400operator os_type_template_actual_arg&()

os_template_actual_arg, defined by 402operator os_type_type&()

os_type, defined by 425operator os_void_type&()

os_type, defined by 425operator T*()


by 295os_Reference_protected<T>, defined by 305os_soft_pointer32<T>, defined by 382os_soft_pointer64<T>, defined by 385

operator void*()

os_Dumper_reference, defined by 209os_typed_pointer_void, defined by 439

os_access_modifier, the class 97create() 97get_base_member() 97set_base_member() 97

~os_address_space_marker()

os_address_space_marker, defined by 100os_address_space_marker()

os_address_space_marker, defined by 99os_address_space_marker, the class 98

get_current() 99get_level() 99get_next() 99get_previous() 99of() 99~os_address_space_marker() 100os_address_space_marker() 99release() 99retain() 100

os_allocation_strategy_least_space enumerator 63

os_allocation_strategy_least_wait enumerator 63

os_anonymous_indirect_type, the class 101create() 101get_target_type() 101is_const() 101is_volatile() 101set_is_const() 101set_is_volatile() 101

os_app_schema, the class 102get() 102

os_application_schema_info, the class 103os_archiver()

os_archiver, defined by 104os_archiver, the class 104

~os_archiver() 104add_db_to_archive() 104change_time_interval() 104get_current_archive_file_name() 104get_status() 104os_archiver() 104remove_db_from_archive() 105start_archiver() 105stop_archiver() 105take_a_snapshot() 105

os_archiver_options()

os_archiver_options, defined by 107os_archiver_options, the class 106

~os_archiver_options() 107os_archiver_options() 107reset() 107

os_array_type, the class 108


Index

create() 108get_element_type() 108get_number_of_elements() 108set_element_type() 108set_number_of_elements() 108

os_authentication, the class 109get_nt_registry_location() 109

os_backup()

os_backup, defined by 110os_backup, the class 110

~os_backup() 110get_status() 110os_backup() 110start_and_run_backup() 110start_backup() 111stop_backup() 111

os_backup_options()

os_backup_options, defined by 115os_backup_options, the class 112

~os_backup_options() 115os_backup_options() 115reset() 115

os_base_class, the class 116create() 116get_access() 116get_class() 116get_offset() 116get_size() 117get_virtual_base_class_pointer_

offset() 117is_virtual() 117Private 117Protected 117Public 117set_access() 117set_class() 117set_offset() 118set_virtual_base_class_no_pointer() 118set_virtual_base_class_pointer_

offset() 118set_virtuals_redefined() 118virtual_base_class_has_pointer() 118virtuals_redefined() 118

OS_BEGIN_TXN(), the macro 474OS_BEGIN_TXN_NAMED(), the macro 478os_boolean 47OS_CACHE_FILE environment variable

objectstore::set_cache_file 85

os_class_type, the class 119Anonymous_union 119Class 119create() 119declares_get_os_typespec_function() 120defines_virtual_functions() 120find_base_class() 120find_member_variable() 120get_access_of_get_os_typespec_

function() 121get_allocated_virtual_base_classes() 121get_base_classes() 121get_class_kind() 122get_dispatch_table_pointer_offset() 122get_dispatch_table_pointer_offset_other_

compiler() 122get_indirect_virtual_base_classes() 122get_members() 123get_most_derived_class() 123get_name() 125get_pragmas() 125get_size_as_base() 125get_source_position() 125has_constructor() 126has_destructor() 126has_dispatch_table() 126has_dispatch_table_other_compiler() 126introduces_virtual_functions() 126is_abstract() 126is_forward_definition() 126is_persistent() 126is_template_class() 126operator os_instantiated_class_

type&() 127set_access_of_get_os_typespec_

function() 127set_base_classes() 127set_class_kind() 127set_declares_get_os_typespec_

function() 127set_defines_virtual_functions() 127set_dispatch_table_pointer_offset() 128set_has_constructor() 128set_has_destructor() 128set_indirect_virtual_base_classes() 128set_introduces_virtual_functions() 128set_is_abstract() 128set_is_forward_definition() 128

Release 6.3 541

O

set_is_persistent() 128set_members() 128set_name() 129set_pragmas() 129set_source_position() 129Union 129

os_class_typeStruct 129os_close_database, the class 130os_cluster, the class 131

database_of() 131destroy() 131get_allocation_strategy() 131get_fetch_policy() 131get_lock_option() 132get_null_illegal_pointers() 132get_number() 133get_transient_cluster() 133is_deleted() 133is_empty() 133is_transient_cluster() 133of() 133release_pointer() 133retain_pointer() 134return_memory() 134segment_of() 134session_of() 134set_allocation_strategy() 135set_fetch_policy() 135set_lock_option() 135set_null_illegal_pointers() 136set_size() 136size() 137with() 137

os_cluster_cursor()

os_cluster, defined by 138os_cluster_cursor, the class 138

get_current() 138next() 138os_cluster_cursor() 138reset() 139

os_cluster_with, the class 140get() 140

os_comp_schema, the class 147get() 147

os_compact, the class 141augment_cluster_split_avoidance() 141augment_post_compact_transformers() 141compact() 142

initialize() 143set_address_space_release_interval() 144set_avoid_page_boundary() 144set_explanation_level() 144set_malloc_size() 145set_maplet_size() 145set_maximum_cluster_size() 145set_maximum_memory_size() 145shutdown() 146

os_database, the class 148affiliate() 148change_affiliation() 149change_schema_key() 149close() 150create() 150create_root() 152create_segment() 152destroy() 153find_root() 153freeze_schema_key() 153get_affiliated_databases() 154get_affiliation_index_of() 154get_all_databases() 154get_all_roots() 155get_all_segments() 155get_all_segments_and_permissions() 155get_allocation_strategy() 156get_application_info() 156get_default_segment() 156get_fetch_policy() 156get_file_host_name() 157get_fragmentation() 157get_host_name() 158get_incremental_schema_

installation() 158get_lock_option() 158get_n_databases() 159get_n_roots() 159get_n_segments() 159get_new_segment_reference_policy() 159get_null_illegal_pointers() 159get_open_mode() 160get_path_to() 160get_pathname() 160get_required_DLL_identifiers() 160get_schema_database() 161get_sector_size() 161get_segment() 161


Index

get_segments() 161get_transient_database() 161has_affiliation_to() 162insert_required_DLL_identifier() 162insert_required_DLL_identifiers() 162is_open() 162is_open_multi_db_mvcc() 162is_open_mvcc() 163is_open_read_only() 163is_open_single_db_mvcc() 163is_open_update() 163is_transient_database() 163lookup() 163of() 163open() 164open_multi_db_mvcc() 165open_mvcc() 165release_pointer() 166remove_required_DLL_identifier() 167retain_pointer() 167return_memory() 167session_of() 167set_allocation_strategy() 168set_application_info() 168set_default_segment() 168set_fetch_policy() 169set_incremental_schema_

installation() 169set_lock_option() 169set_new_segment_reference_policy() 170set_null_illegal_pointers() 170set_schema_database() 170set_size() 170set_size_in_sectors() 171size() 171size_in_sectors() 171time_created() 171

~os_database_root()

os_database_root, defined by 174os_database_root, the class 172

destroy() 172find() 172get_name() 172get_typespec() 172get_value() 172~os_database_root() 174release_pointer() 173retain_pointer() 173

set_value() 174os_database_schema, the class 175

get() 175get_for_update() 175install() 175

os_Database_table, the class 176find_reference() 176get() 176insert() 176is_ignored() 177

os_dbcontrol_options, the classargument to osdbcontrol() 185

os_dbutil, the class 178chgrp() 178chmod() 178chown() 178close_all_connections() 179close_all_server_connections() 179close_server_connection() 179cmgr_remove_file() 179cmgr_shutdown() 179cmgr_stat() 179compare_schemas() 181copy_database() 182disk_free() 182expand_global() 182file_db_pathname() 183get_client_name() 183get_sector_size() 183hostof() 183initialize() 183install_backrest_control_c_handler() 183list_directory() 184make_link() 184mkdir() 185ossize() 186osverifydb() 187osverifydb_one_segment() 188rehost_all_links() 189rehost_link() 189remove() 190rename() 190rmdir() 190set_application_schema_path() 190set_client_name() 191split_pathname() 191start_backrest_logging() 191stat() 192

Release 6.3 543

O

stop_backrest_logging() 192svr_checkpoint() 192svr_client_kill() 192svr_debug() 193svr_machine() 193svr_ping() 194svr_shutdown() 194svr_stat() 194

os_deadlock_exception, the class 203get_application_names() 203get_fault_addr() 204get_hostnames() 204get_lock_type() 204get_pids() 204number_of_blockers() 204

OS_DEF_EXCEPT_ACTION environment variableobjectstore_exception::signal() 96objectstore_exception::vsignal() 96

os_DLL_finder, the class 205equal_DLL_identifiers() 205equal_DLL_identifiers_same_prefix() 205get() 205load_DLL() 205register_() 205unregister() 205

os_DLL_schema_info, the class 206add_DLL_identifier() 206DLL_loaded() 206DLL_unloaded() 207

os_Dumper_reference()

os_Dumper_reference, defined by 210os_Dumper_reference, the class 208

get_database() 208get_database_number() 208get_offset() 208get_segment() 208get_segment_number() 208get_string() 208is_valid() 209operator !() 210operator !=() 209operator <() 209operator <=() 210operator =() 209operator ==() 209operator >() 209operator >=() 210operator void*() 209

os_Dumper_reference() 210resolve() 210

os_Dumper_specialization, the class 211get_specialization_name() 211operator ()() 211should_use_default_constructor() 212

~os_dynamic_extent()

os_dynamic_extent, defined by 214os_dynamic_extent()

os_dynamic_extent, defined by 213os_dynamic_extent, the class 213

insert() 213~os_dynamic_extent() 214os_dynamic_extent() 213remove() 214

OS_END_FAULT_HANDLER, the macro 479OS_END_TXN(), the macro 480os_enum_type, the class 215

create() 215get_enumerator() 215get_enumerators() 215get_name() 215get_pragmas() 215get_source_position() 216set_enumerators() 216set_name() 216set_pragmas() 216set_source_position() 216

os_enumerator_literal, the class 217create() 217get_name() 217get_value() 217set_name() 217set_value() 217

OS_ESTABLISH_FAULT_HANDLER, the macro 481os_evolve_subtype_fun_binding()

os_evolve_subtype_fun_binding, defined by 218

os_evolve_subtype_fun_binding, the class 218os_evolve_subtype_fun_binding() 218

os_export_id, the class 219get_value() 219is_null() 219operator ==() 219

~os_export_id_cursor()

os_export_id_cursor, defined by 221os_export_id_cursor()

os_export_id_cursor, defined by 220


Index

os_export_id_cursor, the class 220get_current() 220next() 220~os_export_id_cursor() 221os_export_id_cursor() 220reset() 221

os_failover_server, the class 222get_logical_server_hostname() 222get_online_server_hostname() 222get_reconnect_retry_interval() 222get_reconnect_timeout() 222set_reconnect_timeout_and_interval() 223

os_fetch(), the global function 461os_fetch_address(), the global function 464os_fetch_cluster enumerator 67os_fetch_page enumerator 67os_fetch_stream enumerator 67os_field_member_variable, the class 224

create() 224get_offset() 224get_size() 224set_size() 224

~os_Fixup()

os_Fixup_dumper, defined by 226os_Fixup_dumper()

os_Fixup_dumper, defined by 226os_Fixup_dumper, the class 225

dump_info() 225duplicate() 225get_number_elements() 225get_object_to_fix() 225get_type() 226~os_Fixup() 226os_Fixup_dumper() 226

os_function_type, the class 227create() 227equal_signature() 227get_arg_list() 227get_arg_list_kind() 227get_return_type() 228Known 227set_arg_list() 228set_arg_list_kind() 228set_return_type() 228Unknown 227Variable 227

os_indirect_type, the class 229get_target_type() 229

set_target_type() 229os_instantiated_class_type, the class 230

create() 230get_instantiation() 230set_instantiation() 230

os_int64()

os_int64, defined by 231os_int64, the class 231

get_high() 231get_low() 231os_int64() 231sprint() 231

os_integral_type, the class 232create() 232create_defaulted_char() 232create_int() 232create_long() 232create_short() 233create_signed_char() 233create_unsigned_char() 233is_signed() 233

os_int16

typespec for 441os_int64 47

typespec for 441os_int32 47

typespec for 441os_literal, the class 234

create_char() 234create_enum_literal() 234create_pointer_literal() 234create_signed_char() 234create_signed_int() 234create_signed_long() 234create_signed_short() 234create_unsigned_char() 234create_unsigned_int() 235create_unsigned_long() 235create_unsigned_short() 235create_wchar_t() 235get_char_value() 235get_enum_literal() 235get_kind() 235get_pointer_literal() 236get_signed_integral_value() 236get_type() 236get_unsigned_integral_value() 236get_wchar_t_value() 236

Release 6.3 545

O

os_literal_template_actual_arg, the class 237create() 237get_literal() 237set_literal() 237

os_lock_timeout exception 89os_lock_timeout_exception, the class 238

get_application_names() 238get_fault_addr() 238get_hostnames() 239get_lock_type() 239get_pids() 239number_of_blockers() 239

OS_LOG_FILE environment variableand objectstore::set_log_file() 89

OS_MARK_SCHEMA_TYPE(), the macro 482OS_MARK_SCHEMA_TYPESPEC(), the macro 483os_member, the class 240

Access_modifier 240Field_variable 240Function 240get_access() 240get_defining_class() 240get_kind() 240is_unspecified() 241Namespace 241operator const os_access_modifier&() 241operator const os_field_member_

variable&() 241operator const os_member_function&() 241operator const os_member_type&() 241operator const os_member_variable&() 241operator const os_relationship_member_

variable&() 242operator os_access_modifier&() 242operator os_field_member_variable&() 242operator os_member_function&() 242operator os_member_type&() 242operator os_member_variable&() 242operator os_relationship_member_

variable&() 242Private 242Protected 243Public 243Relationship 243set_access() 243Type 243Variable 243

os_member_function, the class 244

create() 244get_call_linkage() 244get_function_kind() 244get_name() 245get_source_position() 245get_type() 245is_const() 245is_inline() 245is_overloaded() 245is_pure_virtual() 245is_static() 245is_virtual() 246is_volatile() 246set_call_linkage() 246set_is_const() 246set_is_inline() 246set_is_overloaded() 246set_is_pure_virtual() 246set_is_static() 246set_is_virtual() 247set_is_volatile() 247set_name() 247set_source_position() 247set_type() 247

os_member_namespace, the class 248create() 248get_namespace() 248set_namespace() 248

os_member_type, the class 249create() 249get_type() 249set_type() 249

os_member_variable, the class 250create() 250get_name() 250get_offset() 250get_size() 250get_source_position() 251get_storage_class() 251get_type() 251is_field() 251is_persistent() 251is_static() 251operator const os_field_member_

variable&() 252operator const os_relationship_member_

variable&() 252operator os_field_member_variable&() 252


Index

operator os_relationship_member_

variable&() 252Persistent 251Regular 251set_name() 252set_offset() 252set_source_position() 252set_storage_class() 253set_type() 253Static 251

os_mop, the class 254bind() 254copy_classes() 255current() 255find_namespace() 255find_type() 255get_failure_classes() 255get_neutralized_classes() 255get_transient_schema() 256initialize() 256initialize_object_metadata() 256reset() 256

os_named_indirect_type, the class 257create() 257get_name() 257get_source_position() 257set_name() 257set_source_position() 257

os_namespace, the class 258create() 258get_enclosing_namespace() 258get_members() 258get_name() 258set_enclosing_namespace() 258set_members() 258set_name() 259

os_notification()

os_notification, defined by 263os_notification, the class 260

assign() 260get_database() 260_get_fd() 260get_kind() 260get_location() 261get_string() 261notify_immediate() 261notify_on_commit() 262os_notification() 263

queue_status() 263receive() 264set_queue_size() 265subscribe() 265unsubscribe() 266

~os_object_cursor()

os_object_cursor, defined by 270os_object_cursor()

os_object_cursor, defined by 269os_object_cursor, the class 268

current() 268first() 268more() 268next() 268~os_object_cursor() 270os_object_cursor() 269release_address_space() 269reset() 269set() 270

os_path_to_data, the class 271add() 271bit_offset() 271byte_offset() 271get_root() 271get_total_number_of_elements() 272has_array_components() 272is_base_path() 272is_member_variable_path() 272local_path() 272make() 272minor_subscript() 272name() 272outer_collocated_path() 273outer_path() 273pop() 273to_bit_field() 273to_dope() 273to_static_member() 273to_subscript() 273type() 273unique_name() 273

os_pathname_and_segment_number()


os_pathname_segment_cluster, defined by 276os_pathname_and_segment_number, the class 275

database_pathname 275os_pathname_and_segment_number() 275

Release 6.3 547

O

segment_number 275os_pathname_segment_cluster, the class 276

cluster_number 276database_pathname 276os_pathname_and_segment_number() 276segment_number 276

os_persistent_to_transient_pointer_manager, the class

release() 277os_persistent_to_transient_pointer_manger,

the class 277os_Planning_action, the class 278

operator ()() 278os_pointer_literal, the class 279

create() 279get_name() 279get_type() 279set_name() 279set_type() 279

os_pointer_to_member_type, the class 280create() 280get_target_class() 280set_target_class() 280

os_pointer_type, the class 281create() 281get_target_type() 281set_target_type() 281

os_pragma, the class 282create() 282get_string() 282is_recognized() 282

~os_rawfs_entry()

os_rawfs_entry, defined by 285os_rawfs_entry()

os_rawfs_entry, defined by 284os_rawfs_entry, the class 283

get_abs_path() 283get_creation_time() 283get_group_name() 283get_link_host() 283get_link_path() 283get_n_sectors() 283get_name() 283get_permission() 283get_server_host() 284get_type() 284get_user_name() 284is_db() 284

is_dir() 284is_link() 284operator =() 284~os_rawfs_entry() 285os_rawfs_entry() 284OSU_DATABASE 285OSU_DIRECTORY 285OSU_LINK 285

os_real_type, the class 286create() 286create_double() 286create_float() 286create_long_double() 286

os_recover()

os_recover, defined by 287os_recover, the class

~os_recover() 287get_status() 287os_recover() 287start_and_run_recover() 287start_recover() 288stop_recover() 288

os_recover_options()

os_recover_options, defined by 292os_recover_options, the class 289

~os_recover_options() 292os_recover_options() 292reset() 292

os_Reference()

os_Reference<T>, defined by 294os_Reference<T>, the class 293

get_os_typespec() 293operator !() 294operator =() 294operator ->() 294operator T*() 294os_Reference() 294resolve() 294

os_Reference_cross_session()

os_Reference_cross_session<T>, defined by 296

~os_reference_cross_session()

os_reference_cross_session, defined by 299os_reference_cross_session()

os_reference_cross_session, defined by 299os_reference_cross_session, the class 297

dump() 298get_database() 298


Index

load() 298operator !() 298operator !=() 298operator <() 299operator <=() 299operator =() 298operator ==() 298operator >() 299operator >=() 299~os_reference_cross_session() 299os_reference_cross_session() 299resolve() 300

os_Reference_cross_session<T>, the class 295get_os_typespec() 295operator =() 295operator ->() 296operator T*() 295os_Reference_cross_session() 296resolve() 296

~os_reference_internal()

os_reference_internal, defined by 303os_reference_internal, the class 301

dump() 301get_database() 301get_database_key() 301get_open_database() 302hash() 302load() 302operator !() 302operator !=() 302operator <() 302operator <=() 303operator ==() 302operator >() 303operator >=() 303~os_reference_internal() 303resolve() 303

OS_REFERENCE_NOCLASS(), the macro 484os_Reference_protected()

os_Reference_protected<T>, defined by 305os_Reference_protected<T>, the class 304

get_os_typespec() 304operator =() 304operator ->() 305operator T*() 305os_Reference_protected() 305resolve() 305

~os_reference_protected_internal()

os_reference_protected_internal, defined by 308

os_reference_protected_internal, the class 306dump() 306get_database() 306get_database_key() 307hash() 307load() 307operator !() 307operator !=() 307operator <() 308operator <=() 308operator ==() 307operator >() 308operator >=() 308~os_reference_protected_internal() 308resolve() 309

OS_REFERENCE_PROTECTED_NOCLASS(), the macro 485

os_reference_type, the class 310create() 310

os_relationship_member_variable, the class 311get_related_class() 311get_related_member() 311

os_release_cluster_pointer, the class 312os_release_database_pointer, the class 313os_release_root_pointer, the class 314os_release_segment_pointer, the class 315~os_replicator()

os_replicator, defined by 316os_replicator()

os_replicator, defined by 316os_replicator, the class 316

change_time_interval() 316get_statistics() 316get_status() 317os_replicator() 316reset_statistics() 317start_replicator() 317stop_replicator() 317

~os_replicator_options()

os_replicator_options, defined by 320os_replicator_options()

os_replicator_options, defined by 320os_replicator_options, the class 318

os_replicator_options() 320reset() 320

~os_replicator_statistic_info()

Release 6.3 549

O


os_replicator_statistic_info()


os_replicator_statistic_info, the classformat_and_print_statistics() 322format_statistics() 322get_replica_ID() 322os_replicator_statistic_info() 321

OS_REPORT_DLL_LOAD_AND_UNLOAD(), the macro 486

os_restore()

os_restore, defined by 323os_restore, the class 287, 323

~os_restore() 323get_status() 323os_restore() 323start_and_run_restore() 324start_restore() 324stop_restore() 324

os_restore_options()

os_restore_options, defined by 328os_restore_options, the class 325

~os_restore_options() 328os_restore_options() 328reset() 328

os_retain_address()

os_retain_address, defined by 329os_retain_address, the class 329

os_retain_address() 329release() 329retaining() 329set_retain() 329

os_schema, the class 330Application_schema 330Compilation_schema 330Database_schema 330find_type() 330get_classes() 330get_kind() 330operator const os_app_schema&() 330operator const os_comp_schema&() 330operator const os_database_schema&() 331operator os_app_schema&() 331operator os_comp_schema&() 331operator os_database_schema&() 331

OS_SCHEMA_DLL_ID(), the macro 487

os_schema_evolution, the class 332augment_classes_to_be_recycled() 335augment_classes_to_be_removed() 335augment_cluster_split_avoidance() 335augment_dll_schema_db_names() 335augment_optional_classes() 336augment_post_evol_transformers() 336evolve() 337get_enclosing_object() 340get_evolved_schema() 340get_evolved_schema_db_name() 340get_explanation_level() 340get_path_to_member() 340get_unevolved_schema() 341get_work_database() 341initialize() 341set_address_space_release_interval() 341set_avoid_page_boundary() 341set_disable_transformer_class_

checks() 342set_evolved_schema_db_name() 342set_explanation_level() 342set_malloc_size() 343set_maplet_size() 343set_maximum_cluster_size() 145, 343set_maximum_memory_size() 145, 343set_obsolete_index_handler() 343set_obsolete_query_handler() 343set_optimzie_checkpoints() 345set_pre_evolution_setup_hook() 345set_resolve_ambiguous_void_

pointers() 345set_task_list_file_name() 345set_untranslatable_pointer_handler() 345shutdown() 345task_list() 346

os_schema_handle, the class 347DLL_unloaded() 347get() 347get_all() 347get_application_schema_handle() 348get_DLL_identifiers() 348get_schema_database() 348get_schema_database_pathname() 348get_schema_info() 348get_status() 348insert_required_DLL_identifiers() 349set_schema_database_pathname() 349


Index

os_schema_handle_status, the enumerator 349os_schema_info, the class 350

get() 350get_DLL_identifiers() 350get_schema_database_pathname() 350set_schema_database_pathname() 350

OS_SCHEMA_INFO_NAME(), the macro 488os_schema_install_options()

os_schema_install_options, defined by 351os_schema_install_options, the class 351

get_copy_member_functions() 351os_schema_install_options() 351set_copy_member_functions() 351

os_segment, the class 352create_cluster() 352database_of() 352destroy() 352get_access_control() 352get_all_clusters() 353get_allocation_strategy() 353get_application_info() 353get_cluster() 353get_clusters() 354get_comment() 354get_default_cluster() 354get_export_ids() 355get_fetch_policy() 355get_lock_option() 356get_n_clusters() 356get_null_illegal_pointers() 356get_number() 357get_transient_segment() 357is_deleted() 357is_empty() 357is_transient_segment() 357of() 357release_pointer() 358resolve_export_id() 358retain_pointer() 358return_memory() 359session_of() 359set_access_control() 359set_allocation_strategy() 359set_application_info() 360set_comment() 360set_default_cluster() 360set_fetch_policy() 360set_lock_option() 361

set_null_illegal_pointers() 361set_segment_reference_policy() 357size() 361

~os_segment_access()

os_segment_access, defined by 364os_segment_access()

os_segment_access, defined by 363os_segment_access, the class 362

get_default() 362get_primary_group() 362no_access 362operator =() 363~os_segment_access() 364os_segment_access() 363read_access 363read_write_access 363set_default() 364set_primary_group() 364

os_segment_cursor()

os_segment_cursor, defined by 365os_segment_cursor, the class 365

get_current() 365next() 365os_segment_cursor() 365reset() 366

os_server, the class 367connection_is_broken() 367disconnect() 368get_databases() 368get_host_name() 368get_n_databases() 368is_failover() 369reconnect() 369

os_session, the class 370create() 370force_full_initialization() 370get_all_sessions() 370get_current() 370get_n_sessions() 371get_name() 371get_thread_absorption() 371of() 371operator delete() 371set_current() 372set_thread_absorption() 372unuse_DLL() 372use_DLL() 372

os_signed_int8

Release 6.3 551

O

typespec for 442os_size_options, the class

argument to ossize() 187os_soft_pointer, the macro 489os_soft_pointer<T>, the class 489os_soft_pointer32()

os_soft_pointer32<T>, defined by 382os_soft_pointer32<char>, the class 389os_soft_pointer32<T>, the class 381

operator =() 382operator ->() 382operator T*() 382os_soft_pointer32() 382resolve() 383

os_soft_pointer32<void>, the class 387~os_soft_pointer32_base()

os_soft_pointer32_base, defined by 376os_soft_pointer32_base, the class 373

decache() 373dump() 373get_database() 374get_database_key() 374get_open_database() 374hash() 374load() 374operator !() 375operator !=() 375operator <() 375operator <=() 376operator ==() 375operator >() 375operator >=() 376~os_soft_pointer32_base() 376resolve() 376

OS_SOFT_POINTER32_NOCLASS(), the macro 490os_soft_pointer64()

os_soft_pointer64<T>, defined by 385os_soft_pointer64<char>, the class 390os_soft_pointer64<T>, the class 384

operator =() 385operator ->() 385operator T*() 385os_soft_pointer64() 385resolve() 386

os_soft_pointer64<void>, the class 388~os_soft_pointer64_base()

os_soft_pointer64_base, defined by 380os_soft_pointer64_base, the class 377

decache() 377dump() 377get_database() 378get_database_key() 378get_open_database() 378hash() 378load() 378operator !() 379operator !=() 379operator <() 379operator <=() 380operator ==() 379operator >() 379operator >=() 380~os_soft_pointer64_base() 380resolve() 380

OS_SOFT_POINTER64_NOCLASS(), the macro 491os_store(), the global function 465os_str_conv()

os_str_conv, defined by 393os_str_conv, the class 391

change_mapping() 391convert() 391get_converted_size() 392os_str_conv() 393

~os_string()

os_string, defined by 395os_string()

os_string, defined by 395os_string, the class 394

compare() 394compare_nocase() 394is_null() 394operator =() 394operator const char*() 394~os_string() 395os_string() 395

os_subscription()

os_subscription, defined by 398os_subscription, the class 396

assign() 396get_database() 397os_subscription() 398

os_template, the class 399Function 399get_args() 399get_kind() 399is_unspecified() 399


Index

operator const os_type_template&() 399operator os_type_template&() 400set_args() 400Type 400

os_template_actual_arg, the class 401get_kind() 401operator const os_literal_template_

actual_arg&() 401operator const os_type_template_actual_

arg&() 401operator os_literal_template_actual_

arg&() 401operator os_type_template_actual_

arg&() 402os_template_formal_arg, the class 403

get_kind() 403get_name() 403operator const os_template_type_

formal&() 403operator const os_template_value_

formal&() 403operator os_template_type_formal&() 403operator os_template_value_formal&() 403set_name() 404

os_template_instantiation, the class 405create() 405get_args() 405get_template() 405set_args() 405set_template() 406

os_template_type_formal, the class 407create() 407

os_template_value_formal, the class 408create() 408get_type() 408set_type() 408

os_transaction, the class 409abort() 409abort_top_level() 409begin() 409checkpoint() 410commit() 411get_current() 411get_name() 411get_parent() 411get_scope() 411get_type() 411is_aborted() 411

is_committed() 412is_lock_contention() 412is_prepared() 412read_only 413session_of() 413set_name() 413top_level() 413update 414

os_transaction_hook, the class 415after_begin 415after_checkpoint 415after_commit 415before_abort 415before_checkpoint 415before_commit 416before_retry 416deregister_hook() 416register_hook() 416

os_transformer_binding()

os_transformer_binding, defined by 417os_transformer_binding, the class 417

os_transformer_binding() 417os_type, the class 418

Anonymous_indirect 418Array 418Char 418Class 418Double 418Enum 418Float 418Function 418get_alignment() 419get_enclosing_class() 419get_kind() 419get_kind_string() 420get_size() 420get_string() 420Instantiated_class 420Integer 420is_class_type() 420is_const() 420is_indirect_type() 420is_integral_type() 420is_pointer_type() 421is_real_type() 421is_unspecified() 421is_volatile() 421Long_double 421

Release 6.3 553

O

Named_indirect 421operator const os_anonymous_indirect_

type&() 421operator const os_array_type&() 422operator const os_class_type&() 422operator const os_enum_type&() 422operator const os_function_type&() 422operator const os_instantiated_class_

type&() 422operator const os_integral_type&() 422operator const os_named_indirect_

type&() 422operator const os_pointer_to_member_

type&() 422operator const os_pointer_type&() 423operator const os_real_type&() 423operator const os_reference_type&() 423operator const os_type_type&() 423operator const os_void_type&() 423operator os_anonymous_indirect_

type&() 423operator os_array_type&() 423operator os_class_type&() 423operator os_enum_type&() 424operator os_function_type&() 424operator os_instantiated_class_

type&() 424operator os_integral_type&() 424operator os_named_indirect_type&() 424operator os_pointer_to_member_type&() 424operator os_pointer_type&() 424operator os_real_type&() 424operator os_reference_type&() 425operator os_type_type&() 425operator os_void_type&() 425Pointer 425Pointer_to_member 425Reference 425set_alignment() 425set_size() 425Signed_char 425Signed_long 426Signed_short 426strip_indirect_types() 426Type 427type_at() 427type_containing() 427Undefined 427

Unsigned_char 427Unsigned_integer 427Unsigned_long 428Unsigned_short 428Void 428

os_Type_fixup_info()

os_Type_fixup_info, defined by 429os_Type_fixup_info, the class 429

fixup_data 429os_Type_fixup_info() 429

os_Type_fixup_loader, the class 430fixup() 430get() 430load() 431operator ()() 431

os_Type_info()

os_Type_info, defined by 433os_Type_info, the class 432

data 432get_original_location() 432get_replacing_database() 432get_replacing_location() 432get_replacing_segment() 432get_type() 433os_Type_info() 433set_replacing_location() 433

os_Type_loader, the class 434create() 434fixup() 434get() 434load() 435operator ()() 435

os_type_template, the class 436create() 436get_type() 436set_type() 436

os_type_template_actual_arg, the class 437create() 437get_type() 437set_type() 437

os_type_type, the class 438os_typed_pointer_void, the class 439

get_type() 439operator void*() 439

os_typespec()

os_typespec, defined by 444os_typespec, the class 440

get_char() 440


Index

get_double() 440get_float() 440get_int() 440get_long() 441get_long_double() 441get_name() 441get_os_int16() 441get_os_int64() 441get_os_int32() 441get_os_signed_int8() 442get_os_unsigned_int16() 442get_os_unsigned_int32() 442get_os_unsigned_int64() 442get_os_unsigned_int8() 442get_pointer() 443get_short() 443get_signed_char() 443get_signed_int() 443get_signed_long() 443get_signed_short() 443get_unsigned_char() 444get_unsigned_int() 444get_unsigned_long() 444get_unsigned_short() 444operator ==() 444os_typespec() 444

os_unsigned_int16

typespec for 442os_unsigned_int32

typespec for 442os_unsigned_int64

typespec for 442os_unsigned_int64()

os_unsigned_int64, defined by 446os_unsigned_int64, the class 446

get_high() 446get_low() 446os_unsigned_int64() 446sprint() 447

os_unsigned_int8

typespec for 442os_unsigned_int32 47os_untranslatable_pointer_handler, the

class 448~os_untranslatable_pointer_handler() 451get_exception() 448get_explanation() 448get_final_offset() 449

get_source_cluster() 448get_source_offset() 448get_source_path() 448get_target_cluster() 448get_target_export_id() 449get_target_exported() 449get_target_offset() 449get_target_path() 449get_target_segment() 449handle_xxx() 450is_PTOM() 450set_final_offset() 450

os_verifydb_options, the classargument to osverifydb() 188argument to osverifydb_one_segment() 189

os_void_type, the class 451create() 451

~os_with_mapped()

os_with_mapped, defined by 452os_with_mapped()

os_with_mapped, defined by 452os_with_mapped, the class 452

~os_with_mapped() 452os_with_mapped() 452

ossg utilityOS_MARK_SCHEMA_TYPE(), the macro 482OS_MARK_SCHEMA_TYPESPEC(), the macro 483

ossize()

os_dbutil, defined by 186OSU_DATABASE

os_rawfs_entry, defined by 285OSU_DIRECTORY

os_rawfs_entry, defined by 285OSU_LINK

os_rawfs_entry, defined by 285osverifydb()

os_dbutil, defined by 187osverifydb_one_segment()

osdbutil, defined by 188outer_collocated_path()

os_path_to_data, defined by 273outer_path()

os_path_to_data, defined by 273own_page_write


Ppermissions 362

Release 6.3 555

Q

Persistent

os_member_variable, defined by 251persistent delete 458persistent new 459persistent storage 44

allocating 459reclaiming using the delete operator 458

persistently allocated objects 44Pointer

os_type, defined by 425Pointer_to_member

os_type, defined by 425pointers

See also cross-database pointerspop()

os_path_to_data, defined by 273Private


programs, examplesSee example programs

propagate_log()

objectstore, defined by 79Protected


Public


Qqueue_status()

os_notification, defined by 263

Rread_access

os_segment_access, defined by 363read_only

os_transaction, defined by 413read_write_access

os_segment_access, defined by 363read-only transactions 475receive()

os_notification, defined by 264reclaiming storage

using the delete operator 458reconnect()

os_server, defined by 369reconnecting to servers 367Reference

os_type, defined by 425register_()

os_DLL_finder, defined by 205register_hook()

os_transaction_hook, defined by 416registry location on Windows 109Regular

os_member_variable, defined by 251rehost_all_links()

os_dbutil, defined by 189rehost_link()

os_dbutil, defined by 189Relationship

os_member, defined by 243release()

os_address_space_marker, defined by 99os_persistent_to_transient_pointer_

manager, defined by 277os_retain_address, defined by 329

release_address_space()

os_object_cursor, defined by 269release_cleared_persistent_to_transient_

pointers()

objectstore, defined by 79release_maintenance()

objectstore, defined by 80release_major()

objectstore, defined by 80release_minor()

objectstore, defined by 80release_name()

objectstore, defined by 81release_persistent_addresses()

objectstore, defined by 81release_pointer()

os_cluster, defined by 133os_database, defined by 166os_database_root, defined by 173os_segment, defined by 358tix_exception, defined by 454

remote schemas 151remove()

os_dbutil, defined by 190os_dynamic_extent, defined by 214

remove_db_from_archive()


Index

os_archiver, defined by 105remove_required_DLL_identifier()

os_database, defined by 167rename()

os_dbutil, defined by 190reset()

os_archiver_options, defined by 107os_backup_options, defined by 115os_cluster_cursor, defined by 139os_export_id_cursor, defined by 221os_mop, defined by 256os_object_cursor, defined by 269os_recover_options, defined by 292os_replicator_options, defined by 320os_restore_options, defined by 328os_segment_cursor, defined by 366

reset_persistent_addresses()

objectstore, defined by 81reset_statistics()

os_replicator, defined by 317resolve()

os_Dumper_reference, defined by 210os_Reference<T>, defined by 294os_reference_cross_session, defined by 300os_Reference_cross_session<T>, defined

by 296os_reference_internal, defined by 303os_Reference_protected<T>, defined by 305os_reference_protected_internal, defined

by 309os_soft_pointer32<T>, defined by 383os_soft_pointer32_base, defined by 376os_soft_pointer64<T>, defined by 386os_soft_pointer64_base, defined by 380

resolve_export_id()

os_segment, defined by 358retain()

os_address_space_marker, defined by 100retain_persistent_addresses()

objectstore, defined by 81retain_pointer()

os_cluster, defined by 134os_database, defined by 167os_database_root, defined by 173os_segment, defined by 358

retaining()

os_retain_address, defined by 329retrieving data member address using os_fetch_

address() 464retrieving data member value using os_

fetch() 461return_all_pages()

objectstore, defined by 81return_memory()


rmdir()

os_dbutil, defined by 190RPC exceptions 511

Sschema evolution 46

exceptions 508transformer functions 333

schema keysobjectstore::set_current_schema_key() 86os_database::change_schema_key() 149os_database::freeze_schema_key() 153

schemasSee also component schemasOS_MARK_SCHEMA_TYPE(), the macro 482OS_MARK_SCHEMA_TYPESPEC(), the macro 483remote 151

segment_number


os_pathname_segment_cluster, defined by 276segment_of()

os_cluster, defined by 134segment-level access control 362segments 44

defaultreturning 156setting 168

initial, returning 156initial, setting 168iterating over 365os_segment, the class 352transient 357

serversreconnecting to 367

session_of()

os_cluster, defined by 134os_database, defined by 167

Release 6.3 557

S

os_segment, defined by 359os_transaction, defined by 413

set()

os_object_cursor, defined by 270set_access()


set_access_control()

os_segment, defined by 359set_access_of_get_os_typespec_function()

os_class_type, defined by 127set_address_space_release_interval()


set_alignment()

os_type, defined by 425set_allocation_strategy()


set_always_check_server_connection_at_

commit()

objectstore, defined by 82set_always_null_illegal_pointers()

objectstore, defined by 83set_application_info()

os_database, defined by 168os_segment, defined by 360

set_application_schema_path()

os_dbutil, defined by 190set_application_schema_pathname()

objectstore, defined by 83set_arg_list()

os_function_type, defined by 228set_arg_list_kind()

os_function_type, defined by 228set_args()

os_template, defined by 400os_template_instantiation, defined by 405

set_asmarkers_useless()

objectstore, defined by 83set_auto_open_mode()

objectstore, defined by 83set_autoload_DLLs_function()

objectstore, defined by 83set_avoid_page_boundary()

os_compact, defined by 144

os_schema_evolution, defined by 341set_base_classes()

os_class_type, defined by 127set_base_member()

os_access_modifier, defined by 97set_cache_file()

objectstore, defined by 85set_cache_size()

objectstore, defined by 85set_call_linkage()

os_member_function, defined by 246set_class()

os_base_class, defined by 117set_class_kind()

os_class_type, defined by 127set_client_name()

objectstore, defined by 85os_dbutil, defined by 191

set_comment()

os_segment, defined by 360set_copy_member_functions()

os_schema_install_options, defined by 351set_current()

os_session, defined by 372set_current_schema_key()

objectstore, defined by 86set_decache_soft_pointers_after_address_

space_release()

objectstore, defined by 86set_declares_get_os_typespec_function()

os_class_type, defined by 127set_default()

os_segment_access, defined by 364set_default_address_space_partition_size()

objectstore, defined by 87set_default_cluster()

os_segment, defined by 360set_default_segment()

os_database, defined by 168set_defines_virtual_functions()

os_class_type, defined by 127set_disable_transformer_class_checks()

os_schema_evolution, defined by 342set_dispatch_table_pointer_offset()

os_class_type, defined by 128set_element_type()

os_array_type, defined by 108set_enclosing_namespace()


Index

os_namespace, defined by 258set_enumerators()

os_enum_type, defined by 216set_evolved_schema_db_name()

os_schema_evolution, defined by 342set_explanation_level()


set_fetch_policy()


set_final_offset()


set_handle_transient_faults()

objectstore, defined by 88set_has_constructor()

os_class_type, defined by 128set_has_destructor()

os_class_type, defined by 128set_incremental_schema_installation()

objectstore, defined by 88os_database, defined by 169

set_indirect_virtual_base_classes()

os_class_type, defined by 128set_instantiation()

os_instantiated_class_type, defined by 230set_introduces_virtual_functions()

os_class_type, defined by 128set_is_abstract()

os_class_type, defined by 128set_is_const()

os_anonymous_indirect_type, defined by 101os_member_function, defined by 246

set_is_forward_definition()

os_class_type, defined by 128set_is_inline()

os_member_function, defined by 246set_is_overloaded()

os_member_function, defined by 246set_is_persistent()

os_class_type, defined by 128set_is_pure_virtual()

os_member_function, defined by 246set_is_static()

os_member_function, defined by 246

set_is_virtual()

os_member_function, defined by 247set_is_volatile()

os_anonymous_indirect_type, defined by 101os_member_function, defined by 247

set_literal()

os_literal_template_actual_arg, defined by 237

set_locator_file()

objectstore, defined by 88set_lock_option()


set_lock_timeout()

objectstore, defined by 89set_log_file()

objectstore, defined by 89set_malloc_size()


set_maplet_size()


set_maximum_cluster_size()

os_compact, defined by 145os_schema_evolution, defined by 145, 343

set_maximum_memory_size()

os_compact, defined by 145os_schema_evolution, defined by 145, 343

set_members()

os_class_type, defined by 128os_namespace, defined by 258

set_name()

os_class_type, defined by 129os_enum_type, defined by 216os_enumerator_literal, defined by 217os_member_function, defined by 247os_member_variable, defined by 252os_named_indirect_type, defined by 257os_namespace, defined by 259os_pointer_literal, defined by 279os_template_formal_arg, defined by 404os_transaction, defined by 413

set_namespace()

os_member_namespace, defined by 248set_new_segment_reference_policy()

Release 6.3 559

S

os_database, defined by 170set_null_illegal_pointers()


set_number_of_elements()

os_array_type, defined by 108set_obsolete_index_handler()

os_schema_evolution, defined by 343set_obsolete_query_handler()

os_schema_evolution, defined by 343set_offset()

os_base_class, defined by 118os_member_variable, defined by 252

set_optimzie_checkpoints()

os_schema_evolution, defined by 345set_pathname_encoding()

objectstore, defined by 90set_persistent_to_transient_pointer()

objectstore, defined by 90set_pragmas()

os_class_type, defined by 129os_enum_type, defined by 216

set_pre_evolution_setup_hook()

os_schema_evolution, defined by 345set_primary_group()

os_segment_access, defined by 364set_propagate_on_commit()

objectstore, defined by 91set_queue_size()

os_notification, defined by 265set_reconnect_timeout_and_interval()

os_failover_server, defined by 223set_replacing_location()

os_Type_info, defined by 433set_reserve_as_mode()

objectstore, defined by 91set_resolve_ambiguous_void_pointers()

os_schema_evolution, defined by 345set_retain()

os_retain_address, defined by 329set_retain_persistent_addresses()

objectstore, defined by 91set_return_type()

os_function_type, defined by 228set_schema_database()

os_database, defined by 170

set_schema_database_pathname()


set_segment_reference_policy()

os_segment, defined by 357set_simple_auth_ui()

objectstore, defined by 92set_size()

os_cluster, defined by 136os_database, defined by 170os_field_member_variable, defined by 224os_type, defined by 425

set_size_in_sectors()

os_database, defined by 171set_source_position()

os_class_type, defined by 129os_enum_type, defined by 216os_member_function, defined by 247os_member_variable, defined by 252os_named_indirect_type, defined by 257

set_storage_class()

os_member_variable, defined by 253set_suppress_invalid_hard_pointer_errors()

objectstore, defined by 92set_target_class()

os_pointer_to_member_type, defined by 280set_target_type()

os_indirect_type, defined by 229os_pointer_type, defined by 281

set_task_list_file_name()

os_schema_evolution, defined by 345set_template()

os_template_instantiation, defined by 406set_thread_absorption()

os_session, defined by 372set_transaction_max_retries()

objectstore, defined by 92set_transaction_priority()

objectstore, defined by 92set_transient_delete_function()

objectstore, defined by 93set_type()

os_member_function, defined by 247os_member_type, defined by 249os_member_variable, defined by 253os_pointer_literal, defined by 279os_template_value_formal, defined by 408os_type_template, defined by 436


Index

os_type_template_actual_arg, defined by 437set_unhandled_exception_hook()

tix_exception, defined by 455set_union_variant()

objectstore, defined by 94set_untranslatable_pointer_handler()

os_schema_evolution, defined by 345set_value()

os_database_root, defined by 174os_enumerator_literal, defined by 217

set_virtual_base_class_no_pointer()

os_base_class, defined by 118set_virtual_base_class_pointer_offset()

os_base_class, defined by 118set_virtuals_redefined()

os_base_class, defined by 118should_use_default_constructor()

os_Dumper_specialization, defined by 212shutdown()

objectstore, defined by 94os_compact, defined by 146os_schema_evolution, defined by 345

signal()

objectstore_exception, defined by 96Signed_char

os_type, defined by 425Signed_long

os_type, defined by 426Signed_short

os_type, defined by 426size()

os_cluster, defined by 137os_database, defined by 171os_segment, defined by 361

size_in_sectors()

os_database, defined by 171soft-pointer decaching 86split_pathname()

os_dbutil, defined by 191sprint()


stack unwind 52start_and_run_backup()

os_backup, defined by 110start_and_run_recover()

os_recover, defined by 287start_and_run_restore()

os_restore, defined by 324start_archiver()

os_archiver, defined by 105start_backrest_logging()

os_dbutil, defined by 191start_backup()

os_backup, defined by 111start_recover()

os_recover, defined by 288start_replicator()

os_replicator, defined by 317start_restore()

os_restore, defined by 324stat()

os_dbutil, defined by 192Static

os_member_variable, defined by 251stop_archiverp()

os_archiver, defined by 105stop_backrest_logging()

os_dbutil, defined by 192stop_backup()

os_backup, defined by 111stop_recover()

os_recover, defined by 288stop_replicator()

os_replicator, defined by 317stop_restore()

os_restore, defined by 324storage

allocating 459strip_indirect_types()

os_type, defined by 426Struct

os_class_type, defined by 129subscribe()

os_notification, defined by 265svr_checkpoint()

os_dbutil, defined by 192svr_client_kill()

os_dbutil, defined by 192svr_debug()

os_dbutil, defined by 193svr_machine()

os_dbutil, defined by 193svr_ping()

os_dbutil, defined by 194svr_shutdown()

Release 6.3 561

T

os_dbutil, defined by 194svr_stat()


Ttake_a_snapshot()

os_archiver, defined by 105task_list()

os_schema_evolution, defined by 346time_created()

os_database, defined by 171TIX exception macros

TIX_END_HANDLE 492TIX_EXCEPTION 493TIX_HANDLE() 494TIX_HANDLE_IF() 497

TIX exceptionsSee also exceptionsDECLARE_EXCEPTION(), the macro 471DEFINE_EXCEPTION(), the macro 472

tix_context, the class 453TIX_END_HANDLE, the macro 492tix_exception, the class 454

ancestor_of() 454get_os_deadlock_exception() 454get_os_lock_timeout_exception() 454release_pointer() 454set_unhandled_exception_hook() 455

TIX_EXCEPTION, the macro 493TIX_HANDLE(), the macro 494TIX_HANDLE_IF(), the macro 497tix_handler, the class 456

get_current() 456get_exception() 456get_report() 456get_report0() 456get_value() 456

to_bit_field()

os_path_to_data, defined by 273to_dope()

os_path_to_data, defined by 273to_static_member()

os_path_to_data, defined by 273to_subscript()

os_path_to_data, defined by 273top_level()

os_transaction, defined by 413transactions

nesting 475OS_BEGIN_TXN(), the macro 474OS_BEGIN_TXN_NAMED(), the macro 478read-only 475update 475

transformer functions 333transient segments 357transient storage

allocating 459transiently allocated objects

and clustering 459creating 459

Type

os_member, defined by 243os_template, defined by 400os_type, defined by 427

type()

os_path_to_data, defined by 273type_at()

os_type, defined by 427type_containing()

os_type, defined by 427typespecs

os_typespec class 440

UUndefined

os_type, defined by 427Union

os_class_type, defined by 129unique_name()

os_path_to_data, defined by 273Unknown

os_function_type, defined by 227unload_DLL()

objectstore, defined by 94unregister()

os_DLL_finder, defined by 205Unsigned_char

os_type, defined by 427Unsigned_integer

os_type, defined by 427Unsigned_long

os_type, defined by 428Unsigned_short

os_type, defined by 428unsubscribe()

os_notification, defined by 266


Index

unuse_DLL()

os_session, defined by 372unwind, stack 52update

os_transaction, defined by 414update transactions 475use_DLL()

os_session, defined by 372utility API 178

VVariable

os_function_type, defined by 227os_member, defined by 243

virtual_base_class_has_pointer()

os_base_class, defined by 118virtuals_redefined()

os_base_class, defined by 118Void

os_type, defined by 428vsignal()

objectstore_exception, defined by 96

Wwhich_product()

objectstore, defined by 94Windows registry location 109with()

os_cluster, defined by 137

Release 6.3 563

W


C++ A P I Reference -...

Documents

Transcript of C++ A P I Reference -...