This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRISOpens in a new window, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions pageOpens in a new window (login required).

%Library.RelationshipObject

serial class %Library.RelationshipObject extends %Library.SerialObject, %Collection.AbstractIterator

Registered relationship class for relationship cardinalities many and children. Instances of this class are used by n-cardinality relationships to manage objects currently related to the container object and also to manage the objects whose relationship with the container object has been removed. Related objects are loaded into this object using a query-like interface that is implemented by the inverse relationship. The order in which related objects are loaded is neither guaranteed or maintained as objects are related or unrelated. This class is used internally by Caché. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this class.

Property Inventory (Including Private)

Method Inventory (Including Private)

Parameters

parameter CARDINALITY;
parameter CLASSNAMEINOID = 0;
This parameter determines how the collection object stores OID values. If this parameter is set to 0, then partially-formed OID values (containing only an ID number) are used. If this parameter is set to 1, then fully-formed OID values (containing both a class name and an ID number) are used.
parameter ELEMENTTYPE = %ObjectHandle;
The type (class name) of the elements stored in the collection.
parameter INVERSEPERSISTENT = 0;
parameter INVERSEPROPERTY;
parameter PERSISTENT = 0;

Properties (Including Private)

property Cardinality as %CacheString [ InitialExpression = ..#CARDINALITY ];
The property name of the inverse relationship in the related class.
Property methods: CardinalityGet(), CardinalityIsValid(), CardinalitySet()
property Disconnected as %CacheString [ Private , MultiDimensional ];
Private storage area used to hold OREF values for objects no longer related to the container object.
Property methods: DisconnectedGet(), DisconnectedIsValid(), DisconnectedSet()
property ElementType as %CacheString [ InitialExpression = ..#ELEMENTTYPE ];
The type (class name) of the elements stored in the collection.
Property methods: ElementTypeGet(), ElementTypeIsValid(), ElementTypeSet()
property InversePersistent as %CacheString [ InitialExpression = ..#PERSISTENT ];
TRUE if the ElementType class is a persistent class.
Property methods: InversePersistentGet(), InversePersistentIsValid(), InversePersistentSet()
property InverseProperty as %CacheString [ InitialExpression = ..#INVERSEPROPERTY ];
The property name of the inverse relationship in the related class.
Property methods: InversePropertyGet(), InversePropertyIsValid(), InversePropertySet()
property InverseReference as %CacheString;
Property methods: InverseReferenceGet(), InverseReferenceIsValid(), InverseReferenceSet()
property NotLoaded as %Boolean [ InitialExpression = 1 , Transient ];
TRUE if related objects have not been retrieved by calling Load().
Property methods: NotLoadedDisplayToLogical(), NotLoadedGet(), NotLoadedIsValid(), NotLoadedLogicalToDisplay(), NotLoadedNormalize(), NotLoadedSet()
property Oref as %CacheString [ Private , MultiDimensional ];
Oref is a private property used to hold the related object references in the form i%Oref(key)=oref.
Property methods: OrefGet(), OrefIsValid(), OrefSet()
property Persistent as %CacheString [ InitialExpression = ..#PERSISTENT ];
TRUE if the container class is a persistent class.
Property methods: PersistentGet(), PersistentIsValid(), PersistentSet()
property RelationshipData [ Private , MultiDimensional ];
Private property used to hold some relationship data
Property methods: RelationshipDataDisplayToLogical(), RelationshipDataGet(), RelationshipDataIsValid(), RelationshipDataLogicalToDisplay(), RelationshipDataLogicalToOdbc(), RelationshipDataNormalize(), RelationshipDataSet()

Methods (Including Private)

method %AddToSaveSet(force As %Integer = 0, refresh As %Integer = 0) as %Status
Overrides %SerialObject implementation. Scans objects for modifications in the related list (Element) and the terminated relationship list (DeleteOref). Modified/Scheduled to delete objects are added to the save graph.
private method %GetSerial(force As %Integer = 0) as %String
private method %OnClose() as %Status
Inherited description: This callback method is invoked by the %Close() method to provide notification that the current object is being closed.

The return value of this method is ignored.

private method %OnConstructClone(oref As %RegisteredObject, deep As %Boolean = 0, ByRef cloned As %String) as %Status
Inherited description: This callback method is invoked by the %ConstructClone() method to provide notification that a clone of an object is being created. It passes in the oref of the object that was cloned in object.

If this method returns an error then the object will not be created.

private method %OnNew(initvalue As %String = "") as %Status
%New callback - initializes ElementType, Cardinality, InverseProperty and InverseReference from initvalue parameter.
method %RollBack() as %Status
This method is called by %TRollBack^%occTransaction() when a transaction is rolled back.

Returns a %Status value indicating success or failure.

method %SerializeObject(ByRef serial As %Binary, partial As %Integer = 0) as %Status
This method retrieves all of the serial values for referenced objects and places them into the instance variables and then validates, normalizes, and serializes the object (with a save of the persistent image if persistent).
private method %SetSerial(initvalue As %String) as %Status
method %UnSwizzleAt(key As %String, force As %Integer = 0) as %Status
Unswizzles (removes from memory) the individual element at position key in the list.

Returns a %Status value indicating success or failure.

method Clear() as %Status
Clears the contents of the array. Both the OID and OREF values are cleared.

Returns a %Status value indicating success or failure.

method Count() as %Integer
Returns the number of elements contained in the Relationship.
private method FindExistingObjectId(id As %String, key As %String = "") as %String
Like FindObjectId but is private, and will not trigger a Load()
private method FindExistingOref(oref As %ObjectHandle) as %String
Like FindOref but doesn't support key starting point, is private, and will not trigger a Load()
final method FindObject(oid As %ObjectIdentity, key As %String) as %String
Starting from, but not including, position key, FindObject finds the next element in the list whose ID value equals the id from oid ($$$oidPrimary is the id). If key is a null string, FindObject starts at the beginning of the list.

FindObject returns the position of the found element or null string ("") if no element was found.

method FindObjectId(id As %String, key As %String = "") as %String
Starting from, but not including, position key, FindObjectId finds the next element in the list whose ID value equals id. If key is a null string, FindObjectId starts at the beginning of the list.

FindObjectId returns the position of the found element or null string ("") if no element was found.

method FindOref(oref As %ObjectHandle, key As %String = "", id As %String) as %String
Starting from, but not including, location key, finds the next element in the array whose Oref value equals oref.

If key is a null string (""), the search starts at the beginning of the array.

FindOref returns the key associated with the found element or null string ("") if no element is found. Unswizzled references are compared to oref.%Oid() and if equal, swizzling will occur.

method GetAt(key As %String) as %ObjectHandle
Finds and returns the OREF value referring to the object at position key in the list.

GetAt returns the value of the element at location key or null string ("") if no element is found.

method GetExistingObjectAt(key As %String, force As %Integer = 0) as %ObjectIdentity
Finds and returns the OID value referring to the object at position key in the list.

Returns the value of the element at location key or the null OID if no element is found.

method GetExistingObjectNext(ByRef key As %String) as %ObjectIdentity
Finds and returns the OID value referring to the object at the position after key in the list. If key is a null string (""), it returns the OID value of the first element in the list.

The value of key, which is passed by reference, is updated to the position value of the returned element or the null OID if key is at the end of the list.

method GetNext(ByRef key As %String) as %ObjectHandle
Finds and returns the OREF value referring to the object at the position after key in the list. If key is a null string (""), it returns the OREF value of the first element in the list.

The value of key, which is passed by reference, is updated to the position value of the returned element or null string ("") if key is at the end of the list.

method GetObjectAt(key As %String = "", force As %Integer = 0) as %ObjectIdentity
Finds and returns the OID value referring to the object at position key in the list.

Returns the value of the element at location key or the null OID if no element is found.

method GetObjectIdAt(key As %String = "", force As %Integer = 0) as %String
Finds and returns the ID value of the element associated with key.

GetObjectIdAt returns the ID value of the element associated with key or null string ("") if no element is found.

method GetObjectIdNext(ByRef key As %String) as %String
Finds and returns the ID value of the element at the location after key in the array. If key is a null string (""), it returns the ID value of the first element in the array.

The value of key, which is passed by reference, is updated to the key value of the returned element or null string ("") if key is at the end of the array.

method GetObjectIdPrevious(ByRef key As %String) as %String
Finds and returns the ID value of the element at the location before key in the array. If key is a null string (""), it returns the ID value of the last element in the array.

The value of key, which is passed by reference, is updated to the key value of the returned element or null string ("") if key is at the beginning of the array.

method GetObjectNext(ByRef key As %String = "") as %ObjectIdentity
Finds and returns the OID value referring to the object at the position after key in the list. If key is a null string (""), it returns the OID value of the first element in the list.

The value of key, which is passed by reference, is updated to the position value of the returned element or the null OID if key is at the end of the list.

method GetObjectPrevious(ByRef key As %String) as %ObjectIdentity
Finds and returns the OID value referring to the object at the position before key in the list. If key is a null string (""), it returns the OID value of the last element in the list.

The value of key, which is passed by reference, is updated to the position value of the returned element or the null OID if key is at the beginning of the list.

final method GetOrefAt(key As %String, force As %Integer = 0) as %ObjectHandle
This method is used internally by Caché. You should not make direct use of it within your applications. There is no guarantee made about either the behavior or future operation of this method.

Finds and returns the OREF at position key in the list without automatically swizzling the object. Returns $$$NULLOREF if no element is found or if the referenced object hasn't been swizzled.

method GetPrevious(ByRef key As %String) as %ObjectHandle
Finds and returns the OREF value referring to the object at the position before key in the list. If key is a null string (""), it returns the OREF value of the last element in the list.

The value of key, which is passed by reference, is updated to the position value of the returned element or the null OREF if key is at the beginning of the list.

method Insert(oref As %ObjectHandle) as %Status
Inserts an element with OREF value oref at the end of the array.

Returns a %Status value indicating success or failure.

method InsertObject(oid As %ObjectIdentity) as %Status
Inserts an element with OID value oid at the end of the array.

Returns a %Status value indicating success or failure.

final method InsertObjectId(id As %String) as %Status
Inserts an element with ID value id at the end of the array.

Returns a %Status value indicating success or failure.

final method IsDefined(key As %String) as %Boolean
Returns true (1) if a value is defined at location key, otherwise false (0).
method IsEmpty() as %Boolean
Returns true if this collection is empty. To get better performance, if the contents of the collection are not already loaded, then this will run a minimal query to determine if the collection is empty, and will not actually load the contents.
method Load() as %Status
Retrieves a list of all objects related to InverseReference and inserts them into array of related objects.
Finds and returns the key value of the element at the location following key in the array. If key is a null string (""), then Next returns the key value for the first element in the array.
Finds and returns the key value of the element at the location preceding key in the array. If key is a null string (""), then Previous returns the key value for the last element in the array.
method Relate(oref As %ObjectHandle) as %Status
Inserts an element with OREF value oref at the end of the list.

Returns a %Status value indicating success or failure. This method should not be invoked directly. It is invoked by the inverse relationship.

method Remove(oref As %ObjectHandle) as %ObjectIdentity
Removes the element whose oref is oref.

Remove returns the OID value of the removed element or the null OID if no element was removed.

method RemoveAt(key As %String) as %ObjectIdentity
Removes the element at position key in the array.

RemoveAt returns the OID value of the removed element or the null OID if no element was removed.

method RemoveObject(oid As %ObjectIdentity) as %ObjectIdentity
Removes the element whose OID is oid.

RemoveAt returns the OID value of the removed element or then null OID if no element was removed.

method UnRelate(oref As %ObjectHandle) as %Status
Moves an element with OREF value oref from the array of related objects to the list of terminated relationships.

Returns a %Status value indicating success or failure. This method should not be invoked directly. It is invoked by the inverse relationship.

Inherited Members

Inherited Methods (Including Private)

FeedbackOpens in a new window