os_pvar

One way to deal with this situation is to re-retrieve the pointer in each subsequent transaction in which it is required. However, a convenient alternative is provided by ObjectStore pvars. These allow you to maintain, across transactions, a valid pointer to an entry-point object.

To use pvars, you define the variable you want to hold the pointer to the entry point. Then you pass the variable's address to the function os_pvar::os_pvar(), along with the name of the root that points to the desired entry-point object, and a pointer to the database containing the root.

This function is the constructor for the class os_pvar, but you never have to explicitly use the instance of os_pvar that results. Once you have called this function, ObjectStore automatically maintains an association between the variable and the entry point. At the beginning of each transaction in the current process, if the database containing the specified root is open, ObjectStore establishes a valid pointer to the entry-point object as the value of the variable. It also sets the variable to point to the entry point when the database becomes open during a transaction.

Instances of os_pvar must be allocated on the stack, not the heap, so do not create os_pvars with operator new().

As with os_database_root::get_value(), you can also supply an os_typespec* to os_pvar::os_pvar(), for additional type safety. ObjectStore will check that the specified typespec matches the typespec stored with the root. Note that it checks only that the typespec supplied matches the stored typespec, and does not check the type of the entry-point object itself.

Note that, even though you can use this variable from one transaction to the next without re-retrieving its value, you cannot use it between transactions. As always, you must be within a transaction to access persistent data. Between transactions, ObjectStore automatically sets the variable to 0. The variable is also set to 0 during a transaction if the database containing its associated root is closed.

Note also that you should not try to set the value of this variable, since ObjectStore handles all assignments of values to it.

You can also create an entry point and root using os_pvar::os_pvar() by supplying a pointer to an initialization function. The function should allocate the entry-point object in a given database and return a pointer to the new object.

This function will be executed upon the call to os_pvar() or at the beginning of subsequent transactions, if the database to contain the root is open and ObjectStore cannot find the specified root in that database. It will also be called when this database becomes open during a transaction and ObjectStore cannot find the root in that database.

The predefined functions os_pvar::init_pointer(), os_pvar::init_int(), and os_pvar::init_long() can be used as initialization functions. They allocate pointers, ints, and longs, respectively, and initialize them to 0.

os_pvar::os_pvar()

os_pvar(
      os_database_p db, 
      os_void_p location, 
      os_char_p root_name, 
      os_typespec *typespec = 0, 
      os_void_p(*init_fn)(os_database*) = 0
);

Instances of os_pvar must be allocated on the stack, not the heap, so do not create os_pvars with operator new().

os_pvar::~os_pvar()

~os_pvar();

os_pvar::init_pointer()

static void *init_pointer(os_database *db);

os_pvar::init_int()

static void *init_int(os_database *db);

os_pvar::init_long()

static void *init_long(os_database *db);

Updated: 03/31/98 17:25:09