REFERENCES OF Statement

[This is preliminary documentation and subject to change.]

The REFERENCES OF statement supports the traversal of associations programmatically by retrieving all association instances that refer to a particular source instances.

The syntax of the REFERENCES OF statement is:

references of {SourceObject} where 
    ClassDefsOnly
    RequiredQualifier = QualifierName
    ResultClass = ClassName
    Role = PropertyName
 

To specify a source object, use any valid object path. As with the SELECT statement, the WHERE clause is optional and is used to further define the query. That is, the following statement is perfectly valid:

references of {Adapter="AHA-294X"}

REFERENCES OF statements that include a WHERE clause use one or more of the predefined keywords: ClassDefsOnly, RequiredQualifier, ResultClass, or Role.

The ClassDefsOnly keyword indicates that a list of association class names is returned rather than actual association instances. The class names returned are the class names of all association instances that reference the source object. For example, the following statement returns AdapterDriver and AdapterProtocol class names:

references of {Adapter="AHA-294X"} where ClassDefsOnly

The RequiredQualifier keyword indicates that the returned association objects must include the specified qualifier. The RequiredQualifier keyword can be used to include particular instances of associations in the result set. For example, the following statement returns association instances that include a qualifier called AdapterTag:

references of {Adapter="AHA-294X"} 
    where RequiredQualifier = AdapterTag
 

The ResultClass keyword indicates that the returned association objects must belong to or derive from the specified class. For example, the following statement returns asssociations of the AdapterDriver class or subclasses of AdapterDriver:

references of {Adapter="AHA-294X"} 
    where ResultClass = AdapterDriver
 

The Role keyword indicates that the returned associations are only those in which the source object plays a particular role. The role is defined by the specified property, a reference property of type ref. This is the property in the association that holds the reference to the source object. The Role keyword is useful in associations where a certain object can play one role in some cases and another role in others, such as in hierarchical associations. The Role keyword can be used to retrieve all of the associations in which the source object plays the role of parent, for example. The following statement illustrates the syntax for retrieving associations that include a reference to the source object as the parent:

references of {Adapter="AHA-294X"} 
    where Role = parent