GetDestCollectionKeys - Teradata Meta Data Services

GetDestCollectionKeys

Purpose

The CMetaObject class GetDestCollectionKeys function returns a list of CMetaObjectKeys that contains the object ID and name. The keys identify the collection of the destination class objects associated with this CMetaObject for the specified relationship.

Description

The GetDestCollectionKeys function is expected to be used by an application to enable it to display the name or ID of objects in a collection without having to read the entire collection of objects into memory. This is important for large collections which consume a large amount of process space if all objects are read into memory.

GetDestCollectionKeys only returns the keys of the current versions of objects referenced by the current version of this CMetaObject.

The relationship ID is specified by the GUID relationship ID or the internal relationship ID (one must be set).

If the destination class of the relationship is a superclass, this function will only return objects in the destination class. To return objects in the subclasses, use the GetDestinationCollectionKeys3 function.

The third variant of GetDestCollectionKeys listed returns a list of CMetaRelationshipKey objects (contains object id, object name, class id, class name, and optional explanation text) which identify the collection of the destination class objects associated with this CMetaObject for the specified relationship. This API functions in all respects the same as GetDestCollectionKeys3 except for the type of the return objects.

Requirements

The internal object id must be set in the object and it must be for a version of the object. The ObjectID must be the ID of an object in the origin class of the specified relationship.

The relationship id is specified by the GUID relationship id or internal relationship id (one of which must be set). CMetaObject must be an object in the origin class of the relationship.

The propFilter list can contain zero or more CMetaFilterInfo objects.

The PropertyID (SetPropertyID()) or PropertyName (SetName()) of the value attribute in each CMetaFilterInfo object must contain a valid Relative Property Id or name of a property description in the class.

The value attribute in each CMetaFilterInfo object must also be set to the value on which the search will be made. This value must be of the same type as the property description. For example, if the search is to be made on Relative Property ID = 1 and Relative Property ID 1 is defined as an integer, Value must be set to an integer (SetInt()). If relative Property ID 1 is a string, Value must be set to a string (SetString()).

The default ComparisonOperator in each CMetaFilterInfo object is EQUAL and the default LogicalOperator is META_AND.

If the propFilter list contains zero objects, the function will perform a search by strObjName only. If strObjName is also NULL, the API will return all the objects in the collection.

If the propFilter list contains objects and strObjName is set, the logical operator between the properties and the name will the “AND”. To perform a search of a name “OR” a property, set strObjName to NULL and add a CMetaFilterInfo object to the propFilter list for a name search.

Syntax

HRESULT GetDestCollectionKeys(

vector<CMetaObjectKey> &objectKeyList, 

const GUID &gRelID, 

const OBJECTID_t lRelID = NULLLOID);

HRESULT GetDestCollectionKeys(

vector<CMetaObjectKey> &objectKeyList, 

const GUID &gRelID, 

const OBJECTID_t lRelID.

LPCTSTR strObjName,

const bool WithLock = false);

HRESULT GetDestCollectionKeys(

Vector<CMetaRelationshipKey>& objectKeyList, 

const MetaFilterInfoVector &propFilter,

const GUID &gRelID, 

const OBJECTID_t lRelID.

LPCTSTR strObjName,

const bool WithLock = false);

const OBJECTID_t returnClass = NULLLOID,

const bool allClasses = false,

For more information on creating the propFilter for the search, see Chapter 8: “CMetaFilterInfo Class.”

For more information on building the strObjName parameter for a search, see “Name Search” on page 131.

For more information on the settings for allClasses and returnClass, see “Inheritance” on page 132.

Argument	In/Out	Description
objectKeyList	In/Out	Reference to the list of keys that will hold the collection returned. The list is cleared before adding the return collection.
propFilter	In	List of FilterInfo objects containing the property id and value to use to perform the search
gRelID	In	Relationship ID. Can be set to NULLGUID if gRelID is set.
lRelID	In (Optional)	Relationship internal ID. Optional, if lRelID is set.
strObjName	In	Specific name of object in the collection to be returned.
returnClass	In (Optional)	If the allClasses parameter is = true, the returnClass parameter is ignored. If the allClasses parameter = false: If returnClass = 0, the destination class defined in the relationship is returned. If the destination class in the relationship is a superclass, return class defines the class type of object to return (the superclass or one of its subclasses) If the destination class in the relationship is not a superclass and return class specifies a classid other than the destination class, an error will be returned.
WithLock	In	WithLock=true keeps the Dest Collection table locked for WRITE. Use within an explicit transaction. Set WithLock to true when one of the Dest Collection objects will subsequently be updated within the transaction. This prevents deadlocks caused by Teradata promotional locks.
allClasses	In (Optional)	If the destination class in the relationship is a superclass, setting allClasses = true will return all class types (superclass and subclasses). If allClasses = false, the destination class returned is determined by the returnClass parameter. If allClasses = true and the destination class in the relationship is not a superclass, only object keys of the destination class defined in the relationship are returned. If allClasses = true, the return list is sorted first by class.