Skip Headers

Oracle® C++ Call Interface Programmer's Guide
10g Release 1 (10.1)

Part Number B10778-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

PObject Class

OCCI provides object navigational calls that enable applications to perform any of the following on objects:

This class enables the type definer to specify when a class is capable of having persistent or transient instances. Instances of classes derived from PObject are either persistent or transient. A class (called "A") that is persistent-capable inherits from the PObject class:

class A : PObject { ... } 

The only methods valid on a NULL PObject are setName(), isNull(), and operator=().

Some of the methods provided, such as lock(), apply only for persistent instances, not for transient instances.

Table 10-29 Summary of PObject Methods

Method Summary
PObject()
PObject class constructor.
flush()
Flushes a modified persistent object to the database server.
getConnection()
Return the connection from which the PObject object was instantiated.
getRef()
Return a reference to a given persistent object.
isLocked()
Test whether the persistent object is locked.
isNull()
Test whether the object is NULL.
lock()
Lock a persistent object on the database server. The default mode is to wait for the lock if not available.
markDelete()
Mark a persistent object as deleted.
markModified()
Mark a persistent object as modified or dirty.
operator=()
Assign one PObject to another.
operator delete()
Remove the persistent object from the application cache only.
operator new()
Creates a new persistent / transient instance.
pin()
Pins an object.
setName()
Sets the object value to NULL.
unmark()
Unmarks an object as dirty.
unpin()
Unpins an object. In the default mode, the pin count of the object is decremented by one.


PObject()

PObject class constructor.

Syntax Description
PObject();
Creates a NULL PObject.
PObject(
   const PObject &obj);
Creates a copy of PObject.

Parameter Description
obj
The source object.


flush()

This method flushes a modified persistent object to the database server.


Syntax
void flush();


getConnection()

Returns the connection from which the persistent object was instantiated.


Syntax
const Connection *getConnection() const;


getRef()

This method returns a reference to the persistent object.


Syntax
RefAny getRef() const;


isLocked()

This method test whether the persistent object is locked. If the persistent object is locked, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool isLocked() const;


isNull()

This method tests whether the persistent object is NULL. If the persistent object is NULL, then TRUE is returned; otherwise, FALSE is returned.


Syntax
bool isNull() const;


lock()

Locks a persistent object on the database server.


Syntax
void lock(
   PObject::LockOption lock_option);
Parameter Description
lock_option
Locking options:
  • OCCI_LOCK_WAIT instructs the cache to pin the object only after acquiring a lock; if the object is locked by another user, the pin call with this option will wait until it can acquire the lock before returning to the caller; equivalent to SELECT FOR UPDATE

  • OCCI_LOCK_NOWAIT instructs the cache to pin the object only after acquiring a lock; will not wait if the object is currently locked by another user; equivalent to SELECT FOR UPDATE WITH NOWAIT



markDelete()

This method marks a persistent object as deleted.


Syntax
void markDelete();


markModified()

This method marks a persistent object as modified or dirty.


Syntax
void mark_Modified();


operator=()

This method assigns the value of a persistent object this PObject object. The nature (transient or persistent) of the object is maintained. NULL information is copied from the source instance.


Syntax
PObject& operator=(
   const PObject& obj);
Parameter Description
obj
The object from which the assigned value is obtained.


operator delete()

Deletes a persistent or transient object. The delete operator on a persistent object removes the object from the application cache only. To delete the object from the database server, invoke the markDelete() method.


Syntax
void operator delete(
   void *obj,
   size_t size);
Parameter Description
obj
The pointer to object to be deleted
size
(Optional) Size is implicityly obtained from the object


operator new()

This method is used to create a new object. A persistent object is created if the connection and table name are provided. Otherwise, a transient object is created.

Syntax Description
void *operator new(
   size_t size);
Creates a defualt new object, with a size specification only
void *operator new(
   size_t size,
   const Connection *conn,
   const string& tableName,
   const char *typeName);
Used for creating transient objects when client side characterset is multibyte.
void *operator new(
   size_t size,
   const Connection *conn,
   const string& tableName,
   const string& typeName,
   const string& schTableName="",
   const string& schTypeName="");
Used for creating persistent objects when client side characterset is multibyte.
void *operator new(
   size_t size,
   const Connection *conn,
   const UString& tableName,
   const UString& typeName,
   const UString& schTableName="",
   const UString& schTypeName="");
Used for creating persistent objects when client side characterset is unicode (UTF16).

Parameter Description
size
size of the object
conn
The connection to the database in which the persistent object is to be created.
tableName
The name of the table in the database server.
typeName
The SQL type name corresponding to this C++ class. The format is <schemaname>.<typename>.
schTableName
The schema table name.
schTypeName
The schema type name.


pin()

This method pins the object and increments the pin count by one. As long as the object is pinned, it will not be freed by the cache even if there are no references to this object instance.


Syntax
void pin();


setNull()

This method sets the object value to NULL.


Syntax
void setNull();


unmark()

This method unmarks a persistent object as modified or deleted.


Syntax
void unmark();


unpin()

This method unpins a persistent object. In the default mode, the pin count of the object is decremented by one. When this method is invoked with OCCI_PINCOUNT_RESET, the pin count of the object is reset. If the pin count is reset, this method invalidates all the references (Ref) pointing to this object. The cache sets the object eligible to be freed, if necessary, reclaiming memory.


Syntax
void unpin(
   UnpinOption mode=OCCI_PINCOUNT_DECR);
Parameter Description
mode
Specifies whether the pin count should be decremented or reset to 0. Valid values are:
  • OCCI_PINCOUNT_RESET

  • OCCI_PINCOUNT_DECR