Chapter 18: Support Classes, Types, and Macros

   char            sign;
   char            chart;
   unsigned char   dig[10];

}  o_bcd;

Store binary coded decimal floating point numbers with a precision of 18 digits in the range 10^-64 to 10^+63.

Parameters are:

sign

In a query, you can use the following comparison operators to compare o_bcd values:

                       C api      C++ operator

equal                  O_EQ       ==
not equal              O_NE       !=
less than              O_LT       <
less than or equal     O_LE       <=
greater than           O_GT       >
greater than or equal  O_GE       >=

On attributes of type o_bcd, you can create hash and b-tree indices.

There are no routines that operate on o_bcd or to convert them to and from other numeric types.

As with all VERSANT data types, o_bcd can be used across platforms and operating systems.

You must define arithmetic operators on o_bcd if you want to add, subtract, multiply, and divide. The recommended way to do this is to create an O_BCD C++ class that overloads the arithmetic operators. For example:

class O_BCD
{
   private:
      o_bcd data_member;
   public:
      friend O_BCD operator +(const O_BCD&, const O_BCD&);
      friend O_BCD operator -(const O_BCD&, const O_BCD&);
      friend O_BCD operator *(const O_BCD&, const O_BCD&);
      friend O_BCD operator /(const O_BCD&, const O_BCD&);
}

For example, the following class uses O_BCD:

class UserClass : public PObject {
   private:
      O_BCD my_balance; // bank account balance
   public:
      void a_method();
};

The following shows a query on UserClass::my_balance:

PAttribute mybal = "UserClass::my_balance.O_BCD::data_member";
O_BCD hundred_bucks = 100.0;
PPredicate pred = (mybal >= hundred_bucks.O_BCD::data_member);
PClassObject<UserClass>::Object().select(my_db,TRUE,pred);

In the above, notice it is necessary to know that the data member inside o_bcd is named Val, just as it is necessary to know the data member inside a VString is named s when you do a query on a VString that is embedded inside a defined class. Also, the .Val field must be named on the hundred_bucks object, so that the kernel type o_bcd is present in the predicate expression.

   /* starting parameters */
   o_bool    be_logging_enabled;
   o_bool    be_locking_enabled;
   o_bool    be_commit_flush;
   o_u4b     be_llog_buf_size;
   o_u4b     be_plog_buf_size;
   o_u4b     be_heap_size;
   o_u4b     be_max_page_buffs;
   o_u4b     be_lock_wait_timeout;
};

Data type used to manipulate database server process profiles.

See the Database Administration Manual for an explanation of each parameter.

1-byte boolean type that is either TRUE or FALSE.

The Boolean type o_bool can be used as an attribute type. True and false are defined as follows.

TRUE

Name of a database that is connected in the current session. See o_clientconnectinfo().

Name of a class.

Name of a class.

   o_u4b     ci_connection_id;
   o_u4b     ci_server_pid;

}  o_connectinfo;

This data type describes a database connection.

The range 5,881,546 B.C. to year 5,885,486 is covered. Negative (2^31) (0x80000000) represents a null value.

You can create indexes and query on this type.

   o_dbname     dbname;
   o_4b         dbid;
   o_dbtype     dbtype;
   o_4b         dbgid;
   o_u1b        dbowner[O_NAME_SIZE];
   o_u1b        dbcreate[O_DATETIME_SIZE];
   o_u1b        dbversion[O_VERSION_SIZE];

} o_dblistdesc;

Data structure for the description of a database.

Elements:

dbname

O_DB_PERSONAL

Name of a database optionally including a site name prefixed with the @ sign. The length is 286 bytes.

See also vpp_dbname.

Name of a database optionally including a site name prefixed with the @ sign. The o_dbname_const datatype is defined as const char*.

    o_u4b   msg_len;
    o_uid   trid;
    o_u4b   dbid;
    o_u4b   event_seqno;
    loid    obj_event_defined;
    loid    obj_event_raised;
    o_u4b   event_type;
    o_4b    timestamp;
    o_u4b   definer_info_offset;
    o_u4b   definer_info_len;
    o_u4b   raiser_info_offset;
    o_u4b   raiser_info_len;
    loid    regid;
}   o_event_msg;

Store an event message.

The event message fields are:

msg_len

   o_u1b     version[O_VERSION_SIZE];
   o_u1b     rootpath[O_PATH_SIZE];
   o_u1b     dbpath[O_PATH_SIZE];
   o_u1b     vrtpath[O_PATH_SIZE];

}  o_envinfo;

Data structure for database environmental data.

Elements:

version

   char*     alias_name;
   char*     alias_expansion; };

Data type used to manipulate database application process profiles.

See the Database Administration Manual for an explanation of each parameter.

   o_u4b               fe_heap_size;
   o_u4b               fe_swap_threshold;
   o_u4b               fe_connection_count;
   char**              fe_connection_array;
   o_u4b               fe_alias_count;
   struct o_fe_alias*  fe_alias_array;

};

Data type used to manipulate database application process profiles.

See the Database Administration Manual for an explanation of each parameter.

   O_IT_BTREE,
   O_IT_HASH

}  o_indextype;

A type of index.

Options are:

O_IT_BTREE

An o_interval value is the result of subtracting an o_date value from another o_date value, an o_time value from another o_time value, or an o_timestamp value from another o_timestamp value.

An o_interval value can be added to an o_date, o_time, or o_timestamp value without changing the domain of the result. An o_interval value can be added to or subtracted from another o_interval value to produce another o_interval value.

You can create indexes and query on this type.

A bit array of options. Options are explained in the context of individual commands.

The range 00:00:00.000 to 23:59:59.999 is covered. Negative (2^31) (0x80000000) represents a null value.

You can create indexes and query on this type.

The range from 10-Jul-1677 00:00:00 and 0 nanoseconds to 21-May-2262 23:59:59 and 999999999 nanoseconds is covered (1.8 e+19 nanoseconds). Negative (2^63) (0x8000000000000000) represents a null value.

You can create indexes and query on this type.

   o_u1b     username[O_NAME_SIZE];
   o_u1b     sitename[O_PATH_SIZE];
   o_4b      dbprivilege;
   o_4b      usertype;
   o_u1b     create[O_DATETIME_SIZE];

}  o_userdesc;

Data structure for a description of a database user.

Elements:

username[O_NAME_SIZE]

O_USR_READ

O_USR_IS_REGULAR

A version type.

Options are:

VSN_TRANSIENT_VERSION

Name of a database optionally including a site name prefixed with the @ sign.

Capture the class definition of a persistent class or template class.

You must write an O_CAPTURE_SCHEMA() directive for each class that will be stored in a database.

Declaring an attribute or class to be transient means that it will be transient:

•    in instances of the class
•    in instances of derived classes
•    in attributes of other classes when this class is used as an attribute type

In effect, this makes the class or attribute invisible to databases.

See the sections "Transient Attributes" and "Create and Load Schema Files" in the "Basic Programming" chapter of the C++/VERSANT Usage Manual.

Convert a type downward, return a pointer to a derived class derivedClass when given a pointer to a base class baseClassPtr, and throw an error if not successful.

The pointer to the base class baseClassPtr is cast to the specified type derivedClass if the pointer is to an instance of a superclass of the type, is of that type, or is convertible to a pointer to an instance of a superclass or that type. Otherwise an error is thrown.

Use AS() to convert downward if you have a pointer. You can also use AS() to cast a link downwards, but L_AS() is faster if you have a link.

Upward conversion is normally automatic. However, you must explicitly cast derived links upward to base links.

To use this macro on a transient object, you must have established run time type identification with a constructor macro. See "Class Constructors" in the Chapter "Creating Classes."

See also L_AS() and as().

The following code fragment illustrates a use of the AS() macro.

...
class Circle : public PObject {
private:
    o_double xCoordinate;
    o_double yCoordinate;
    o_double radius;
public:
    Circle(o_double, o_double, o_double);
    ...
};
...
class Arc : public Circle {
private:
    o_double angle;
public:
    Arc(o_double);
    ...
};
...
main()
{
    ...
    Circle* circlePointer =
        new Persistent Arc(20.0);
    PObject*   pOPointer      = circlePointer;
    Link<PObject> pOLink   = circlePointer;
    Link<Circle>  circleLink  = circlePointer;
    Arc*  arcPointer     = AS(Arc, circlePointer);
    Link<Arc> arcLink = AS(Arc, circlePointer);
    ...
}

In the above example, Arc is derived from Circle which is derived from PObject. The code first creates an instance of Arc as circlePointer.

If you need to convert circlePointer upward to PObject*, Link<PObject>, or a Link<Circle>, then you can just use a simple assignment statement.

If you need to convert circlePointer downward to either Arc* or Link<Arc>, then you must use AS() as shown.

   const PObject&  obj,
   const PClass&   expect
   const char*     fname = NULL);

Assert that the given object obj is of the given class expect or derived from expect and raise an error if the assertion fails. You may provide the name of the function fname from which this is called, to be included in the error message.

To use this macro on a transient object, you must have established run time type identification with a constructor macro. See "Class Constructors" in the Chapter "Creating Classes."

   const PObject&  obj,
   const PClass&   expect
   const char*     fname = NULL);

Assert that the given object obj is an instance of the given class expect and raise an error if the assertion fails.

If you provide the name of the function fname from which this method is called, the name will be included in the error message.

End of string.

Convert a type downward, return a pointer to a derived class derivedClass when given a link to a base class baseClassLink, and throw an error if not successful.

The link to the base class baseClassLink is cast to the specified type derivedClass if the link is to an instance of a superclass of the type, is of that type, or is convertible to a link to an instance of a superclass or that type. Otherwise an error is thrown. Using L_AS() to convert a link is faster than using AS().

Upward conversion for pointers is normally automatic. However, you must explicitly cast derived links upward to base links.

To use this macro on a transient object, you must have established run time type identification with a constructor macro. See "Class Constructors" in the Chapter "Creating Classes."

See also AS() and as().

The following code fragment illustrates a use of the L_AS() macro.

...
...
class Circle : public PObject
{
private:
    o_double xCoordinate;
    o_double yCoordinate;
    o_double radius;
public:
    Circle(o_double, o_double, o_double);
    ...
}
...
class Arc : public Circle
{
private:
    o_double angle;
public:
    Arc(o_double);
    ...
}
...
main()
{
    ...
    Link<Circle>  circleLink =
         new Persistent Arc(20.0);
    PObject*  pOPointer    = circleLink;
    Link<PObject> pOLink   = (PObject*)circleLink;
    Circle*  circlePointer = circleLink;
    Arc*  arcPointer    = L_AS(Arc, circleLink);
    Link<Arc> arcLink   =  L_AS(Arc, circleLink);
    ...

In the above example, Arc is derived from Circle which is derived from PObject. The code first creates an instance of Arc as circleLink. If you need to convert circleLink upward to PObject* or a Circle*, then you can just use a simple assignment statement. If you need to convert circleLink downward to either Arc* or Link<Arc>, then you must use L_AS() as shown.

You can use NULL to mean a null pointer. It is compatible with (char*).

For example:

LinkVstr<type> lv;
lv.set(NULL_VSTR);

The O_NEW_PERSISTENT1() macro will create the new object in a specified database.

The O_NEW_PERSISTENT() and O_NEW_PERSISTENT2() macros will create the new object in the default database. The default database is initially the session workspace specified when you begin a session. Once a session has been started, you can change the default database with set_default_db().

These macros will allocate space for the new object in the object cache, create a cached object descriptor for the object, pin the object in the object cache, and return a pointer to the new object.

For example, to create a new instance of the class Part, assuming that the Part constructor does not require any arguments:

Part* partPtr = O_NEW_PERSISTENT(Part);

Use new normally to create transient objects:

Part* partPtr = new Part;

For template classes with two arguments, such as VVVDictionary<A,B>, you must use the O_NEW_PERSISTENT2() macro or else the comma within the brackets in the template class name will be interpreted as an argument separater.

For example:

VVVDictionary<A,B>* ptr =
   O_NEW_PERSISTENT2(VVVDictionary<A,B>)(arg);

Constructor macro for non-template classes and template classes with one argument (including bilink, bilink vstr, and collection classes.)

A class constructor macro is required if you want to establish the type of a transient instance at run time or use a link to a transient object.

For example, the following methods require type identification:

Macros:

Substitute the name of the class for the type parameter.

For example, for class A:

A::A()
{
   VPP_CLASS_CONSTRUCTOR1(A);
   ...
}

See also VPP_CLASS_CONSTRUCTOR2(), vppConstruct(), and the chapter "Creating Classes."

Constructor macro for template classes with two arguments.

A class constructor macro is required if you want to establish the type of a transient instance at run time or use a link to a transient object.

A class contructor macro must be the first statement in the constructor body.

Substitute the name of the class for the type parameter.

For example, for class A:

template < classB, classC >
A<B,C>::A()
{
   VPP_CLASS_CONSTRUCTOR2(A<B,C>);
   ...
}

See also VPP_CLASS_CONSTRUCTOR1(), vppConstruct(), and the chapter "Creating Classes."

Constructor macro for template classes with more than two arguments.

Constructor macro for template classes with two arguments.

A class constructor macro is required if you want to establish the type of a transient instance at run time or use a link to a transient object.

A class contructor macro must be the first statement in the constructor body.

Substitute the name of the class for the type parameter.

For example:

template <class X, class Y, class Z>
Object3<X,Y,Z>::Object3()
{
   PClassObject<Object3<X,Y,Z>>::Pointer() ->
   vppConstruct(this);
   .....
}

   EXTERNAL,
   INTERNAL,
   RESERVED );

Combine the external lock mode EXTERNAL and internal lock mode INTERNAL into a combined lock mode. The RESERVED parameter is reserved for future use; for this release, specify RESERVED as NULL.

For the EXTERNAL and INTERNAL parameters, you can specify any of the following:

WLOCK

In the upgradelock() and downgradelock() methods, if you do not want to change the value for just the external or internal parameter, you can specify O_LK_NO to indicate no change.

Return the external lock mode from the combined lock mode COMBINED.

Return the internal lock mode from the combined lock mode COMBINED.

Return TRUE if the combined lock is an explicit lock and otherwise return FALSE.

O_SET_EXPLICIT_LOCK( COMBINED );

Turn on the explicitness flag in the combined lock mode COMBINED.

A single or combined lock mode used to specify a short lock.

You can specify either of two kinds of short locks in the o_lockmode data type:

External

Within a session with a single process, in methods that require a lock mode of type o_lockmode, you need only supply a single parameter that describes the desired type of lock. This single parameter will, by default, specify the external lock seen by other sessions.

Options for short lock parameters are:

WLOCK

RLOCK

The default lock mode when objects are read is a read lock. To change the default, use the set_default_lock() method.

For example, to change the default to a write lock:

dom -> set_default_lock(WLOCK);

In query methods, the o_lockmode option applies to the class object only. Thus, to avoid unintentioned side effects, you should normally only specify one of the following in select(): IRLOCK, an intention read lock; IWLOCK, an intention write lock; NOLOCK, no lock. Sometimes, however, you will want to set a read or write lock on a class object when performing a query. Thus, all o_lockmode parameters can be used in query methods.

Combined lock modes

In shared sessions there may be multiple processes accessing the same object cache in shared memory. Accordingly, locks must provide concurrency among processes in the same session as well as among processes in separate sessions. To provide this concurrency, in methods that require a lock mode, you can either specify just an external parameter, such as RLOCK, or you can provide finer grain control by specifying a combined lock mode.

A combined lock mode specification consists of three parts:

External lock mode

For coding compatibility, you can also supply a combined lock mode in standard sessions, but in those cases only the external lock mode will be used.

Combined lock modes are specified using the O_COMBINE_LOCK() macro. See O_COMBINE_LOCK() for more information.

External or internal lock mode component of a combined lock mode.

Used in the O_EXTERNAL_LOCK() and O_INTERNAL_LOCK() macros.

PLock(

   o_plmode  mode,
   o_pllevel level,
   o_plqopt  qopt,
   o_u2b     intent,
   o_u2b     events );

Create an instance of PLock that describes a persistent lock.

The default is to set a read lock with a soft level that pauses until the lock is ready or the request is timed out and that does not notify you of locking events related to that object.

The PLock data type is used in acquireplock(), gcheckout(), pcheckout(), and checkin(). You cannot use a NULL pointer for a lock description in a predicate checkout pcheckout().

See also the VERSANT Database Fundamentals Manual for a complete explanation of locking options. Following is a brief description of options.

Options for mode are:

O_PL_READ

Options for level are:

O_PL_HARD

If an object is not immediately available for locking, your queuing option qopt determines what happens next. Options for qopt are:

O_PL_WAIT

The intent parameter is reserved for future use; for the present release specify 0.

Options for events are:

O_PL_LOCK_BROKEN

These options can be combined with the "or" operator |.

For example, to set persistent, soft, write locks on a group of objects partsToLock using acquireplock():

LinkVstr<Part> partsToLock = ...

PLock LockType(
   O_PL_WRITE, // Lock Mode
   O_PL_SOFT,  // Lock Level
   O_PL_WAIT,  // Queuing option
   0, // Intent option
   0 );  // Events mask

dom->acquireplock(partsToLock, LockType);

Throw an error from a catch block to the next outermost pair of try and catch blocks.

Set the function called when an unrecoverable error occurs to the function panic_function.

When VERSANT encounters an unrecoverable error, it calls a panic function to print a message and the place of the error. The default kernel panic function will then abort the application and exit with a rollback.

You might want to change the default panic function to vpp_panic(), which uses normal C++ exception handling mechanisms to throw a PError object with the description and location of the unrecoverable error.

To set the panic function to vpp_panic(), include <cxxcls/pobject.h> and call set_panic() as follows:

#include <cxxcls/pobject.h>
main()
{
   set_panic(vpp_panic);
   ...
}

The set_panic() function will return a pointer to the old panic function.

You can replace vpp_panic() with your own panic handling function which could give a customized error message, but you should not try to use any VERSANT function. A panic function should abort at the end.

For example:

#include <cxxcls/pobject.h>
void my_panic_handler(
   const char* msg,
   o_4b  line_num,
   const char* file_name);
{
   // output:
   // panic case: msg
   // panic at line line_num of file file_name
   exit(1);
}
int main()
{
   set_panic(my_panic_handler);
   ...
}

Reset the behavior of the terminate() function by specifying a pointer to an alternate function that you have defined.

Reset the behavior of the unexpected() function by specifying a pointer to an alternate function that you have defined.

The default behavior of VERSANT's built-in terminate() function is:

1.  Print the word "terminating" on stderr.

2.  If the global variable vpp_terminate_where is not NULL, then print the character string it contains.

3.  If the global variable vpp_terminate_why is not NULL, then print the character string it contains.

4.  Call o_exit(1), which terminates the application process with a rollback. This is the same as calling dom->exit(1).

See also unexpected(), set_unexpected(), and set_terminate().

The unexpected() function is automatically invoked if an error is thrown but not caught. This happens if there is no enclosing try block or if all catch blocks rethrow the error.

The default behavior of VERSANT's built-in unexpected() function is:

1.  Print "Unexpected exception:" on stderr.

2.  Print the description() of the unexpected error.

3.  Call terminate(). See also terminate().

When errors are raised, the terminate(), unexpected(), and throw() error handling functions internally call the vpp_break() subroutine. You can put a breakpoint on vpp_break() so that your debugger gains control when an error occurs.

When an unrecoverable error occurs, the function vpp_panic() uses C++ exception handling mechanisms to throw an object of type PError with a description and the place of the unrecoverable error and then calls exit(1) which exits with a rollback.

To use vpp_panic, you must include <cxxcls/pobject.h> and <cxxcls/perror.h>.

The vpp_panic() function is the recommended panic handler function for C++/VERSANT. See set_panic() for how to change the default handler

The output of vpp_panic() could be:

•    When the error number is found in the error message file, the output is something like:

The standard C preprocessor, used in C++ as well, understands the special macros __FILE__ and __LINE__, which expand into the filename and the line number of the source file in which they appear. The __HERE__ macro combines these two so that you can inform a PError object where in the source it was created.

For example:

throw(PError(WIDGET_NOT_FOUND,__HERE__));

In a thread session, replace the default error handling method vpp_terminate().

The vpp_thread_terminate() macro will do the following.

1.  Print the word "terminating" on stderr.

2.  Print the error message in the latest exception (PError::print()).

3.  Call thread exit to exit the thread.

In a thread session, replace the default error handling method vpp_unexpected().

The vpp_thread_unexpected() macro will do the following.

1.  Print the words "Unexpected exception" on stderr.

2.  call vpp_thread_terminate().

Included for ODMG compatibility.

A VERSANT error code number.

   o_err     e_errno;
   o_u4b     e_oserr;

} o_error;

An error.

Elements:

e_errno

   const char*   error_desc,
   o_4b          line_number,
   const char*   file_name );

A pointer to a function to be used as a panic handler, where error_desc is a character string that describes the error, line_number is the line number where the error occurred, and file_name is the name of the file in which the error occurred.

See also vpp_panic() and set_panic().

As defined in C++, this is the type of a pointer to a function that takes no argument. It is used as the data type of the argument for and returned value of set_terminate() and set_unexpected().

•    Before calling terminate(), VERSANT will set vpp_terminate_why to one of the following:

Print error when terminate() is invoked.

If the global variable vpp_terminate_why is a character string rather than NULL, the contents will be printed whenever the VERSANT default terminate() method is invoked. See also terminate().

For a standard installation, error messages are stored in the files:

VERSANT_RELEASE_DIRECTORY/lib/error.msg

VERSANT_RELEASE_DIRECTORY/lib/error.txt

You can define your own error by allocating an error number greater than 50,000, using the constructor to create your own error, adding you error message to the error.msg file, and using methods defined on PError.

Including <cxxcls/pobject.h> provides access to all error handling methods.

Destructor.

Supply a value for %d, %s, or %f when used in an error description string.

For example, you might create an error 15001, named APP_NOTHING_FOUND. The error description string in error.msg might be:

15001, No objects of class %s were found

In the case of the above line, you could then use the << operator to supply a value for %s in the error description string.

For example:

PError e(APP_NOTHING_FOUND);
throw (e << "Employee");

Example

This example has been simplified so that PError handles only a few, specific error numbers. Although this example does not show it, try blocks can be nested.

#include <libc.h>
#include "employee.h"
#include "departme.h"
main
{
   const lineSize = 1024;
   char predicate[lineSize];
   char value[lineSize];
   char response[lineSize];
   #define APP_NOTHING_FOUND 50001;
   dom = new PDOM;
   dom-> beginsession("myDatabase");
   do
   {
      try
      {
         cout << "Enter predicate: ";
         cin.getline(predicate,linesize)
         cout << "Enter value: ";
         cin.getline(value, linesize)
         LinkVstr<Employee> staff =
            PClassObj<Employee>.select(
               "myDatabase,"
               TRUE,
               IRLOCK,
               predicate,
               value);

         if (staff.empty())
         {
            PError e(APP_NOTHING_FOUND);
            throw (e << "Employee");
         }

         Employee* worker = staff[0];

         staff.release();

         cout  << "Found: "
               << (char*)(worker->getName())
               << endl;
      }
      catch (PError& err)
      {
         switch (err.errnum)
         {
            case CXX_NO_SUCH_ATTR:
            case CXX_BAD_PRED:
            case APP_NOTHING_FOUND:
               err.print();
               break;
            default: rethrow;
         }
      }
      cout  << "Continue ? ";
   }
   while (
      cin.getline(response,lineSize) &&
         (response[0] == 'y' || response[0] == 'Y');
      cout  << "Commit the short transaction and exit..."
            << endl;
      dom -> exit(0);
}

For a standard installation, error messages are stored in the file:

/usr/local/osc/lib/error.msg

The line for error 50001, named APP_NOTHING_FOUND in the C++ source code, might be:

50001, No objects of class %s were found

In the case of the above line, the string "Employee" was supplied by the throw for substitution for the %s in the error description string.

Create a new error stack which is initially empty. The error stack can later be used to hold application errors.

See also: deleteerror(), deleteerrortext(), formaterrortext(), getcurrenterror(), pusherrorstack(), seterrorparam().

   char*     buf,
   o_u4b     bufsize );

Write an error description for this object into the given buffer. The maximum size of the buffer must be provided. The values supplied by the throw with operator << are substituted into the % codes in the error description string.

Delete memory used by an o_error structure when the o_error structure is no longer required.

See also: createerror(), deleteerrortext(), formaterrortext(), getcurrenterror(), pusherrorstack(), seterrorparam().

Delete the memory associated with the error text allocated by the formaterrortext() function.

See also: createerror(), deleteerror(), formaterrortext(), getcurrenterror(), pusherrorstack(), seterrorparam().

Return the error number in this instance of PError.

Return the file name where an error was thrown, if you have used the PError(n,file,line) constructor; otherwise, return NULL.

Included for ODMG compatibility.

Return the line number in the file where an error was thrown, if you have used the PError(n,file,link) constructor; otherwise, return NULL.

Get a description of the error generated by the last VERSANT Manager function call and return it to the new instance of o_error specified as errStack.

See also: createerror(), deleteerror(), deleteerrortext(), formaterrortext(), pusherrorstack(), seterrorparam().

   FILE*     f = stderr,
   o_bool    usePrefix = TRUE );

Call the description() method and print the result followed by a new line to the specified file. The default file is the standard error file.

See also: createerror(), deleteerror(), deleteerrortext(), formaterrortext(), getcurrenterror(), seterrorparam().

If the parameter is already set, this function will overwrite the old value. If the parameter does not exist, the function will append the parameter to the list.

You can use the sourcefile and sourceline parameters to specify the source file and line number where an error occured.

See also: createerror(), deleteerror(), deleteerrortext(), formaterrortext(), getcurrenterror(), pusherrorstack().

Included for ODMG compatibility.

The constructor takes no arguments and initializes the internal state to O_OK.

Assign the state of this instance of PResult to O_OK. Methods that take PResult& as an argument should either use set() or clear() on the PResult& before returning.

Return the state of this instance of PResult which will be an error code if an error has occurred or O_OK if there has been no error.

Return TRUE if the internal state of this instance of PResult is not O_OK and otherwise return FALSE.

Return TRUE if the internal state of this instance of PResult is O_OK and otherwise return FALSE.

Assign the state of this instance of PResult to a specified error code e or, by default, to the value of the global variable o_errno. Methods that take PResult& as an argument should either use set() or clear() on the PResult& before returning.

If you want to perform value comparisons, you must derive the elements from PVirtual and define for them a comparison method compare() and a hashing method hash().

Class PVirtual inherits from PObject, so you do not have to include PObject in your list of base classes if you derive your class from PVirtual. However, if you do not include pobject.h, you must include <cxxcls/vcommon.h>.

The PVirtual class defines two virtual methods: hash() and compare(). These methods must be redefined by derived classes, because there is no way to know what attributes you want to use to make the comparison or how to compare the attributes.

See also the usage notes in the "Collection Classes" chapter of the C++/VERSANT Usage Manual.

Set this instance of PVirtual equal to specified object.

Compare this object with another object specified as other_obj.

The compare() method should be redefined by a derived class so that a negative number is returned if this object is "less than" the other object, zero if this object is "equal to" the other object, and a positive number if this object is "greater than" the other object.

For example, to compare coordinates by considering first the x and then the y coordinates:

class Coord : PVirtual
{  public:
   ...
   o_4b compare( const PVirtual* c ) const
   {  if ( x == c.h && y == c.y ) return 0;
      if ( y == c.y ) return x - c.x;
      return y - c.y;
   }
}

Following are comparison operators on PVirtual.

!=

Map an object to an unsigned integer.

The hash() method should be redefined by a derived class so that if two objects are equal, their hash value is the same.

Fix this C++ object when first brought into memory.

To initialize an object with transient data when it is brought into memory, derive its class from PVirtual and then redefine the init() method. The init() method will be called after the C++ activation.

By default, init() is not called when objects are brought into memory. To cause it to be called, use set_call_user_init_flag() in PCustomizeFundamental.

See set_call_user_init_flag() in PCustomizeFundamental for usage notes.

Activation and deactivation functionality are provided by the virtual methods d_activate() and d_deactivate().

Classes that derive from PVirtual are checked to see if they provide an implementation of d_activate() and d_deactivate(). If a class or any of its base classes derived from PVirtual do not override the default implementation of d_activate() and d_deactivate(), nothing happens when an object is activated or deactivated.

If a class or any of its base classes derived from PVirtual does implement d_activate(), then it will be called when an instance enters the object cache. If there is an implementation of d_deactivate(), it will be called when an instance leaves the object cache.

If implemented on a class directly or indirectly deriving from PVirtual, activate an instance of the class when it enters the application object cache.

If implemented on a class directly or indirectly deriving from PVirtual, deactivate an instance of the class when it leaves the application object cache.

Mark this object as dirty.

The ODMG d_Object class is aliased to PVirtual.

To declare and use VElemental, just include the file for the collection class involved. This will also include vcommon.h and velement.h.

The hashing and comparison methods in VElemental are defined on many types:

•    Elemental types, including o_1b, o_u1b, o_2b, o_u2b, o_4b, o_u4b, o_float, o_double.

•    Links, pointers, and references to objects of class PObject and PVirtual.

•    Vstrs of elemental types.

•    Link vstrs of PObject or PVirtual.

The class VElemental defines a number of methods on elemental types. This class contains no data, so all of the methods are static.

The overloaded VElemental::compare() method compares two instances of a given type.

In the case of a numeric type, the comparison method is a simple inline function. The value returned is -1, 0, or 1 depending upon whether the first instance is considered, respectively, to be less than, equal to, or greater than the second instance.

The overloaded VElemental::hash() method performs hashing on an instance of a given type.

The functions defined by these methods are designed to provide good mixing properties and also to be fairly efficient.

Combine two or more hash values together into a new hash value.

For your convenience, up to eight hash value arguments may be supplied.