ObjectStore provides C functions and macros analogous to many of the functions in the ObjectStore C++ class and function libraries. This chapter presents the C library interface for ObjectStore, which allows C programs to access basic ObjectStore functionality.
Topics
This chapter presents the ObjectStore C library interface for collections and queries. For information on the interface for other features, see the ObjectStore C++ API Reference.
To access the C library interface, include the following directive in your C programs:
#include <ostore/ostore.h>Note that this header file provides access to ObjectStore's exception facility, which provides a stock of predefined errors that can be signaled at run time. For more information, see Appendix, Predefined TIX Exceptions.
To use ObjectStore collections, also include
#include <ostore/coll.h>Calling the C interface from a C++ main program requires the following directives in the following order:
#define _PROTOTYPES
#include <ostore/ostore.hh>
extern "C" {
#include <ostore/ostore.h>
}
To use collections, follow this with
#include <ostore/coll.hh>
extern "C" {
#include <ostore/coll.h>
}
os_backptr Functions
The C library interface contains macros for index maintenance analogous to members of the class os_backptr in the ObjectStore class library: os_indexable_setvalue() and os_indexable_body_with_copy(). These functions are used for index maintenance in conjunction with the macros os_indexable_member(), os_indexable_body(), os_index(), and os_index_key(). (See Chapter 4, System-Supplied Macros and User-defined Functions, on page 283 for further information.) os_bound_query Functions
The C library interface contains functions analogous to those of the class os_bound_query in the ObjectStore class library. os_bound_query_create
extern os_bound_query* os_bound_query_create(
os_coll_query*, /* the query to bind */
os_keyword_arg_list* /* the arg list with binding for free vars */
);
Creates a bound query. See os_bound_query::os_bound_query().extern void os_bound_query_delete(
os_bound_query*
);
Deletes the specified bound query.
extern void os_collection_add_index(
os_collection*, /* the collection to be indexed */
os_index_path*, /* the index path */
unsigned int /* index options */
);
See os_collection::add_index().
os_collection_add_index_in_seg
extern void os_collection_add_index_in_seg(
os_collection*, /* the collection to be indexed */
os_index_path*, /* the index path */
unsigned int, /* index options */
os_segment* /* segment of the index */
);
See os_collection::add_index().extern os_collection* os_collection_bound_query(
os_collection*, /* the collection to query */
os_bound_query* /* the query to apply */
);
See os_collection::query().
os_collection_bound_query_exists
extern int os_collection_bound_query_exists(
os_collection*, /* the collection to query */
os_bound_query* /* the existential query to apply */
);
See os_collection::exists().
os_collection_bound_query_pick
extern void* os_collection_bound_query_pick(
os_collection*, /* the collection to query */
os_bound_query* /* the pick query to apply */
);
See os_collection::query_pick().extern unsigned int os_collection_cardinality(
os_collection* /* the collection */
);
See os_collection::cardinality().extern void os_collection_change_behavior(
os_collection*,
unsigned int, /* new behavior flags */
int /* true means verify that coll meets behavior */
);
See os_collection::change_behavior().extern void os_collection_change_rep(
os_collection*, /* the collection to be changed */
unsigned int, /* the new expected size */
os_coll_rep_descriptor*,
/* the rep policy descriptor to change to (or 0) */
int /* true means retain rep policy descriptor */
);
See os_collection::change_rep().extern void os_collection_clear(
os_collection* /* the collection to clear */
);
See os_collection::clear().extern int os_collection_contains(
os_collection*, /* the collection */
void* /* the element to search for */
);
See os_collection::contains().extern void os_collection_copy(
/* copy source elements to destination */
os_collection*, /* destination */
os_collection* /* source */
);
See os_collection::operator =().extern unsigned int os_collection_count(
os_collection*, /* the collection */
void* /* the element to count */
);
See os_collection::count().extern os_collection* os_collection_create(
os_database*, /* where to create */
unsigned int, /* flags denoting desired behavior (or 0) */
int, /* expected size (or 0) */
os_coll_rep_descriptor *, /* representation policy (or 0) */
int /* true means retain policy descriptor */
);
See os_collection::create().
os_collection_create_in_cluster
extern os_collection* os_collection_create_in_cluster(
os_object_cluster*, /* where to create */
unsigned int, /* flags denoting desired behavior (or 0) */
int, /* expected size (or 0) */
os_coll_rep_descriptor *, /* representation policy (or 0) */
int /* true means retain policy descriptor */
);
See os_collection::create().extern os_collection* os_collection_create_in_seg(
os_segment*, /* where to create */
unsigned int, /* flags denoting desired behavior (or 0) */
int, /* expected size (or 0) */
os_coll_rep_descriptor *, /* representation policy (or 0) */
int /* true means retain policy descriptor */
);
See os_collection::create().extern os_collection* os_collection_create_near(
void*, /* where to create */
unsigned int, /* flags denoting desired behavior (or 0) */
int, /* expected size (or 0) */
os_coll_rep_descriptor *, /* representation policy (or 0) */
int /* true means retain policy descriptor */
);
See os_collection::create().extern void os_collection_delete(
os_collection* /* the collection to delete */
);
Deletes the specified collection.
extern void os_collection_difference(
/* subtract source elements from destination */
os_collection*, /* destination */
os_collection* /* source */
);
See os_collection::operator -().extern void os_collection_drop_index(
os_collection*, /* the collection with the index */
os_index_path* /* the index to drop */
);
See os_collection::drop_index().extern int os_collection_empty(
os_collection* /* check if the collection is empty */
);
See os_collection::empty().extern int os_collection_equal(
os_collection*,
os_collection*
);
See os_collection::operator ==().extern unsigned int os_collection_get_behavior(
/* return flags denoting behavior */
os_collection*
);
See os_collection::get_behavior().extern os_coll_rep_descriptor* os_collection_get_rep(
os_collection*
);
See os_collection::get_rep().extern int os_collection_greater_than(
os_collection*,
os_collection*
);
See os_collection::operator >().
os_collection_greater_than_or_equal
extern int os_collection_greater_than_or_equal(
os_collection*,
os_collection*
);
See os_collection::operator >=().extern int os_collection_has_index(
os_collection*, /* the collection to look for an index on */
os_index_path*, /* the index to look for */
int /* true if looking for an ordered index */
);
See os_collection::has_index().extern void os_collection_initialize();See os_collection::initialize().
extern void os_collection_insert(
os_collection*, /* the collection */
void* /* the element to insert */
);
See os_collection::insert().
os_collection_insert_after_cursor
extern void os_collection_insert_after_cursor(
os_collection*,
void*,
os_cursor*
);
See os_collection::insert_after().
os_collection_insert_after_position
extern void os_collection_insert_after_position(
os_collection*,
void*,
unsigned int
);
See os_collection::insert_after().
os_collection_insert_before_cursor
extern void os_collection_insert_before_cursor(
os_collection*,
void*,
os_cursor*
);
See os_collection::insert_before().
os_collection_insert_before_position
extern void os_collection_insert_before_position(
os_collection*,
void*,
unsigned int
);
See os_collection::insert_before().extern void os_collection_insert_first(
os_collection*, /* the collection */
void* /* the element to insert */
);
See os_collection::insert_first().
extern void os_collection_insert_last(
os_collection*, /* the collection */
void* /* the element to insert */
);
See os_collection::insert_last().
extern void os_collection_intersect(
os_collection*, /* destination */
os_collection* /* source */
);
See os_collection::operator &().
extern int os_collection_less_than(
os_collection*,
os_collection*
);
See os_collection::operator <().
extern int os_collection_less_than_or_equal(
os_collection*,
os_collection*
);
See os_collection::operator <=().
extern int os_collection_not_equal(
os_collection*,
os_collection*
);
See os_collection::operator !=().
extern void* os_collection_only(
os_collection*
);
See os_collection::only().
extern int os_collection_ordered_equal(
os_collection*,
os_collection*
);
See os_collection::operator ==().
extern void* os_collection_pick(
os_collection*
);
See os_collection::pick().
extern os_collection* os_collection_query(
os_collection*, /* the collection to query */
char*, /* the string denoting the element type */
char*, /* the string denoting the query expression */
os_database*, /* the database from which to get the schema */
char*, /* name of file (for error printing) or 0 */
unsigned int /* line number in file (for error printing) or 0 */
);
See os_collection::query().
extern int os_collection_query_exists(
os_collection*, /* the collection to query */
char*, /* the string denoting the element type */
char*, /* the string denoting the query expression */
os_database*, /* the database from which to get the schema */
char*, /* name of file (for error printing) or 0 */
unsigned int /* line number in file (for error printing) or 0 */
);
See os_collection::exists().extern void* os_collection_query_pick(
os_collection*, /* the collection to query */
char*, /* the string denoting the element type */
char*, /* the string denoting the query expression */
os_database*, /* the database from which to get the schema */
char*, /* name of file (for error printing) or 0 */
unsigned int /* line number in file (for error printing) or 0 */
);
See os_collection::query_pick().extern int os_collection_remove(
os_collection*, /* the collection */
void* /* the element to remove */
);
See os_collection::remove().
os_collection_remove_at_cursor
extern void os_collection_remove_at_cursor(
os_collection*,
os_cursor*
);
See os_collection::remove_at().
os_collection_remove_at_position
extern void os_collection_remove_at_position(
os_collection*,
unsigned int
);
See os_collection::remove_at().extern void* os_collection_remove_first(
os_collection*
);
See os_collection::remove_first().extern void* os_collection_remove_last(
os_collection*
);
See os_collection::remove_last().
os_collection_replace_at_cursor
extern void* os_collection_replace_at_cursor(
os_collection*,
void*,
os_cursor*
);
See os_collection::replace_at().
os_collection_replace_at_position
extern void* os_collection_replace_at_position(
os_collection*,
void*,
unsigned int
);
See os_collection::replace_at().
os_collection_retrieve_at_cursor
extern void* os_collection_retrieve_at_cursor(
os_collection*,
os_cursor*
);
See os_collection::retrieve().
os_collection_retrieve_at_position
extern void* os_collection_retrieve_at_position(
os_collection*,
unsigned int
);
See os_collection::retrieve().extern void* os_collection_retrieve_first(
os_collection*
);
See os_collection::retrieve_first().extern void* os_collection_retrieve_last(
os_collection*
);
See os_collection::retrieve_last().extern void os_collection_union(
/* union source elements into destination */
os_collection*, /* destination */
os_collection* /* source */
);
See os_collection::operator |().
os_coll_query Functions
The C library interface contains functions analogous to those of the class os_coll_query in the ObjectStore Class Library. os_coll_query_create
extern os_coll_query *os_coll_query_create(
char*, /* string denoting the element type */
char*, /* string denoting the query expression */
os_database*, /* schema for query interpretation */
os_int32, /* true means cache the query in db */
char*, /* file name (for error messages) or 0 */
unsigned /* line number in file or 0 */
);
Creates a query. See os_coll_query::create().extern os_coll_query *os_coll_query_create_exists(
char*, /* string denoting the element type */
char*, /* string denoting the query expression */
os_database* , /* schema for query interpretation */
os_int32, /* true means cache the query persistently in db */
char*, /* file name (for error messages) or 0 */
unsigned /* line number in file or 0 */
);
Creates an existential query. See os_coll_query::create_exists().
os_coll_query_create_exists_in_seg
extern os_coll_query *os_coll_query_create_exists_in_seg(
char*, /* string denoting the element type */
char*, /* string denoting the query expression */
os_segment*, /* schema for query interpretation */
os_int32, /* true means cache the query in db */
char*, /* file name (for error messages) or 0 */
unsigned /* line number in file or 0 */
);
Creates an existential query in the specified segment. See os_coll_query::create_exists().extern os_coll_query *os_coll_query_create_in_seg(
char*, /* string denoting the element type */
char*, /* string denoting the query expression */
os_segment*, /* schema for query interpretation */
os_int32, /* true means cache the query persistently in seg */
char*, /* file name (for error messages) or 0 */
unsigned /* line number in file or 0 */
);
Creates a query in the specified segment. See os_coll_query::create().extern os_coll_query *os_coll_query_create_pick(
char*, /* string denoting the element type */
char*, /* string denoting the query expression */
os_database*, /* schema for query interpretation */
os_int32, /* true means cache the query persistently in db */
char*, /* file name (for error messages) or 0 */
unsigned /* line number in file or 0 */
);
Creates a single-element query. See os_coll_query::create_pick().
os_coll_query_create_pick_in_seg
extern os_coll_query *os_coll_query_create_pick_in_seg(
char*, /* string denoting the element type */
char*, /* string denoting the query expression */
os_segment*, /* schema for query interpretation */
os_int32, /* true means cache the query in seg */
char*, /* file name (for error messages) or 0 */
unsigned /* line number in file or 0 */
);
Creates a single-element query in the specified segment. See os_coll_query::create_pick().
os_coll_rep_descriptor Functions
The C library interface contains functions analogous to those of the class os_coll_rep_descriptor in the ObjectStore Class Library. os_coll_rep_descriptor
extern os_coll_rep_descriptor* os_coll_get_packed_list_rep_ descriptor();Returns an os_packed_list rep descriptor.
extern os_coll_rep_descriptor* os_coll_get_ptr_bag_list_rep_ descriptor();Returns an os_ptr_bag rep descriptor.
extern os_coll_rep_descriptor* os_coll_get_ptr_hash_rep_ descriptor();Returns an os_ptr_hash rep descriptor.
extern os_coll_rep_descriptor* os_coll_get_tinyarray_rep_ descriptor();Returns an os_tinyarray rep descriptor.
extern unsigned os_coll_rep_descriptor_allowed_behavior(
os_coll_rep_descriptor*
/* return the behavior that this rep supports */
);
Returns a bit pattern indicating the behavior supported by the specified rep descriptor.
extern os_coll_rep_descriptor* os_coll_rep_descriptor_copy(
os_coll_rep_descriptor,
/* make a copy of this rep descriptor */
os_segment * /* in this segment */
);
Copies the specified descriptor. See os_coll_rep_descriptor::copy().
os_coll_rep_descriptor_get_grow
extern os_coll_rep_descriptor* os_coll_rep_descriptor_get_grow(
os_coll_rep_descriptor*
/* return this descriptor's grow-into descriptor */
);
Returns the rep descriptor that becomes active when the specified rep descriptor's maximum cardinality is exceeded.
extern unsigned os_coll_rep_descriptor_get_max_size(
os_coll_rep_descriptor*
/* return this descriptor's max size */
);
Returns the upper bound of the specified rep descriptor's associated cardinality range.
extern unsigned os_coll_rep_descriptor_get_min_size(
os_coll_rep_descriptor*
/* return this descriptor's min size */
);
Returns the lower bound of the specified rep descriptor's associated cardinality range.
extern os_coll_rep_descriptor* os_coll_rep_descriptor_get_shrink(
os_coll_rep_descriptor*
/* return this descriptor's shrink-into descriptor */
);
Returns the rep descriptor that becomes active when the specified rep descriptor's minimum cardinality threshold is passed.
extern unsigned os_coll_rep_descriptor_required_behavior(
os_coll_rep_descriptor*
/* return the behavior that this rep requires */
);
Returns a bit pattern indicating the behavior required of collections with the specified representation.
extern void os_cursor_copy(
os_cursor*, /* destination */
os_cursor* /* source */
);
Copies source to destination.
extern os_cursor* os_cursor_create(
os_collection*, /* create a cursor over this collection */
int /* true means allow for updates during iteration */
);
Creates a cursor for the specified collection. See os_cursor::os_cursor().extern os_cursor* os_cursor_create_in_cluster(
os_object_cluster*, /* create in this cluster */
os_collection*, /* create a cursor over this collection */
os_int32 /* bitmask option: forward/reverse, order_by_address */
/* safe/unsafe etc, enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().extern os_cursor* os_cursor_create_in_db(
os_database*, /* create in this database */
os_collection*, /* create a cursor over this collection */
os_int32 /* bitmask: forward/reverse, order_by_address */
/* safe/unsafe enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().extern os_cursor* os_cursor_create_in_seg(
os_segment*, /* create in this segment */
os_collection*, /* create a cursor over this collection */
os_int32 /* bitmask option: forward/reverse, order_by_address */
/* safe/unsafe etc, enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().extern os_cursor* os_cursor_create_near(
void*, /* where to create this */
os_collection*, /* create a cursor over this collection */
os_int32 /* bitmask: forward/reverse, order_by_address */
/* safe/unsafe, etc enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().extern os_cursor* os_cursor_create_options(
os_collection*, /* create a cursor over this collection */
os_int32 /* bitmask: forward/reverse, order_by_address */
/* safe/unsafe etc, enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().extern void os_cursor_delete(
os_cursor*
);
Destroys the specified cursor and frees its associated memory.
extern void* os_cursor_first(
os_cursor* /* put the cursor on the first element and return it */
);
See os_cursor::first().extern void os_cursor_insert_after(
os_cursor*,
/* insert after this position, in the cursor's collection */
void* /* element to insert */
);
See os_cursor::insert_after().extern void os_cursor_insert_before(
os_cursor*,
*insert before this position, in the cursor's collection */
void* /* element to insert */
);
See os_cursor::insert_before().extern void* os_cursor_last(
os_cursor* /* put the cursor on the last element and return it */
);
See os_cursor::last().extern int os_cursor_more(
os_cursor* /* return true if this cursor is not null */
);
See os_cursor::more().extern void* os_cursor_next(
os_cursor* /* put the cursor on the next element and return it */
);
See os_cursor::next().extern int os_cursor_null(
os_cursor* /* return true if this cursor is null */
);
See os_cursor::null().extern os_cursor* os_cursor_ordered_create(
os_collection*, /* create a cursor over this collection */
os_index_path*, /* path to codify order of an ordered iteration */
os_int32 /* true means allow for updates during iteration */
);
See os_cursor::os_cursor().
os_cursor_ordered_create_in_cluster
extern os_cursor* os_cursor_ordered_create_in_cluster(
os_object_cluster*, /* create cursor in this cluster */
os_collection*, /* create a cursor over this collection */
os_index_path*, /* path to codify order of an ordered iteration */
os_int32 /* bitmask option: forward/reverse, order_by_address */
/* safe/unsafe etc, enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().
os_cursor_ordered_create_in_db
extern os_cursor* os_cursor_ordered_create_in_db(
os_database*, /* create in this database */
os_collection*, /* create a cursor over this collection */
os_index_path*, /* path to codify order of an ordered iteration */
os_int32 /* bitmask option: forward/reverse, order_by_address */
/* safe/unsafe etc, enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().
os_cursor_ordered_create_in_seg
extern os_cursor* os_cursor_ordered_create_in_seg(
os_segment*, /* create in this segment */
os_collection*, /* create a cursor over this collection */
os_index_path*, /* path to codify order of an ordered iteration */
os_int32 /* bitmask option: forward/reverse, order_by_address */
/* safe/unsafe etc, enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().extern os_cursor* os_cursor_ordered_create_near(
void *, /* create cursor in this */
os_collection*, /* create a cursor over this collection */
os_index_path*, /* path to codify order of an ordered iteration */
os_int32 /* bitmask: forward/reverse, order_by_address */
/* safe/unsafe, etc enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().
os_cursor_ordered_create_options
extern os_cursor* os_cursor_ordered_create_options(
os_collection*, /* create a cursor over this collection */
os_index_path*, /* path to codify order of an ordered iteration */
os_int32 /* bitmask option: forward/reverse, order_by_address */
/* safe/unsafe etc, enums */
/* safe allow for updates during iteration */
);
See os_cursor::os_cursor().extern void* os_cursor_previous(
os_cursor*
/* put the cursor on the previous element and return it */
);
See os_cursor::previous().extern void os_cursor_remove_at(
os_cursor*
/* remove the element in the collection at this position */
);
See os_cursor::remove_at().extern void* os_cursor_retrieve(
os_cursor* /* return the element at the current cursor position */
);
See os_cursor::retrieve().extern int os_cursor_valid(
os_cursor* /* return true if this cursor is at an element */
);
See os_cursor::valid().
os_index_path Functions
The C library interface contains functions analogous to those of the class os_index_path in the ObjectStore Class Library. os_index_path_create
extern os_index_path* os_index_path_create(
char*, /* string denoting element type (start of path) */
char*, /* string denoting the path */
os_database* /* database in which to create path */
);
Creates an index path. See os_index_path::create().extern os_index_path* os_index_path_create_in_seg(
char*, /* string denoting element type (start of path) */
char*, /* string denoting the path */
os_segment* /* segment in which to create path */
);
Creates an index path. See os_index_path::create().extern void os_index_path_delete(
os_index_path*
);
Deletes an index path. See os_index_path::destroy().Updated: 03/31/98 15:58:14