The mapping in the C++ programming language of an SQL REF value, which is a reference to an SQL structured type value in the database.
Each REF value has a unique identifier of the object it refers to. An SQL REF value may be used in place of the SQL structured type it references; it may be used as either a column value in a table or an attribute value in a structured type.
Because an SQL REF value is a logical pointer to an SQL structured type, a Ref object is by default also a logical pointer; thus, retrieving an SQL REF value as a Ref object does not materialize the attributes of the structured type on the client.
The only methods valid on a NULL
Ref
object are isNull(), and operator=().
A Ref object can be saved to persistent storage and is de-referenced through operator*(), operator->() or ptr() methods. T must be a class derived from PObject
. In the following sections, T*
and PObject
* are used interchangeably.
Table 12-34 Enumerated Values Used by Ref Class
Attribute | Options |
---|---|
LockOptions |
|
PrefetchOption |
|
Table 12-35 Summary of Ref Methods
Method | Summary |
---|---|
|
|
Clears the reference. |
|
Returns the connection this ref was created from. |
|
Checks if the Ref is cleared. |
|
Checks if the |
|
Marks the referred object as deleted. |
|
Dereferences the |
|
Dereferences the |
|
Checks if the |
|
Checks if the |
|
Assignment operator. |
|
Dereferences the |
|
Specifies type and depth of the object attributes to be followed for prefetching. |
|
Sets the lock option for the object referred from this. |
|
Sets the Ref to |
|
Sets the prefetch options. |
|
Unmarks for delete the object referred by this. |
Ref
object constructor.
Syntax | Description |
---|---|
Ref(); |
Creates a NULL Ref. |
Ref( const Ref<T> &src); |
Creates a copy of Ref. |
Parameter | Description |
---|---|
src |
The Ref that is being copied. |
This method clears the Ref
object.
void clear();
Returns the connection from which the Ref
object was instantiated.
const Connection *getConnection() const;
This method checks if Ref
object is cleared.
bool isClear() const;
This method tests whether the Ref
object is NULL
. If the Ref
object is NULL
, then TRUE
is returned; otherwise, FALSE
is returned.
bool isNull() const;
This method marks the referenced object as deleted.
void markDelete();
This method dereferences the Ref
object and pins, or fetches the referenced object if necessary. This might result in prefetching a graph of objects if prefetch attributes of the referenced object are set.
Syntax | Description |
---|---|
T *operator->(); |
Dereferenes and pins or fetches a non-const Ref object. |
const T *operator->() const; |
Dereferences and pins or fetches a const Ref object. |
This method dereferences the Ref
object and pins or fetches the referenced object if necessary. This might result in prefetching a graph of objects if prefetch attributes of the referenced object are set. The object does not need to be deleted. Destructor would be automatically called when it goes out of scope.
Syntax | Description |
---|---|
T& operator*(); |
Dereferenes and pins or fetches a non-const Ref object. |
const T& operator*() const; |
Dereferences and pins or fetches a const Ref object. |
This method tests whether two Ref
objects are referencing the same object. If the Ref
objects are referencing the same object, then TRUE
is returned; otherwise, FALSE
is returned.
bool operator == ( const Ref<T> &ref) const;
Parameter | Description |
---|---|
ref |
The Ref object of the object to be compared. |
This method tests whether two Ref
objects are referencing the same object. If the Ref
objects are not referencing the same object, then TRUE
is returned; otherwise, FALSE
is returned.
bool operator!= ( const Ref<T> &ref) const;
Parameter | Description |
---|---|
ref |
The Ref object of the object to be compared. |
Assigns the Ref
or the object to a Ref
. For the first case, the Ref
s are assigned and for the second case, the Ref
is constructed from the object and then assigned.
Syntax | Description |
---|---|
Ref<T>& operator=( const Ref<T> &src); |
Assigns a Ref to a Ref . |
Ref<T>& operator=( const T *)obj; |
Assigns a Ref to an object. |
Parameter | Description |
---|---|
src |
The source Ref object to be assigned. |
obj |
The source object pointer whose Ref object is to be assigned. |
Returns a pointer to a PObject
. This operator dereferences the Ref
and pins or fetches the object if necessary. This might result in prefetching a graph of objects if prefetch attributes of the Ref
are set.
Syntax | Description |
---|---|
T *ptr(); |
Returns a pointer of a non-const Ref object. |
const T *ptr() const; |
Returns a pointer of a const Ref object. |
This method specifies how the object should be locked when dereferenced.
void setLock(lockOptions);
Argument | Description |
---|---|
lockOptions |
The lock options as defined by LockOptions in Table 12-34 . |
This method sets the Ref
object to NULL
.
void setNull();
Sets the prefetching options for complex object retrieval. This method specifies depth up to which all objects reachable from this object through Ref
s (transitive closure) should be prefetched. If only selected attribute types are to be prefetched, then the first version of the method should be used. This method specifies which Ref attributes of the object it refers to should be followed for prefetching of the objects (complex object retrieval) and how many levels deep those links should be followed.
Syntax | Description |
---|---|
void setPrefetch( const string &typeName, unsigned int depth); |
Sets the prefetching options for complex object retrieval, using type name and depth. |
void setPrefetch( unsigned int depth); |
Sets the prefetching options for complex object retrieval, using depth only. |
void setPrefetch( const string &schName, const string &typeName, unsigned int depth); |
Sets the prefetching options for complex object retrieval, using scheman, type name, and depth. |
void setPrefetch( const UString &schName, const UString &typeName, unsigned int depth); |
Sets the prefetching options for complex object retrieval, using scheman, type name, and depth, and UString support. |
Parameter | Description |
---|---|
typeName |
Type of the Ref attribute to be prefetched. |
schName |
Schema name of the Ref attribute to be prefetched. |
depth |
Depth level to which the links should be followed; can use PrefetchOption as defined in Table 12-34 . |
This method unmarks the referred object as dirty and available for deletion.
void unmarkDelete();