MetaActive Class - Teradata Meta Data Services

MetaActive Class

The IMetaActive COM class contains one interface: IMetaActive. The interface supports a variety of functions and methods to maintain repository objects.

Initialize

Purpose:

Use this method to initialize with the MDS repository.

Description:

The Initialize method will create a connection to the MDS repository. Either the Initialize or SignOn method must be called before any other MDS COM calls. The connection remains open until the DeInitialize method is called.

Syntax:

HRESULT Initialize(

[in] BSTR Username, 

[in] BSTR Password);

DeInitialize

Purpose:

The DeInitialize method removes or closes the connection to the MDS repository.

Description:

This method should always be called before terminating to insure the database connection to the MDS repository is properly closed.

Syntax:

HRESULT DeInitialize();

SignOn

Purpose:

Use this method to sign on to the MDS repository as a different user.

Description:

Each MDS MetaActive COM class object will support one user. If the user signs on with a different user name, any subsequent MDS API calls will have the new user name as the caller and the security will be based on the user access rights. To support multiple users in a single process, create multiple MetaActive objects and assign one user per each of the MetaActive objects.

If the MDS repository has not already been initialized, it will be at this time.

Syntax:

HRESULT SignOn(

[in] BSTR Username, 

[in] BSTR Password);

SignOff

Purpose:

Use this method to sign off the user that was signed on.

Description

If the MDSUserName is not specified, the MDS user associated with this MetaActive object is signed off. An MDS user can be associated with a MetaActive object in one of three ways: first, during an Initialize call, second, during a SignOn call or third, by setting the MDSCaller property for the object. If no user name is specified for the call, and no user is associated with the MetaActive object, the engine will return a META_E_USER_NOT_SIGNED_ON error.

Syntax:

HRESULT SignOff([in] BSTR MDSUserName);

ReadObject

Purpose:

Use this method to read in an object from the MDS repository.

Description:

This may require waiting for write locks held by other transactions to be released. MDS does not support reads of write-locked MDS repository data.

In a repository with versioning on, ReadObject always returns the “published” or “current” version. This includes the case where the LOID of the MetaInfo object to be read is *not* the LOID of the published version. This allows ReadObject to behave in a similar fashion on repositories with versioning on or off. To read a specific object version, use ReadObjectVersion.

Reading an object from one of the classes in the DIM AIM (DatabaseModel meta model) will also return the object's DIM information (System Name, Database Name and Table Name). This DIM information is placed in the "DIMInfo" property of the MetaInfo object. This information is acquired by several JOIN operations, and can cause some performance overhead, especially in version-enabled repositories.

If DIM information is not needed for an object from a DIM class, set the MetaActive DIMInfoNeeded property to FALSE before the object is read. With this setting the MDS engine executes the read as if the object is from a non-DIM class, so it will not execute the DIM-related JOINs. All other object properties will be retrieved as usual; the DIM fields will be empty. The result can be significant performance savings when the DIM information is not needed. Note that objects from classes not in the DIM AIM never retrieve DIM information, and so never incur the JOIN overhead.

Requirements:

The MDS COM MetaInfo object must be created and the object identification attributes must be set before calling the ReadObject method. The object identification attributes can be the class ID (internal or globally unique) and the object name or the object identifier (internal or globally unique).

Syntax:

HRESULT ReadObject(

[in] IMetaInfo *MetaInfo);

ReadObjectVersion

Purpose:

Use this method to read in an object from the MDS repository.

Description:

Identical to the ReadObject call, except that in a repository with versioning on, the version of the object read is the one specifically identified by the LOID in the MetaInfo interface object. In contrast, the ReadObject call always returns the published version of the object no matter which version the LOID is associated with.

Reading an object from one of the classes in the DIM AIM (DatabaseModel meta model) will also return the object's DIM information (System Name, Database Name and Table Name). This DIM information is placed in the "DIMInfo" property of the MetaInfo object. This information is acquired by several JOIN operations, and can cause some performance overhead, especially in version-enabled repositories.

If DIM information is not needed for an object from a DIM class, set the MetaActive DIMInfoNeeded property to FALSE before the object is read. With this setting the MDS engine executes the read as if the object is from a non-DIM class, so it will not execute the DIM-related JOINs. All other object properties will be retrieved as usual; the DIM fields will be empty. The result can be significant performance savings when the DIM information is not needed. Note that objects from classes not in the DIM AIM never retrieve DIM information, and so never incur the JOIN overhead.

Syntax:

HRESULT ReadObjectVersion(

[in] IMetaInfo *MetaInfo);

ReadDormantObject

Purpose:

This routine extends the functionality of ReadObject to return an object that is either active ("mdsCurrent") or dormant.

Description:

If the DIMInfoNeeded property for this class has been set to True, the IMetaInfo object will have its DIMInfo information associated with it.

If the return status is S_OK, check the PublishState to determine if the object is current (PublishState is "mdsCurrent") or is dormant (PublishState is "mdsDormant").

The order of evaluation to determine the object to be read is:

1 ObjectID if not zero

2 ObjectGUID if not null

3 ClassID and Name if the ClassID is not zero

4 ClassGUID and Name

Reading an object from one of the classes in the DIM AIM (DatabaseModel meta model) will also return the object's DIM information (System Name, Database Name and Table Name). This DIM information is placed in the "DIMInfo" property of the MetaInfo object. This information is acquired by several JOIN operations, and can cause some performance overhead, especially in version-enabled repositories.

If DIM information is not needed for an object from a DIM class, set the MetaActive DIMInfoNeeded property to FALSE before the object is read. With this setting the MDS engine executes the read as if the object is from a non-DIM class, so it will not execute the DIM-related JOINs. All other object properties will be retrieved as usual; the DIM fields will be empty. The result can be significant performance savings when the DIM information is not needed. Note that objects from classes not in the DIM AIM never retrieve DIM information, and so never incur the JOIN overhead.

Requirements:

The requirements for specifying the object to be returned are the same as those for ReadObject.

This routine can only be called by an administrative user.

Syntax:

HRESULT ReadDormantObject(

[in] IMetaInfo *MetaInfo);

WriteObject

Purpose:

Use this method to write the object into the MDS repository.

Description:

This may require waiting for write locks held by other transactions to be released. MDS does not support reads of write-locked MDS repository data.

In a repository with versioning on, WriteObject writes a new version of the object to the repository. The new object has the same GUID as the current version, but the LOID is different and of course, and the version number is one greater than the “current” version of the object. This also means that this write produces the new “current” or “published” version of the object, replacing the previous current version (which is now in the “inactive” published state). To re-write the current version of the object when versioning is on, use WriteObjectVersion.

Requirements

The MDS COM MetaInfo object must be created and the object identification attributes must be set before calling the WriteObject method. The object identification attributes can be the class ID (internal or globally unique) and the object name or the object identifier (internal or globally unique).

Syntax:

HRESULT WriteObject(

[in] IMetaInfo *MetaInfo);

WriteObjectVersion

Purpose:

Use this method to write the object into the MDS repository.

Description:

Identical to the WriteObject method except that in a repository with versioning on, the published (current) version is updated, that is, a new version is not written. Since only the current version of an object can be updated, if WriteObjectVersion is attempted on any other version, the user will receive an error (META_E_OBJECT_ISFROZEN).

Syntax:

HRESULT WriteObjectVersion(

[in] IMetaInfo *MetaInfo);

Delete

Purpose:

Use this method to delete an object from the MDS repository.

Description:

This may require waiting for write locks held by other transactions to be release.

In a repository with versioning on, Delete deletes all versions of the object from the repository so that the object is completely removed from the repository. This makes its behavior consistent with that of a non-versioned repository, where a Delete also completely removes the object from the repository. If you wish to remove a specific version(s) of the object, use DeleteVersion or DeleteVersionRange.

If the object is from a DIM class that has business information associated with it, and the retain-business-objects feature is enabled, the object will have its PublishState changed to "dormant" (mdsDormant) and not be removed from the repository. The object can be re-activated or removed at a later time with the appropriate function call (see “ActivateDormantObject” on page 313 or “DeleteDormantObject” on page 313, respectively). If the object’s PublishState is mdsDormant, this call will fail; use the DeleteDormantObject to specifically delete dormant objects.

Requirements

The MDS COM MetaInfo object must be created and the object identification attribute must be set before calling the Delete method. The object identification attribute is the object identifier.

Syntax:

HRESULT Delete(

[in] IMetaInfo *MetaInfo);

DeleteDormantObject

Purpose:

Use this method to force the deletion an object from the MDS repository even if the object would otherwise be a candidate for having its publish state set to dormant because the retain-business-objects feature is enabled.

Description:

The object can be either dormant or non-dormant.

Requirements

This routine can only be called by an administrative user.

Syntax:

HRESULT DeleteDormantObject (

[in] IMetaInfo *MetaInfo);

ActivateDormantObject

Purpose:

Use this method to change a dormant object to an active object, and re-associate of all its business information back to it.

Description:

The change is immediately made to the repository. By default, the (re)activation is propagated to all objects that are in the destination class of any relationship from this (origin) object, and those objects also have their business information (if any), re-associated. The call has no effect if the object is already active, that is, the PublishState is already "mdsCurrent".

Requirements

This routine can only be called by an administrative user.

Reactivating an object will require DELETE permission.

Syntax:

HRESULT ActivateDormantObject (

[in] IMetaInfo *MetaInfo);

DeleteVersion

Purpose:

Use this method to delete an object from the MDS repository.

Description:

Identical to the Delete routine except that the DeleteVersion routine removes only that version identified by the MetaInfo object; no other versions are deleted. If the current or “published” version is deleted, then the previous version becomes the current version.

Syntax:

HRESULT DeleteDormantObject(

[in] IMetaInfo *MetaInfo);

DeleteVersionRange

Purpose:

Use this method to delete an object from the MDS repository.

Description:

Identical to the DeleteVersion routine except that the user can specify a range of versions to be deleted. If the startVersion parameter is less than 1, or greater than the highest version for the object, an error will be returned. The endVersion parameter indicates the highest version to be deleted. If endVersion is not provided, all versions from startVersion to the current version will be deleted, and the new highest version number will become the current version. If endVersion is 0, or greater than the current version number, the current version number will be assumed to be the end version.

Syntax:

HRESULT DeleteVersionRange(

[in] IMetaInfo *MetaInfo 

[in] long startVersion. 

[in] long endVersion = 0);

GetObjectID

Purpose:

Use this method to get the local internal object identifier given the class identification and name or object GUID.

Description:

If the ObjectGUID is known, it is sufficient by itself to retrieve the object’s ID. However, if the object’s GUID is not known, you will need to specify either the ClassGUID or ClassID, along with the object’s name.

If the object is not found in the repository and there were not repository errors reported (that is, HRESULT is S_OK), an ObjectID of 0 is returned.

Syntax:

HRESULT GetObjectID(

[in, optional] BSTR ObjectGUID, 		

[in, optional] BSTR ClassGUID, 

[in, optional] long ClassID, 

[in, optional] BSTR Name, 

[out, retval] long *lpObjectID);

GetClassObjects

Purpose:

Use this method to retrieve the MDS objects in a particular class.

Description:

This may require waiting for write locks held by other transactions to be release. If the optional Name parameter is specified, the method will only retrieve the object with the matching object name.

Requirements:

The class identification can be a class GUID or a class internal identifier. The class GUID is a string representation of the GUID format (for example: {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT GetClassObjects(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in, optional] BSTR Name, 

[out, retval] IMetaInfoList **InfoList);

GetClassObjectVersions

Purpose:

Use this method to get the local internal object identifier given the class identification and name or object GUID.

Description:

Identical to the GetClassObjects routine except for the addition of the optional LabelName parameter.

For repositories that have versioning enabled, this routine returns not only all objects for the class, but all versions of each object, unless a label is specified by the LabelName parameter. In that case, the label acts like a filter returning only those object versions that have the label attached to them.

Syntax:

HRESULT GetClassObjects(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in, optional] BSTR Name, 

[in, optional] BSTR LabelName,

[out, retval] IMetaInfoList **InfoList);

GetClassObjectKeys

Purpose:

Use this method to retrieve the MDS object keys in a particular class. This may require waiting for write locks held by other transactions to be release.

Description:

If a value for the optional Name parameter is specified, only those objects whose names match the pattern are returned. (Name-patterns accept Teradata wildcard characters.) If the Name parameter is omitted, all objects from the class are returned. For a version-enabled repository, the returned objects are the current, non-frozen versions only. To get inactive or frozen versions of an object, use GetClassObjectVersionKeys or any GetClassObjects call.

Requirements:

The class identification can be a class GUID or a class internal identifier. The class GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT GetClassObjectKeys(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in, optional] BSTR Name, 

[out, retval] IMetaInfoKeyList **InfoKeyList);

GetDormantClassObjectKeys

Purpose:

Use this method to retrieve only the keys for dormant objects in a particular class.

Description:

This routine returns a list of IMetaInfoKeys in the InfoKeyList parameter, that identifies the dormant objects in the specified class. Only the keys of dormant objects (PublishState = "mdsDormant") are returned. The class must be specified by either the ClassGUID or ClassID. If only one named object is to be returned from the class, its name should be specified in the Name parameter.

This routine is expected to be used by a meta data browser to enable it to display the name and/or id of objects in a class without having to read the entire collection of objects into memory.

This routine can only be called by an administrative user.

Syntax:

HRESULT GetDormantClassObjectKeys(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in, optional] BSTR Name,

[out, retval] IMetaInfoKeyList **keyList);

GetClassObjectVersionKeys

Purpose:

Use this method to retrieve the MDS object keys in a particular class.

Description:

Identical to the GetClassObjectKeys routine except for the addition of the optional LabelName parameter, and the return of a collection of MetaVersionedInfoKeys instead of MetaInfoKeys.

For repositories that have versioning enabled, this routine returns not only keys of all objects in the repository, but all versions of all objects, unless a label is specified. If a label is specified by the LabelName parameter, it acts as a filter returning only those object versions that have the label attached to them.

If the optional Name parameter is provided, only those objects whose Name matches the parameter are returned. [The match is exact but case-insensitive. The effect is similar to adding a filter of “WHERE (...) AND Name = ‘name-value’” to the SQL.]

Syntax:

HRESULT GetClassObjectVersionKeys(

[in] BSTR ClassGUID,

[in] long ClassID,

[in, optional] BSTR LabelName,

[in, optional] BSTR Name,

[out, retval] IMetaversionedInfoKeyList **keyList);

GetCollections

Purpose:

Use this method to retrieve the MDS collection objects in the object relationship.

Description:

This may require waiting for write locks held by other transactions to be release. If the optional Name parameter is specified, the method will only retrieve the object with the matching object name in the object relationship.

Requirements

The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT GetCollections(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in] long RelationshipID, 

[in, optional] BSTR Name, 

[out, retval] IMetaInfoList **InfoList);

GetCollectionKeys

Purpose:

Use this method to retrieve the MDS collection object keys in the object relationship.

Description:

This may require waiting for write locks held by other transactions to be release. If the optional Name parameter is specified, the method will only retrieve the object key with the matching object name in the object relationship.

Requirements

The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT GetCollectionKeys(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in] long RelationshipID, 

[in, optional] BSTR Name, 

[out, retval] IMetaInfoKeyList **InfoKeyList);

GetClassObjectsByProperty

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

The GetClassObjectsByProperty method returns a list of MetaInfo objects that matches the selected criteria. The function allows the programmer to specify the property id, property value and comparison operator on which to perform the search. If multiple properties are specified in the search, the logical operator between the property searches must also be specified.

If the DIMInfoNeeded property for this class has been set to True, the IMetaInfo objects returned will each have DIM information associated with them. For more information on this method and its usage, see Chapter 8: “CMetaFilterInfo Class,” and “GetClassObjectsByProperty” on page 167 in Chapter 7: “CMetaObject Class.”

Requirements:

The class identification can be a class GUID or a class internal identifier. The class GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

For each of the MetaFilter object, the property identifier or the property name must be set and must contain a valid relative property identifier or name of a property description in the class. The value must also be set 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 the relative property identifier = 1 and the relative property identifier is defined as an integer, the value must be set to an integer.

Syntax:

HRESULT GetClassObjectsByProperty(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in] BSTR NamePattern, 

[in] IMetaFilterList *Filters, 

[in] IMetaInfoKeyList *SortKeys, 

[out, retval] IMetaInfoList **InfoList);

GetClassObjectsByProperty2

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

This method is identical to the GetClassObjectsByProperty method except that the ColumnFilter parameter allows the caller to specify which properties are to be returned by the implementation.

Refer to “ColumnFilter” on page 305 for additional information.

Syntax:

HRESULT GetClassObjectsByProperty2(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in] BSTR NamePattern, 

[in] IMetaFilterList *Filters, 

[in] IMetaInfoKeyList *SortKeys, 

[in, optional]  IMetaInfoKeyList* ColumnFilter,

[out, retval] IMetaInfoList **InfoList);

GetClassObjectVersionsByProperty

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

Identical to the GetClassObjectsByProperty except for the addition of the optional LabelName parameter.

For a repository that has versioning enabled, this routine returns all versions of those objects that match the property filter, unless a label is also specified by the LabelName parameter. In that case, the label acts as another filter returning only those objects that also have the label attached to them. (Note also that the filter list and sort key list are both optional.)

Syntax:

HRESULT GetClassObjectVersionsByProperty(

[in] BSTR ClassGUID,

[in] long ClassID,

[in] BSTR NamePattern,

[in, optional] BSTR LabelName,

[in, optional] IMetaFilterList *Filters,

[in, optional] IMetaInfoKeyList *SortKeys,

[out, retval] IMetaInfoList **InfoList);

GetClassObjectVersionsByProperty2

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

Identical to the GetClassObjectVersionsByProperty except that the ColumnFilter parameter allows the caller to specify which properties are to be returned by the implementation.

Refer to “ColumnFilter” on page 305 for additional information

Syntax:

HRESULT GetClassObjectVersionsByProperty2(

[in] BSTR ClassGUID,

[in] long ClassID,

[in] BSTR NamePattern,

[in, optional] BSTR LabelName,

[in, optional] IMetaFilterList *Filters,

[in, optional] IMetaInfoKeyList *SortKeys,

[in, optional] IMetaInfoKeyList *ColumnFilter,

[out, retval] IMetaInfoList **InfoList);

GetClassObjectsByRange

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

This method is identical to the GetClassObjectsByProperty method with the addition of three new parameters. The new parameters allow the caller to specify how many items are to be returned in “RequestCount”, and the offset in the result set at which to start returning in “Start”. It also returns the actual count of items in the ReturnCount parameter.

If the DIMInfoNeeded property for this class has been set to True, the IMetaInfo objects returned will each have DIM information associated with them.

This method was created especially for browser applications where there are 10s or 100s of thousands of items that could be returned, but only a “page full” at a time will be displayed. It would be of no value for the application to wait for all the items to become available (which could take some time), as happens in the GetClassObjectsByProperty call. With this method, the user can specify a page-full of items starting at anywhere in the result set, and thereby get results much faster than waiting for the entire result set.

Requirements:

The requirements are the same as for “GetClassObjectVersionsByProperty” on page 322

Syntax:

HRESULT GetClassObjectsByRange(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in] BSTR NamePattern, 

[in] int Start, 

[in] int RequestCount, 

[out] VARIANT *ReturnCount, 

[in] IMetaFilterList *Filters, 

[in] IMetaInfoKeyList *SortKeys, 

[out, retval] IMetaInfoList **InfoList);

GetClassObjectsByRange2

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

Identical to the GetClassObjectsByRange routine except that the ColumnFilter parameter allows the caller to specify which properties are to be returned by the implementation.

Refer to “ColumnFilter” on page 305 for additional information

Requirements:

The requirements are the same as for “GetClassObjectVersionsByProperty” on page 322

Syntax:

HRESULT GetClassObjectsByRange2(

[in] BSTR ClassGUID,

[in] long ClassID,

[in] BSTR NamePattern,

[in] int Start,

[in] int RequestCount,

[out] VARIANT *ReturnCount,

[in] IMetaFilterList *Filters,

[in] IMetaInfoKeyList *SortKeys,

[in] IMetaInfoKeyList *ColumnFilter,

[in, optional]  IMetaInfoKeyList* ColumnFilter,

[out, retval] IMetaInfoList **InfoList);

GetClassObjectVersionsByRange

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

Identical to the GetClassObjectsByRange routine except for the addition of the optional LabelName parameter.

For repositories that have versioning enabled, this routine returns the range of all versions of those class objects that match the property filter, unless a label is also supplied. If a label is supplied by the LabelName parameter, it acts as a filter returning only those versions of the objects that have the label attached to them. Since the LabelName is used with a "LIKE" clause when the request is sent to the database, it can have Teradata wildcard search characters in it. (Note that the filter list and sort-key list are also optional.)

Requirements:

The requirements are the same as for “GetClassObjectVersionsByProperty” on page 322

Syntax:

HRESULT GetClassObjectVersionsByRange(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in] BSTR NameParameter, 

[in] int Start, 

[in] int RequestCount,

[out] VARIANT* ReturnCount, 

[in, optional] BSTR LabelName, 

[in, optional] IMetaFilterList* Filters 

[in, optional] IMetaInfoKeyList* SortKeys, 

[out, retval] IMetaInfoList** InfoList);

GetClassObjectVersionsByRange2

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified class.

Description:

Identical to the GetClassObjectVersionsByRange routine except that the ColumnFilter parameter allows the caller to specify which properties are to be returned by the implementation.

Refer to “ColumnFilter” on page 305 for additional information

Requirements:

The requirements are the same as for “GetClassObjectVersionsByProperty” on page 322

Syntax:

HRESULT GetClassObjectVersionsByRange2(

[in] BSTR ClassGUID, 

[in] long ClassID, 

[in] BSTR NameParameter, 

[in] int Start, 

[in] int RequestCount,

[out] VARIANT* ReturnCount, 

[in, optional] BSTR LabelName, 

[in, optional] IMetaFilterList* Filters 

[in, optional] IMetaInfoKeyList* SortKeys,

[in, optional] IMetaInfoKeyList* ColumnFilter, 

[out, retval] IMetaInfoList** InfoList);

GetDormantClassObjects

Purpose:

Use this method to search for objects with their publish state set to mdsDormant in the specified class.

Description:

This routine is essentially the same as the GetClassObjectsbyProperty routine, except the only objects returned are those that are “dormant”, that is, they all have their PublishState = “mdsDormant”.

If the DIMInfoNeeded property for this class has been set to True, the IMetaInfo objects returned will each have DIMInfo information associated with them.

Requirements:

This routine may only be called by an administrative user.

Syntax:

HRESULT GetDormantClassObjects(

[in] BSTR ClassGUID, 

[in, optional, defaultvalue(0)] long ClassID, 

[in, optional] BSTR NamePattern, 

[in, optional] IMetaFilterList *Filters, 

[in, optional] IMetaInfoKeyList *SortKeys, 

[out, retval] IMetaInfoList **InfoList);

GetCollectionsByProperty

Purpose:

Use this method to perform searching on the matching properties of the objects in the specified relationship.

Description:

The GetCollectionByProperty method returns a list of MetaInfo objects that matches the selected criteria in the specified relationship. The function allows the programmer to specify the property id, property value, and comparison operator on which to perform the search. If multiple properties are specified in the search, the logical operator between the property searches must also be specified.

If the DIMInfoNeeded property for this class has been set to True, the IMetaInfo objects returned will each have DIM information associated with them. For more information on this method and its usage, see Chapter 8: “CMetaFilterInfo Class” and Chapter 7: “CMetaObject Class.”

Requirements:

The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

For each of the MetaFilter object, the property identifier or the property name must be set and must contain a valid relative property identifier or name of a property description in the class. The value must also be set 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 the relative property identifier = 1 and the relative property identifier is defined as an integer, the value must be set to an integer.

Syntax:

HRESULT GetCollectionsByProperty(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in] long RelationshipID, 

[in] BSTR NamePattern, 

[in] IMetaFilterList *Filters, 

[in] IMetaInfoKeyList *SortKeys,

[out, retval] IMetaInfoList **InfoList);

IsVersioningEnabled

Purpose:

Returns the repository versioning setting.

Description:

Returns VARIANT_TRUE (true) if versioning is enabled (on) for the repository, else it returns FALSE. Currently, repository versioning can only be enabled/disabled during a metacreate or metamigrate.

Syntax:

HRESULT IsVersioningEnabled(

[out, retval] VARIANT_BOOL* val);

put_DIMInfoNeeded

Purpose:

This call sets the DIMInfoNeeded property for this class.

Description:

When this property is set to "true" (its default setting), the DIM information will be set for each of the returned items. This means that the MetaInfo property get_DIMInfo will return a filled-out MetaDIMInfo class. This is the normal case. However, for performance reasons, the user may not need DIM info for the returned MetaInfo items, and so can save time (and memory) by setting the DIMInfoNeeded property to "false" before making the MetaActive call. The only method calls affected by this property are:

Syntax:

HRESULT put_DIMInfoNeeded(

[in] VARIANT_BOOL newVal);

get_DIMInfoNeeded

Purpose:

This call returns the current setting of the DIMInfoNeeded property.

Syntax:

HRESULT get_DIMInfoNeeded(

[out, retval] VARIANT_BOOL *pVal);

AddManyToCollection

Purpose:

Use this method to add a list of object keys to the object relationship.

Description:

This may require waiting for write locks held by other transactions to be release. The merge argument indicates whether the specified object key list should be merged with the object collection. If the merge argument is true (1), the MDS repository will ignore any object ids in the list that are already in the object collection. If false, an error will be returned if the object ids are already in the object collection.

Requirements:

The relationship identification must be set. The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT AddManyToCollection(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in] long RelationshipID, 

[in] IMetaInfoKeyList *ObjectList, 

[in, optional] BOOL Merge);

AddManyToRelCollection

Purpose:

Use this method to add a list of object keys to the object relationship where an Explanation property is to be attached to relationship associations.

Description:

This call is identical to the AddManyToCollection call, except that the ObjectList parameter is of type IMetaRelationInfoKeyList. This list contains MetaRelationInfoKey objects, instead of MetaInfoKey objects which the AddManyToCollection call uses. The MetaRelationInfoKey object includes an Explanation property which can be used to set the "Explanation" for the each of the objects in the association. If relationship associations do not have an Explanation property attached (which is the normal case), use the AddManyToCollection call.

Requirements:

The relationship identification must be set. The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT AddManyToRelCollection(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in] long RelationshipID, 

[in] IMetaRelationshipInfoKeyList *ObjectList, 

[in, optional] VARIANT_BOOL Merge);

RemoveManyFromCollection

Purpose:

Use this method to remove a list of object keys to the object relationship.

Description:

This may require waiting for write locks held by other transactions to be release. The merge argument indicates whether the specified object key list should be removed from the object collection. If the merge argument is true, the MDS repository will ignore any object ids in the list that are not already in the object collection. If false, an error will be returned if the object ids are not already in the object collection.

Requirements:

The relationship identification must be set. The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT RemoveManyFromCollection(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in] long RelationshipID, 

[in] IMetaInfoKeyList *ObjectList, 

[in, optional] BOOL Merge);

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

RemoveAllFromCollection

Purpose:

Use this method to remove all the objects from a collection, as specified by the direction, object ID and Relationship indicated.

Description:

Objects are removed from the collection, not the repository. That is, collections are the result of relationships which indicate a mapping between two objects, one set from the "Origin" class(es) and the other from the "Destination" class(es). (We say "classes" because due to inheritance, more that one class may be part of the Origin or Destination set of classes.) So this routine removes objects from the collection, which means deleting the mapping, but not the objects themselves, from the repository.

The optional parameters "TargetClass" and "AllClasses" are used for collections that involve inheritance.

This routine call ultimately calls CMetaObject:: RemoveAllFromOrigCollection2 and RemoveAllFromDestCollection2 in the MDS C++ class library.

Requirements:

The relationship identification must be set. The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT RemoveAllFromCollection(

[in] CollectionType Direction, 

[in] long ObjID, 

[in, optional] BSTR RelGUID, 

[in, optional] long RelID, ,  

[in, defaultvalue(0)] long TargetClass, 

[in, defaultvalue(0)] VARIANT_BOOL AllClasses);

{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}

ReplaceCollection

Purpose:

Use this method to replace a list of object keys of the object relationship. This may require waiting for write locks held by other transactions to be release.

Description:

See CMetaObject::ReplaceXXXCollection for more detail.

Note: For Relationships inherited by sub-classes, target class-object collections will be replaced only if they appear in the ObjectList. For example, if the ObjectList has objects from two of three possible sub-classes inherited with the relationship, then only those two collections will be “replaced” by this call (all current objects removed, being replaced by the ones in the ObjectList), and whatever objects were in the third class’s collection, will remain the same.

Requirements:

The relationship identification must be set. The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT ReplaceCollection(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in] long RelationshipID, 

[in] IMetaInfoKeyList *ObjectList);

ReplaceRelCollection

Purpose:

Use this method to replace a list of object keys of the object relationship. This may require waiting for write locks held by other transactions to be release.

Description:

Identical to the ReplaceCollection call, except that the ObjectList parameter is of type IMetaRelationInfoKeyList. This list contains MetaRelationInfoKey objects, instead of MetaInfoKey objects which the ReplaceCollection call uses. The MetaRelationInfoKey object includes an Explanation property which can be used to set the Explanation for the each of the objects in the association. If not attaching an Explanation to the relationship associations (which would be the normal case), use the ReplaceCollection call.

Requirements:

The relationship identification must be set. The relationship identification can be a relationship GUID or a relationship internal identifier. The relationship GUID is a string representation of the GUID format (that is, {8CAF7740-EECD-11d3-9D01-00902781A33F}).

Syntax:

HRESULT ReplaceRelCollection(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in] BSTR RelationshipGUID, 

[in, optional, defaultvalue(0)] long RelationshipID, 

[in] IMetaRelationInfoKeyList *ObjectList);

GetBIZObjectsByRange

Purpose:

This routine returns business-related properties from the business classes, based on the requested filter list. The Start and RequestCount parameters can be used to request a specific range of the total result to be returned.

The following business classes and properties are included in the search:

Description:

This routine is the only way that MetaBIZInfoList can be created. This routine ultimately calls CMetaBIZObject::GetBIZObjectsByRange in the MDS C++ class library.

Requirements:

Although the Filters parameter shows as optional, the engine will return a "missing required parameter" if one is not set.

Syntax:

HRESULT GetBIZObjectsByRange(

[in] int Start,  

[in] int RequestCount,  

[in] MetaSortType SortType, 

[out] VARIANT *ReturnCount,  

[in] IMetaFilterList *Filters,  

[in, optional] BSTR Label,

[out, retval] IMetaBIZInfoList **BIZInfoList);

GetBIZObjectVersionsByRange

Purpose:

Returns all versions of each object.

Description:

This routine is identical to the GetBIZObjectsByRange except that all versions of each object are returned, not just the "Current" (or Published) version. What this means is that, unlike the GetBIZObjectsByRange call, if a label is specified in the Label parameter, it does not have to be applied to the Current version of an object for that version of the object to be returned.

This routine makes sense to use only in versioned repositories; for non-versioned repositories, use the GetBIZObjectsByRange call described above.

Syntax:

HRESULT GetBIZObjectVersionsByRange(

[in] int Start,  

[in] int RequestCount,  

[in] MetaSortType SortType, 

[out] VARIANT *ReturnCount,  

[in] IMetaFilterList *Filters,  

[in, optional] BSTR Label,

[out, retval] IMetaBIZInfoList **BIZInfoList);

GetCollectionKeysByProperty

Purpose:

This routine is used to search the repository for the origin or destination collection of the relationship of the object.

Description:

The search can be for repository objects of a given name (if desired), and/or using a filter list. (The "origin or destination" is given by the Direction parameter, the "relationship" is given by either the RelationshipGUID or RelationshipID parameter, the "object" itself is identified by the ObjectID parameter, the "name" is given by the Name parameter and the "filter list" is given by the Filters parameter.)

The caller can also specify the class ID of a particular class to search (the ReturnClass parameter), or that all classes are to be searched (the AllClasses parameter). These two parameters are useful for searches of relationships that have been inherited by the given object, and can therefor include many classes in the resulting collection.

The user can also ask that the MDS engine check to see that the object ID is in the proper origin or destination class for the given Destination and Relationship. Set the SkipValidation parameter to false if this check is desired. If validation is not preformed (SkipValidation is true), and this step would have returned an error, the call will simply return S_OK and have 0 objects in the InfoKeyList collection.

What is returned is a collection of IMetaInfoClassKey interface objects, which contain the "keys", that is, object IDs and Names, of all the items found in the repository for the collection, which also match any filters given.

This routine ultimately calls CMetaObject::GetOrigCollectionKeys3 or CMetaObject::GetDestCollectionKeys3 in the C++ class library.

Syntax:

HRESULT GetCollectionKeysByProperty(

[in] CollectionType Direction, 

[in] long ObjectID,  

[in, optional] BSTR RelationshipGUID, 

[in, optional] long RelationshipID, 

[in, optional] BSTR Name,  

[in, optional] IMetaFilterList *Filters, 

[in, defaultvalue(0)] long ReturnClass,  

[in, defaultvalue(0)] VARIANT_BOOL AllClasses, 

[in, defaultvalue(0)] VARIANT_BOOL SkipValidation, 

[out, retval] IMetaInfoClassKeyList **InfoClassKeyList);

GetCollectionVersionKeysByProperty

Purpose:

This routine is used to search the repository for the origin or destination collection of the relationship of the object.

Description:

Identical to the GetCollectionKeysByProperty routine except for the addition of the optional LabelName parameter.

For repositories with versioning enabled, returns the collection keys for the object (given by ObjectID and relationship identification) whose versions match the filter, unless a label is supplied. If a label is specified by the LabelName parameter, it acts as an additional filter returning only those object versions that also have the label attached to them.

Syntax:

HRESULT GetCollectionVersionKeysByProperty(

[in] CollectionType Direction,

[in] long ObjectID,

[in, optional] BSTR RelationshipGUID,

[in, optional] long RelationshipID,

[in, optional] BSTR Name,

[in, optional] BSTR LabelName,

[in, optional] IMetaFilterList *Filters,

[in, defaultvalue(0)] long ReturnClass,

[in, defaultvalue(0)] VARIANT_BOOL AllClasses,

[in, defaultvalue(0)] VARIANT_BOOL SkipValidation,

[out, retval] IMetaVersionedInfoKeyList **keyList);

GetCollectionVersionRelKeys

Purpose:

Use this routine to search the repository for the origin or destination collection of the relationship object if the Explanation property is attached to some or all of the relationship pairs.

Description:

Identical to the GetCollectionVersionKeysByProperty method of the MetaActive class interface, except that the key-list which returned is of type IMetaVersionedInfoRelKeyList.

This list contains MetaVersionedInfoRelKey objects. The objects are the same as MetaVersionedInfoClassKey objects (which are returned in the list from the GetCollectionVersionKeysbyProperty call), with the addition of the Explanation property.

If the associated relation pairs do not have an Explanation property attached (the usual case), use the GetCollectionVersionKeysByProperty call.

Syntax:

HRESULT GetCollectionVersionRelKeys(

[in] CollectionType Direction,

[in] long ObjectID,

[in, optional] BSTR RelationshipGUID,

[in, optional] long RelationshipID,

[in, optional] BSTR Name,

[in, optional] BSTR LabelName,

[in, optional] IMetaFilterList *Filters,

[in, defaultvalue(0)] long ReturnClass,

[in, defaultvalue(0)] VARIANT_BOOL AllClasses,

[in, defaultvalue(0)] VARIANT_BOOL SkipValidation,

[out, retval] IMetaVersionedInfoRelKeyList **keyList);

GetCollectionsByProperty2

Purpose:

This routine is used to search the repository for the origin or destination collection of the relationship of the object.

Description:

This routine is effectively the same as GetCollectionsByProperty with parameters added to indicate the need to return objects in inherited classes. These inheritance-related parameters are ReturnClass, AllClasses and SkipValidation. They are listed in the table below and work effectively the same as those in the GetCollectionKeysByProperty call described above.

If the Interface has the DIMInfoNeeded property set to True, the MetaInfo objects in the returned collection will have their DIMInfo filled in, else they will not.

This routine ultimately calls CMetaDIMObject:: GetOrigCollection3 or CMetaDIMObject:: GetDestCollection3 if DIMInfoNeeded is true; or CMetaObject:: GetOrigCollection3 or CMetaObject:: GetDestCollection3 if it is false.

Syntax:

HRESULT GetCollectionsByProperty2(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in, optional] BSTR RelationshipGUID, 

[in, optional] long RelationshipID, 

[in, optional] BSTR NamePattern, 

[in, optional] IMetaFilterList *Filters, 

[in, optional] IMetaInfoKeyList *SortKeys, 

[in, defaultvalue(0)] long ReturnClass, 

[in, defaultvalue(0)] VARIANT_BOOL AllClasses, 

[in, defaultvalue(0)] VARIANT_BOOL SkipValidation, 

[out, retval] IMetaInfoList **InfoList);

GetCollectionsByProperty3

Purpose:

This routine is used to search the repository for the origin or destination collection of the relationship of the object.

Description:

This routine is effectively the same as GetCollectionsByProperty2 except that the ColumnFilter parameter allows the caller to specify which properties are to be returned by the implementation.

Refer to “ColumnFilter” on page 305 for additional information

Note: If there are subclasses in the collection, the PIDs specified in the ColumnFilter must exist in all those classes. Effectively this means that the PIDs must be from the top-most class. The engine will return a property-not-found error otherwise.

Syntax:

HRESULT GetCollectionsByProperty3(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in, optional] BSTR RelationshipGUID, 

[in, optional] long RelationshipID, 

[in, optional] BSTR NamePattern, 

[in, optional] IMetaFilterList *Filters, 

[in, optional] IMetaInfoKeyList *SortKeys, 

[in, optional] IMetaInfoKeyList *ColumnFilter, 

[in, defaultvalue(0)] long ReturnClass, 

[in, defaultvalue(0)] VARIANT_BOOL AllClasses, 

[in, defaultvalue(0)] VARIANT_BOOL SkipValidation, 

[out, retval] IMetaInfoList **InfoList);

GetDormantCollectionKeys

Purpose:

Use this method to search for objects with their publish state set to mdsDormant in the specified class.

Description:

This routine is identical to GetCollectionKeysByProperty routine, except that the InfoClassKeyList which is returned has only the dormant object-keys of the specified collection for the object, limited by the filters and inheritance information parameters, if present.

The calling object may be dormant or active.

This routine can only be called by an administrative user.

Syntax:

HRESULT GetDormantCollectionKeys(

[in] CollectionType Direction, 

[in] long ObjectID,  

[in, optional] BSTR RelationshipGUID, 

[in, optional, defaultvalue(0)] long RelationshipID, 

[in, optional] BSTR Name,  

[in, optional] IMetaFilterList *Filters, 

[in, optional, defaultvalue(0)] long ReturnClass,  

[in, optional, defaultvalue(0)] VARIANT_BOOL AllClasses, 

[in, optional, defaultvalue(0)] VARIANT_BOOL SkipValidation, 

[out, retval] IMetaInfoClassKeyList **InfoClassKeyList);

GetDormantCollectionObjects

Purpose:

This routine is used to search the repository for dormant objects in the collection specified for the object.

Description:

This routine is identical to the GetCollectionsByProperty2 routine, except that the InfoList which is returned has only the dormant objects of the specified collection for the object, limited by the filters and inheritance information parameters, if present.

If the Interface has the DIMInfoNeeded property set to True, the MetaInfo objects in the returned collection will have their DIMInfo filled in, else they will not.

The calling object may be dormant or active.

This routine may only be called by an administrative user.

Syntax:

HRESULT GetDormantCollectionObjects(

[in] CollectionType Direction, 

[in] long ObjectID, 

[in, optional] BSTR RelationshipGUID, 

[in, optional, defaultvalue(0)] long RelationshipID, 

[in, optional] BSTR NamePattern, 

[in, optional] IMetaFilterList *Filters, 

[in, optional] IMetaInfoKeyList *SortKeys, 

[in, optional, defaultvalue(0)] long ReturnClass, 

[in, optional, defaultvalue(0)] VARIANT_BOOL AllClasses, 

[in, optional, defaultvalue(0)] VARIANT_BOOL SkipValidation, 

[out, retval] IMetaInfoList **InfoList);

GetCollectionVersionsByProperty2

Purpose:

This routine is used to search the repository for the origin or destination collection of the relationship of the object.

Description:

Identical to the GetCollectionsByProperty2 routine except for the addition of the LabelName parameter. In repositories with versioning enabled, it returns the collection class associated with a version of this object (given by ObjectID) for the specified relationship, which match the selection criteria, unless a label is specified. If a label is specified with the LabelName parameter, then it acts as an additional filter.

Syntax:

GetCollectionVersionsByProperty2(

[in] CollectionType Direction,

[in] long ObjectID,

[in, optional] BSTR RelationshipGUID,

[in, optional] long RelationshipID,

[in, optional] BSTR NamePattern,

[in, optional] IMetaFilterList *Filters,

[in, optional] IMetaInfoKeyList *SortKeys,

[in, optional, defaultvalue(0)] long ReturnClass,

[in, optional, defaultvalue(0)] VARIANT_BOOL AllClasses,

[in, optional, defaultvalue(0)] VARIANT_BOOL SkipValidation,

[in, optional] BSTR Label,

[out, retval] IMetaInfoList **InfoList);

GetCollectionVersionsByProperty3

Purpose:

This routine is used to search the repository for the origin or destination collection of the relationship of the object.

Description:

Identical to the GetCollectionVersionsByProperty2 routine except that the ColumnFilter parameter allows the caller to specify which properties are to be returned by the implementation.

Refer to “ColumnFilter” on page 305 for additional information

Note: If there are subclasses in the collection, the PIDs specified in the ColumnFilter must exist in all those classes. Effectively this means that the PIDs must be from the top-most class. The engine will return a property-not-found error otherwise.

Syntax:

GetCollectionVersionsByProperty3(

[in] CollectionType Direction,

[in] long ObjectID,

[in, optional] BSTR RelationshipGUID,

[in, optional] long RelationshipID,

[in, optional] BSTR NamePattern,

[in, optional] IMetaFilterList *Filters,

[in, optional] IMetaInfoKeyList *SortKeys,

[in, optional] IMetaInfoKeyList *ColumnFilter,

[in, optional, defaultvalue(0)] long ReturnClass,

[in, optional, defaultvalue(0)] VARIANT_BOOL AllClasses,

[in, optional, defaultvalue(0)] VARIANT_BOOL SkipValidation,

[in, optional] BSTR Label,

[out, retval] IMetaInfoList **InfoList);

GetRelationExplanation

Purpose:

Use this method to return the Explanation property for a particular pair of associated objects.

Description:

The GetRelationExplanation call returns the Explanation for the object-association given by the OrigID and DestID pair, for the indicated Relationship, identified by the Relationship GUID or ID. 

Requirements:

The object association must already exist. Therefore, the DestID object must already be in the destination collection of the OrigID object for the relationship.

Syntax:

HRESULT GetRelationExplanation(

[in] long OrigID, 

[in] long DestID,

[in] BSTR RelationshipGUID, 

[in, optional] long RelationshipID, 

[out, retval] BSTR *Explanation);

SetRelationExplanation

Purpose:

Use this method to set the Explanation property for a particular pair of associated objects.

Description:

The SetRelationExplanation call sets the Explanation for the object-association given by the OrigID and DestID pair, for the indicated Relationship, identified by the Relationship GUID or ID. 

Requirements:

The object association must already exist. Therefore, the DestID object must already be in the destination collection of the OrigID object for the relationship.

Syntax:

HRESULT SetRelationExplanation(

[in] long OrigID, 

[in] long DestID,

[in] BSTR RelationshipGUID, 

[in, optional] long RelationshipID, 

[in] BSTR Explanation);

BeginTransaction

Purpose:

Use this method to start an explicit MDS transaction.

Syntax:

HRESULT BeginTransaction();

RollbackTransaction

Purpose:

Use this method to rollback the explicit MDS transaction.

Syntax:

HRESULT RollbackTransaction();

CommitTransaction

Purpose:

Use this method to commit the explicit MDS transaction.

Syntax:

HRESULT CommitTransaction();

GetMDSUsers

Purpose:

Use this method to return a collection of all the users currently in the MDS repository, as IMetaUserInfo objects.

Syntax:

HRESULT GetMDSUsers(

[out, retval] IMetaUserInfoList ** UserList);

put_MDSCaller

Purpose:

Use this method to set the MDSCaller for the MetaActive object.

Description

This can be used to specify a specific MDS user for the object which will then be used for all subsequent calls from the object, including the SignOff call. This allows for MetaActive objects to be used for repository access, which are different from the object where the original sign-on occurred. Note that this is not needed for a single-user MDS application, since only one MDS user is signed on the Repository, and the MDS engine is aware of who that user is (the one specified at SignOn or Initialize).

This property is only useful for a multi-user (and possibly multi-threaded) MDS application.

Syntax:

HRESULT put_MDSCaller(

[in] BSTR MDSCallerName);

get_MDSCaller

Purpose:

Use this method to get the MDSCaller for the MetaActive object.

Description

This can be used to specify a specific MDS user for the object which will then be used for all subsequent calls from the object, including the SignOff call. This allows for MetaActive objects to be used for repository access, which are different from the object where the original sign-on occurred. Note that this is not needed for a single-user MDS application, since only one MDS user is signed on the Repository, and the MDS engine is aware of who that user is (the one specified at SignOn or Initialize).

This property is only useful for a multi-user (and possibly multi-threaded) MDS application.

Syntax:

HRESULT get_MDSCaller(

([out, retval] BSTR* MDSCallerName);

SuperUserLogon

Purpose:

Use this method to determine if the MDS user specified in the UserName parameter is an MDS super-user.

Description

This method returns VARIANT_TRUE (true) if the user named in “UserName” is an MDS super-user (administrator), else it returns VARIANT_FALSE (false).

Requirements:

The User identified in UserName must be currently logged in from the running process, else the return will be VARIANT_FALSE in all cases.

Syntax:

HRESULT SuperUserLogon([in] BSTR UserName,

	[out, retval] VARIANT_BOOL *pVal);

EnableRetainBIZInfo

Purpose:

Use this method to set the value of the retain-business-objects feature for the repository.

Description:

When this feature is enabled, objects in the appropriate DIM classes, which have business information associated with them, are *not* removed from the repository when they are deleted, they are instead marked with a publish state of "dormant".

These dormant objects can later be returned to the "active" state if the DIM objects they were previously associated with are re-loaded back into the appropriate DIM class, with their (previous) business information re-associated with them. With the feature enabled, this behavior is automatically done by the MDS engine. These types of objects are not normally accessible but can be managed by the various calls for dormant objects from this interface.

There is no effect if the method is called with Enable set to "true" and the feature is currently enabled, or with Enabled set to "false" and the feature is currently disabled.

When called with Enabled set to "false", not only will the feature be disabled, but *all* objects currently in the "dormant" state, if any, will finally be removed from the repository. This amounts to a final clean-up from the previous delete of these objects.

Syntax:

HRESULT EnableRetainBIZInfo(

[in, defaultvalue(VARIANT_TRUE)] VARIANT_BOOL Enable);

UsingRetainBIZInfo

Purpose:

This routine returns the current repository setting for the support of the retain-business-objects feature: VARIANT_TRUE (true) if the repository supports the feature, and VARIANT_FALSE (false) if not.

Syntax:

HRESULT UsingRetainBIZInfo(

[out, retval] VARIANT_BOOL* value);