GetDestCollectionVersions - Teradata Meta Data Services

Teradata Meta Data Services Programmer Guide
Product
Teradata Meta Data Services
Release Number
15.00
ft:locale
en-US
ft:lastEdition
2018-09-28
Product Category
Teradata Tools and Utilities

GetDestCollectionVersions

Purpose

GetDestCollectionVersions returns the collection (list of CMetaObjects) of the destination class associated with this CMetaObject for the specified relationship that matches the selection criteria. The function allows the programmer to specify the property id, property value and comparison operator on which to perform the search. The search is performed on the list of objects in the collection. If multiple properties are specified for the search, the logical operator between the property searches must be specified. The properties to be returned can be restricted by the use of the column filters vector. The name of the property upon which to sort the returned list can also be specified.

Description

GetDestCollectionVersions can be used with any version of the object and by default it will return all object versions that are found through rigid relationships and match the search conditions. If rigidRelsOnly is set to false, both rigid and semi-rigid relationships will be used to find destination objects.

Requirements

  • The internal object id must be set in the object and it must be for a version of the origin object.
  • The propFilter list may 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 GetDestCollectionVersions(
    vector<CMetaObject >& objectList,
    const MetaFilterInfoVector &propFilter,
    const MetaObjectKeyVector &sortList,
    const GUID &gRelID, 
    const OBJECTID_t lRelID = NULLLOID,
    LPCTSTR strObjName = NULL,
    LPCTSTR strLabel = NULL,
    const bool WithLock = false,
    const OBJECTID_t returnClass = NULLLOID,
    const bool allClasses = false,
    const bool skipValidation = false,
    const bool rigidRelsOnly = true);
     
    HRESULT GetDestCollectionVersions(
    vector<CMetaObject >& objectList,
    const MetaFilterInfoVector &propFilter,
    const MetaObjectKeyVector &sortList,
    const MetaObjectKeyVector &columnFilters,
    const GUID &gRelID, 
    const OBJECTID_t lRelID = NULLLOID,
    LPCTSTR strObjName = NULL,
    LPCTSTR strLabel = NULL,
    const bool WithLock = false,
    const OBJECTID_t returnClass = NULLLOID,
    const bool allClasses = false,
    const bool skipValidation = false,
    const bool rigidRelsOnly = true);

    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 building the sortList parameter, see “Sort List” on page 130.

    For more information on using the columnFilters parameter, see “Column Filter” on page 132.

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

     

    Argument

    In/Out

    Description

    ObjectList

    In/out

    Reference to the list of CMetaObjects 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

    sortList

    In

    List of property identifiers (relative property id or name) to sort the collection by. The return list will be returned in ascending order and the sort will not be case specific.

    columnFilters

    In

    List of property IDs defining the common and unique properties to be set in each object. An empty vector means to return all properties.

    gRelID

    In

    Relationship GUID.

    lRelID

    In

    Relationship internal ID.

    StrObjName

    In
    (Optional)

    Search string for names of objects in the collection to be returned.

    strLabel

    In
    (Optional)

    Label string to filter the objects; only object versions with the label will be returned.

    WithLock

    In

    WithLock=true keeps the class table of the Origin Collection locked for WRITE. Use within an explicit transaction. Set WithLock to true when one of the Origin Collection objects will subsequently be updated within the transaction. This prevents deadlocks caused by Teradata promotional locks.

    returnClass

    In

    If the allClasses parameter is = true, the returnClass parameter is ignored. If the allClasses parameter = false:

  • If returnClass = 0, the origin class defined in the relationship is returned.
  • If the origin 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 origin class in the relationship is not a superclass and return class specifies a classid other than the origin class, an error will be returned

    • allClasses

    In

    If the origin class in the relationship is a superclass, setting allClasses = true will return all class types (superclass and subclasses). If allClasses = false, the origin class returned is determined by the returnClass parameter. If allClasses = true and the origin class in the relationship is not a superclass, only objects of the origin class defined in the relationship are returned.

    skipValidation

    In

    The function validates that the id of the object is an object in the destination class (or subclass) of the relationship. If returnClass is specified, the function will validate that the returnClass is the origin class (or subclass) of the relationship. If skipValidation is true, this validation is not performed. If the validation is not performed and the validation would have returned an error, the function will return zero objects in the ObjectList.

    rigidRelsOnly

    In

    If set true, the function will only return destination objects that are found through rigid relationships; that is, they are the latest version of the destination object associated with the version of the calling object. If set false, the function will return all destination object versions that can be reached from the origin object version.