C C++ API REFERENCE

370 Pages·1998·1.13 MB·English

by  Object Design, Inc.

C C++
OLLECTIONS
API R
EFERENCE
RELEASE 5.1
March 1998
ObjectStore Collections C++ API Reference
ObjectStore Release 5.1, March 1998
ObjectStore, Object Design, the Object Design logo, LEADERSHIP BY DESIGN, and Object
Exchange are registered trademarks of Object Design, Inc. ObjectForms and Object Manager
are trademarks of Object Design, Inc.
All other trademarks are the property of their respective owners.
Copyright © 1989 to 1998 Object Design, Inc. All rights reserved. Printed in the United States
of America. Except as permitted under the Copyright Act of 1976, no part of this publication
may be reproduced or distributed in any form or by any means, or stored in a database or
retrieval system, without the prior written permission of the publisher.
COMMERCIAL ITEM — The Programs are Commercial Computer Software, as defined in
the Federal Acquisition Regulations and Department of Defense FAR Supplement, and are
delivered to the United States Government with only those rights set forth in Object
Design’s software license agreement.
Data contained herein are proprietary to Object Design, Inc., or its licensors, and may not be
used, disclosed, reproduced, modified, performed or displayed without the prior written
approval of Object Design, Inc.
This document contains proprietary Object Design information and is licensed for use
pursuant to a Software License Services Agreement between Object Design, Inc., and
Customer.
The information in this document is subject to change without notice. Object Design, Inc.,
assumes no responsibility for any errors that may appear in this document.
Object Design, Inc.
Twenty Five Mall Road
Burlington, MA 01803-4194
Part number:SW-OS-DOC-CRF-510
Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Chapter 2 Collection, Query, and Index Classes . . . . . . . . . . . . .3
os_Array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
os_array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
os_backptr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
os_Bag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
os_bag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
os_bound_query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
os_Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
os_collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
os_collection_size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
os_coll_query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
os_coll_range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
os_coll_rep_descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
os_Cursor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
os_cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
os_Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
os_dynamic_extent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
os_index_name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
os_index_path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
os_keyword_arg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
os_keyword_arg_list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
os_List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
os_list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
os_rDictionary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Release 5.1 iii
Contents
os_rep. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
os_Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
os_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Chapter 3 Representation Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
os_chained_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
os_dyn_bag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
os_dyn_hash. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
os_ixonly and os_ixonly_bc. . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
os_ordered_ptr_hash. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
os_packed_list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
os_ptr_bag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
os_vdyn_bag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
os_vdyn_hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Chapter 4 Macros and User-Defined Functions. . . . . . . . . . . . . 265
OS_MARK_DICTIONARY() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
OS_MARK_QUERY_FUNCTION(). . . . . . . . . . . . . . . . . . . . . . . . . 268
OS_MARK_RDICTIONARY(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
OS_TRANSIENT_DICTIONARY(). . . . . . . . . . . . . . . . . . . . . . . . . . 270
OS_TRANSIENT_DICTIONARY_NOKEY() . . . . . . . . . . . . . . . . . . 271
OS_TRANSIENT_RDICTIONARY(). . . . . . . . . . . . . . . . . . . . . . . . . 272
os_index(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
os_index_key() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
os_index_key_hash_function(). . . . . . . . . . . . . . . . . . . . . . . . . 275
os_index_key_rank_function() . . . . . . . . . . . . . . . . . . . . . . . . . 276
os_indexable_body() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
os_indexable_member() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
os_query_function(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
os_query_function_body(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
os_query_function_body_returning_ref(). . . . . . . . . . . . . . . . 282
os_query_function_returning_ref(). . . . . . . . . . . . . . . . . . . . . . 283
os_rel_1_1_body(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
os_rel_1_m_body(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
os_rel_m_1_body(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
os_rel_m_m_body() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
os_rel_1_1_body_options() . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
os_rel_1_m_body_options(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
iv ObjectStore Collections C++ API Reference
Contents
os_rel_m_1_body_options(). . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
os_rel_m_m_body_options() . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
os_relationship_1_1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
os_relationship_1_m() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
OS_RELATIONSHIP_LINKAGE() . . . . . . . . . . . . . . . . . . . . . . . . . . 304
os_relationship_m_1() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
os_relationship_m_m(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Chapter 5 C Library Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311
os_backptr Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312
os_bound_query Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . .313
os_collection Functions and Enumerators. . . . . . . . . . . . . . .314
os_coll_query Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .325
os_coll_rep_descriptor Functions . . . . . . . . . . . . . . . . . . . . . .327
os_cursor Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329
os_index_path Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334
Appendix Predefined TIX Exceptions . . . . . . . . . . . . . . . . . . . . . . . .335
Parent Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .336
Predefined Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .338
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Release 5.1 v
Contents
vi ObjectStore Collections C++ API Reference
Preface
Purpose The ObjectStore Collections C++ API Referenceprovides a reference
on C++ programming interfaces to ObjectStore for collections,
queries, and indexes. This book supports ObjectStore Release 5.1.
Audience This book assumes the reader is experienced with C++.
Scope Information in this book assumes that ObjectStore is installed and
configured.
How This Book Is Organized
The manual has five chapters and an appendix:
It begins with an introductory chapter. Each chapter after that
covers a type of interface, including classes, representation types,
macros, user-supplied functions, and the C library interface.
Within each chapter, material is organized alphabetically.
Topic Location
Database services Chapter 1, Introduction, on
page1
The C++ API for ObjectStore Chapter 2, Collection, Query,
collections, queries, and and Index Classes, on page3
indexes
Representation types Chapter 3, Representation Types,
on page245
System-supplied macros Chapter 4, Macros and User-
User-defined functions Defined Functions, on page265
C library interface Chapter 5, C Library Interface, on
page309
Release 5.1 vii
Preface
Topic Location
Exceptions Appendix, Predefined TIX
Exceptions, on page335
viii ObjectStore Collections C++ API Reference
Preface
Notation Conventions
This document uses the following conventions:
Convention Meaning
Bold Bold typeface indicates user input or code.
Sans serif Sans serif typeface indicates system
output.
Italic sans serif Italic sans serif typefaceindicates a
variable for which you must supply a
value. This most often appears in a syntax
line or table.
Italic serif In text, italic serif typeface indicates the
first use of an important term.
[ ] Brackets enclose optional arguments.
{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 specifya orb orc.
... Three consecutive periods indicate that
you can repeat the immediately previous
item. In examples, they also indicate
omissions.
Indicates that the operating system named
UNIX UNIX inside the circle supports or does not
support the feature being discussed.
ObjectStore C++ Release 5.1 Documentation
The ObjectStore Release 5.1 documentation is chiefly distributed
on line in web-browsable format. If you want to order printed
books, contact your Object Design sales representative.
Your use of ObjectStore documentation depends on your role and
level of experience with ObjectStore. You can find an overview
description of each book in the ObjectStore documentation set at
URLhttp://www.objectdesign.com. SelectProducts and then select
Product Documentation to view these descriptions.
Release 5.1 ix
Preface
Internet Sources for More Information
World Wide Web Object Design’s support organization provides a number of
information resources. These are available to you through a web
browser such as Mosaic or Netscape. You can obtain information
by accessing the Object Design home page with the URL
http://www.objectdesign.com. Select Technical Support. Select
Support Communicationsfor detailed instructions about different
methods of obtaining information from support.
Internet gateway You can obtain such information as frequently asked questions
(FAQs) from Object Design’s Internet gateway machine as well as
from the web. This machine is called ftp.objectdesign.comand its
Internet address is 198.3.16.26. You can use ftp to retrieve the
FAQs from there. Use the login nameodiftp and the password
obtained frompatch-info. This password also changes monthly,
but you can automatically receive the updated password by
subscribing topatch-info. See theREADME file for guidelines for
using this connection. The FAQs are in the subdirectory./FAQ.
This directory contains a group of subdirectories organized by
topic. The file./FAQ/FAQ.tar.Z is a compressedtar version of this
hierarchy that you can download.
Automatic email In addition to the previous methods of obtaining Object Design’s
notification latest patch updates (available on theftp server as well as the
Object Design Support home page) you can now automatically be
notified of updates. To subscribe, send email topatch-info-
[e-mail] with the keywordSUBSCRIBE patch-
info <your siteid> in the body of your email. This will subscribe you
to Object Design’s patch information server daemon that
automatically provides site access information and notification of
other changes to the on-line support services. Your site ID is listed
on any shipment from Object Design, or you can contact your
Object Design Sales Administrator for the site ID information.
Training
If you are in North America, for information about Object
Design’s educational offerings, or to order additional documents,
call 781.674.5000, Monday through Friday from 8:30 AM to 5:30
PM Eastern Time.
If you are outside North America, call your Object Design sales
representative.
x ObjectStore Collections C++ API Reference