MTS Administrative Reference
Archived content. No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
The Microsoft® Transaction Server (MTS) Administrative reference provides object and method information for Microsoft® Visual Basic® or Microsoft Visual Basic Scripting Edition (VBScript) programmers, and interface and function information for Microsoft Visual C++® programmers. In addition, this technical reference provides a detailed description of the collections used by the administration objects.
This section contains the following sections:
Using MTS Administration Objects
Using MTS Collection Types
Automating MTS Administration With Visual Basic
MTS Administration Object Methods
Automating MTS Administration With Visual C++
On This Page
See Also
Automating MTS Administration With Visual Basic
Using MTS Administration Objects
MTS Catalog Object
MTS CatalogObject Object
MTS CatalogCollection Object
MTS PackageUtil Object
MTS ComponentUtil Object
MTS RemoteComponentUtil Object
MTS RoleAssociationUtil Object
Using MTS Collection Types
MTS LocalComputer Collection
MTS ComputerList Collection
MTS Packages Collection
MTS ComponentsInPackage Collection
MTS RemoteComponents Collection
MTS InterfacesForComponent and InterfacesForRemoteComponent Collections
MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections
MTS MethodsForInterface Collection
MTS RolesInPackage Collection
MTS UsersInRole Collection
MTS ErrorInfo Collection
MTS PropertyInfo Collection
MTS RelatedCollectionInfo Collection
MTS Visual Basic Error Codes
MTS Administration Object Methods
Add Method (CatalogCollection)
AddEnabled Property (CatalogCollection)
AssociateRole Method (RoleAssociationUtil)
AssociateRoleByName Method (RoleAssociationUtil)
Connect Method (Catalog)
Count Property (CatalogCollection)
DataStoreMajorVersion Property (CatalogCollection)
DataStoreMinorVersion Property (CatalogCollection)
ExportPackage Method (PackageUtil)
GetCLSIDs Method(ComponentUtil)
GetCollection Method (Catalog)
GetCollection Method (CatalogCollection)
GetUtilInterface Method (CatalogCollection)
ImportComponent Method (ComponentUtil)
ImportComponentByName Method (ComponentUtil)
InstallComponent Method (ComponentUtil)
InstallPackage Method (PackageUtil)
InstallRemoteComponent Method (RemoteComponentUtil)
InstallRemoteComponentByName Method (RemoteComponentUtil)
IsPropertyReadOnly Property (CatalogObject)
IsPropertyWriteOnly Property (CatalogObject)
Item Property (CatalogCollection)
Key Property (CatalogObject)
MajorVersion Property (Catalog)
MinorVersion Property (Catalog)
Name Property (CatalogObject)
Name Property (CatalogCollection)
Populate Method (CatalogCollection)
PopulateByKey Method (CatalogCollection)
Remove Method (CatalogCollection)
RemoveEnabled Property (CatalogCollection)
SaveChanges Method (CatalogCollection)
ShutdownPackage Method (PackageUtil)
Valid Property (CatalogObject)
Value Property (CatalogObject)
Automating MTS Administration With Visual C++
MTS Visual C++ Error Codes
MTS ICatalog Interface
ICatalog::GetCollection
ICatalog::Connect
ICatalog::get_MajorVersion
ICatalog::get_MinorVersion
MTS ICatalogCollection Interface
ICatalogCollection::get_NewEnum
ICatalogCollection::get_Item
ICatalogCollection::get_Count
ICatalogCollection::Add
ICatalogCollection::Populate
ICatalogCollection::SaveChanges
ICatalogCollection::GetCollection
ICatalogCollection::get_Name
ICatalogCollection::get_AddEnabled
ICatalogCollection::Remove
ICatalogCollection::get_RemoveEnabled
ICatalogCollection::GetUtilInterface
ICatalogCollection::get_DataStoreMajorVersion
ICatalogCollection::get_DataStoreMinorVersion
ICatalogCollection::PopulateByKey
MTS ICatalogObject Interface
ICatalogObject::get_Value
ICatalogObject::put_Value
ICatalogObject::get_Key
ICatalogObject::get_Name
ICatalogObject::IsPropertyReadOnly
ICatalogObject::IsPropertyWriteOnly
ICatalogObject::get_Valid
MTS IPackageUtil Interface
IPackageUtil::InstallPackage
IPackageUtil::ExportPackage
IPackageUtil::ShutdownPackage
MTS IComponentUtil Interface
IComponentUtil::InstallComponent
IComponentUtil::ImportComponent
IComponentUtil::ImportComponentByName
IComponentUtil::GetCLSIDs
MTS IRemoteComponentUtil Interface
IRemoteComponentUtil::InstallRemoteComponent
IRemoteComponentUtil::InstallRemoteComponentByName
MTS IRoleAssociationUtil Interface
IRoleAssociationUtil::AssociateRole
IRoleAssociationUtil::AssociateRoleByName
See Also
Automating MTS Administration
Automating MTS Administration With Visual Basic
This reference topic provides guidance for Microsoft® Visual Basic® or Microsoft Visual Basic Scripting Edition (VBScript) programmers who want to use the administration objects to automate tasks that an administrator performs using the Microsoft Transaction Server (MTS) Explorer. The MTS Visual Basic reference contains the following topics:
MTS Visual Basic Error Codes
MTS Administration Object Methods
See Also
Automating MTS Administration
Using MTS Administration Objects
Use the MTS administration objects to automate administration for MTS packages.
This section describes how the following administration objects are used:
MTS Catalog Object
MTS CatalogObject Object
MTS CatalogCollection Object
MTS PackageUtil Object
MTS ComponentUtil Object
MTS RemoteComponentUtil Object
MTS RoleAssociationUtil Object
MTS Catalog Object
The Catalog object enables you to connect to an MTS catalog and access collections. This general administration object supports the following methods.
Method |
Description |
---|---|
|
|
GetCollection |
Gets a collection on the catalog without reading any objects from the catalog. |
Connect |
Connects to a remote catalog and returns a root collection. |
MajorVersion |
Returns the major version number of the catalog. |
MinorVersion |
Returns the minor version number of the catalog. |
See Also
MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object
MTS CatalogObject Object
The CatalogObject object allows you to get and set object properties. This general administration interface supports the following methods.
Method |
Description |
---|---|
|
|
Value |
Gets and sets a property value |
Key |
Gets the value of the key property |
Name |
Gets the name of the object |
IsPropertyReadOnly |
True if the property cannot be set |
IsPropertyWriteOnly |
True if the property only supports set |
Valid |
True if all properties were successfully read from the catalog data store |
See Also
MTS Catalog Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object
MTS CatalogCollection Object
Use the CatalogCollection object to enumerate, add, delete, and modify catalog objects and to access related collections This general administration interface supports the following methods.
Method |
Description |
---|---|
|
|
Item |
Returns an object by index. The index is zero-based. |
Count |
Returns number of objects in the collection. |
Remove |
Removes an item according to its index position. |
Add |
Adds an object to the collection. |
Populate |
Reads all the collection objects from the catalog data store. |
SaveChanges |
Saves changes made to the collection into the catalog data store. |
GetCollection |
Gets a collection related to a specific object. |
Name |
Gets the name of a collection. |
AddEnabled |
Returns true if the Add method is enabled. |
RemoveEnabled |
Returns true if the Remove method is enabled. |
GetUtilInterface |
Gets the utility interface for the collection. |
PopulateByKey |
Reads the selected collection objects from the catalog data store. |
DataStoreMajorVersion |
Returns the major version number of the catalog data store. |
DataStoreMinorVersion |
Returns the minor version number of the catalog data store. |
See Also
Add Method (CatalogCollection), Remove Method (CatalogCollection), MTS Catalog Object, MTS CatalogObject Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object
MTS PackageUtil Object
The PackageUtil object enables installing and exporting a package. Instantiate this object by calling GetUtilInterface on a Packages collection.
This utility administration interface supports the following methods:
Method |
Description |
---|---|
|
|
InstallPackage |
Installs a pre-built package. |
ExportPackage |
Exports a package. |
ShutdownPackage |
Shuts down a package, thereby terminating that server process. |
See Also
MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object
MTS ComponentUtil Object
Call the ComponentUtil object to install a component in a specific collection and import components registered as in-process servers. Create this object by calling GetUtilInterface on a ComponentsInPackage collection. This utility administrationinterface supports the following methods.
Method |
Description |
---|---|
|
|
InstallComponent |
Installs a component from a DLL. |
ImportComponent |
Imports a component that is already registered as an in-process server. Supply the CLSID of the component. |
ImportComponentByName |
Imports a component that is already registered as an in-process server. Supply the ProgID of the component. |
GetCLSIDS |
Returns an array of installable CLSIDs in the DLL/type library. Note that changes are not made to the data store. |
See Also
MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS RemoteComponentUtil Object, MTS RoleAssociationUtil Object
MTS RemoteComponentUtil Object
Using the RemoteComponentUtil object, you can program your application to pull remote components from a package on a remote server. Instantiate this object by calling GetUtilInterface on a RemoteComponents collection. This utility administration interface supports the following methods.
Method |
Description |
---|---|
|
|
InstallRemoteComponent |
Pulls remote components from a package on a remote server. Supply the package ID and CLSID. |
InstallRemoteComponentByName |
Pulls remote components from a package on a remote server. Supply the package name and ProgID. |
See Also
GetUtilInterface Method (CatalogCollection), MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RoleAssociationUtil Object
MTS RoleAssociationUtil Object
Call methods on the RoleAssociationUtil object to associate roles with a component or interface. Create this object by calling the GetUtilInterface method on a RolesForPackageComponent or RolesForPackageComponentInterface collection. This utility administration interface supports the following methods.
Method |
Description |
---|---|
|
|
AssociateRole |
Associates the role by role ID with the component or interface. |
AssociateRoleByName |
Associates the role by role name with the component or interface. |
See Also
GetUtilInterface Method (CatalogCollection), MTS Catalog Object, MTS CatalogObject Object, MTS CatalogCollection Object, MTS PackageUtil Object, MTS ComponentUtil Object, MTS RemoteComponentUtil Object
Using MTS Collection Types
This topic describes the collections and collection properties supported by the MTS catalog. Additional collections and properties may be added in future versions. Use the DataStoreMajorVersion and DataStoreMinorVersion properties of a collection to distinguish between catalog versions.
The MTS catalog data store supports the following collection types:
MTS LocalComputer Collection
MTS ComputerList Collection
MTS Packages Collection
MTS ComponentsInPackage Collection
MTS RemoteComponents Collection
MTS InterfacesForComponent and InterfacesForRemoteComponent Collections
MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections
MTS MethodsForInterface Collection
MTS RolesInPackage Collection
MTS UsersInRole Collection
MTS ErrorInfo Collection
MTS PropertyInfo Collection
MTS RelatedCollectionInfo Collection
MTS LocalComputer Collection
The LocalComputer contains a single object that corresponds to the computer whose catalog that you are accessing. If you call the Connect method on the Catalog object, the LocalComputer collection contains information about the computer whose catalog you are accessing. This collection does not support the Add, Remove or GetUtilInterface methods.
The following table provides a list of the properties supported by the LocalComputer collection.
Property |
Description |
---|---|
|
|
Name |
"My Computer". |
Description |
Description of the computer. |
Transaction Timeout |
The transaction timeout setting in seconds. |
RemoteComponent InstallPath |
The path in which remote component files will be installed when remote components are configured |
PackageInstall Path |
The default path in which component files will be installed when pre-built packages are installed. |
ResourcePooling Enabled |
"Y" enables resource pooling. "N" disables resource pooling. Note that resource pooling is currently only supported by the ODBC resource dispenser. |
ReplicationShare |
When replicating the MTS catalog, the name of a share that the target system should use to access installed packages. |
RemoteServer Name |
The computer name to be generated when you use the MTS Explorer to create a client executable. If this string is blank or empty, the physical computer name of the exporting computer is used. If you put the name of the remote server as the string, the application executable generated by the MTS Explorer points to that remote server name. |
See Also
RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS ComputerList Collection
The ComputerList collection provides access to the list of computers shown in the MTS Explorer Computers folder. This collection supports the Add and Remove methods. This collection does not support the GetUtilInterface method.
The following table provides a list of the properties supported by the ComputerList collection.
Property |
Description |
---|---|
|
|
Name |
The name of the computer. |
See Also
RelatedCollectionInfo, PropertyInfo, ErrorInfo, Add Method (CatalogCollection), Remove Method (CatalogCollection)
MTS Packages Collection
As the top-level collection managed by the MTS Explorer, the Packages collection contains the packages installed on the local machine running MTS. Packages contain a set of components that run in the same server process, and define declarative security constructs that determine access to components at run time. The Packages collection supports the Add method and Remove method on the CatalogCollection object. In addition, the GetUtilInterface method of this collection returns a PackageUtil object which can be used to install and export packages.
The following table provides a list of the properties supported by the CatalogObject objects within the Packages collection.
Property |
Description |
---|---|
|
|
Name |
Name of the package. |
ID |
A universally unique identifier (UUID) for the package. |
Description |
Describes the package. Description fields hold a maximum of 500 characters. |
IsSystem |
Identifies an MTS system package. "N" signifies that the package is not a Transaction Server system package, and "Y" indicates that package is an MTS system package. |
Authentication |
Sets authentication level for calls. Possible values are 0 through 6, which correspond to the Remote Procedure Call (RPC) authentication settings. |
ShutdownAfter |
Sets the delay before shutting down a server process after it becomes idle. Shutdown latency ranges from 0 to 1440 minutes. |
RunForever |
Enables a server process to continue if a package is idle. If value is set to "Y", the server process will not shut down when left idle. If set to "N", the process will shut down according the value set by the ShutDownAfter property. |
SecurityEnabled |
Checks the security credentials of any client that calls the package if value is set to "Y." |
Identity |
Sets the server process identity for the package. Specify a valid Windows NT user account or "Interactive User" to have the package assume the identity of the current logged-on user. |
Password |
Sets the password used by the server process to log on under the identity above. |
Activation |
Sets the package level activation property to either "Local" or "Inproc". The Local setting determines that objects within the package will run within a dedicated local server process. A package running under the Local activation setting is a "server package". The Inproc activation setting means objects run in their creator's process. A package running under the Inproc activation setting is a "library package" |
Changeable |
Sets whether changes to the package settings, or those of its components, are allowed (either programmatically, or through the MTS UI). |
|
Data Type: String |
Deleteable |
Sets whether the package or its components can be deleted (either programmatically, or through the MTS UI). |
CreatedBy |
Informational string to describe the package creator. |
See Also
ComponentsInPackage, RolesInPackage, RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS ComponentsInPackage Collection
The ComponentsInPackage collection contains the set of components that run in the same server process and compose a package. This collection supports the Remove method. The Add method is not supported. You must use the ComponentUtil object to install components into the package.
The following table provides a list of the properties supported by the CatalogObjects within the ComponentsInPackage collection.
Property |
Description |
---|---|
|
|
ProgID |
The name that identifies the component. |
CLSID |
The universally unique identifier (UUID) for the component. |
Transaction |
Determines how a component supports transactions. Must be one of the following transaction settings: |
Description |
Describes the component. Description fields hold a maximum of 500 characters. |
PackageID |
Defines the identity of the owning package. |
PackageName |
Defines the name of the owning package. |
ThreadingModel |
Determines how instances of the component are assigned to threads for method execution. Possible values are those supported by Component Object Model (COM). |
SecurityEnabled |
Checks the security credentials of any client that calls the component if value is set to "Y." |
DLL |
Displays the name of the DLL containing the component implementation. |
IsSystem |
Identifies an MTS system component. "N" signifies that the package is not a Transaction Server system component, and "Y" indicates that package is an MTS system component. |
See Also
InterfacesForComponent, RolesForPackageComponent, RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS RemoteComponents Collection
Use the Microsoft Transaction Server (MTS) Explorer on a client computer to add remote component entries that see components installed on a remote server. This is often described as "pulling" remote component information from a server. Configuring remote components automatically copies proxy/stub DLLs and type libraries from the server to the client. The RemoteComponents collection supports the Remove method. This collection does not support the Add method on the CatalogCollection object. Instead you must call GetUtilInterface to obtain the RemoteComponentUtil object in order to add new remote components.
The following table provides a list of the properties supported by the CatalogObjects within the RemoteComponents collection.
Property |
Description |
---|---|
|
|
ProgID |
The name that identifies the remote component. |
CLSID |
The universally unique identifier (UUID) for the component. |
Description |
Describes the remote component. Description fields hold a maximum of 500 characters. |
Server |
Name of the server hosting the remote component. |
See Also
InterfacesForRemoteComponent, RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS InterfacesForComponent and InterfacesForRemoteComponent Collections
The InterfacesForComponent and InterfacesForRemoteComponent collections provide information about a selected interface. InterfacesForComponent or InterfacesForRemoteComponent collections are listed for each component, and can be used by an administrator to identify or manage the interface. These collections do not support the Add, Remove, or GetUtilInterface methods.
The following table provides a list of the properties supported by the CatalogObjects within the InterfacesForComponent and the InterfacesForRemoteComponent collections.
Property |
Description |
---|---|
|
|
Name |
Displays the friendly name of the interface. |
ID |
Displays the unique interface identifier (IID). |
Description |
Describes the interface. Description fields hold a maximum of 500 characters. |
ProxyCLSID |
Displays the CLSID of the proxy/stub. |
ProxyDLL |
Displays the file name of the proxy/stub DLL. |
ProxyThreadingModel |
Displays the threading model of the selected proxy/stub. |
TypeLibID |
Displays the UUID of the type library. |
TypeLibVersion |
Displays the version of the type library. |
TypeLibLangID |
Displays the language identification number of the type library. |
TypeLibPlatform |
Displays the platform of the type library. |
TypeLibFile |
Displays the file name of the type library. |
See Also
MethodsForInterface (InterfacesForComponent only), RolesForPackageComponentInterface (InterfacesForComponent only), RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections
The RoleForPackageComponent and RolesForPackageComponentInterface collections contain the roles associated with a component or interface. You add existing roles to these collections from a package's RolesInPackage collection. The Add method is not supported by this collection. Use the RoleAssociationUtil methods to add roles to this collection. The CatalogCollection Remove method is supported by this collection.
The following table provides a list of the properties supported by the CatalogObject(s) within the RolesForPackageComponent and the RolesForPackageComponentInterface collections.
Property |
Description |
---|---|
|
|
Name |
Displays the name of the role associated with a component. |
ID |
Displays the universally unique identifier (UUID) of the role. |
Description |
Describes the role. Description fields hold a maximum of 500 characters. |
See Also
RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS MethodsForInterface Collection
The MethodsForInterface collection contains the methods defined in an interface. Method properties are used to display information about the methods exposed by an interface. This collection does not support the Add, Remove, or GetUtilInterface methods.
The following table provides a list of the properties supported by the CatalogObjects within the MethodsForInterface collection.
Property |
Description |
---|---|
|
|
Name |
Displays the name of a method. |
Description |
Describes the method. Description fields hold a maximum of 500 characters. |
See Also
RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS RolesInPackage Collection
The RolesInPackage collection defines a class of users for a set of components in a package. Each role defines a set of users allowed to invoke interfaces on a component. Roles can be applied to both components and component interfaces. This collection supports the Add and Remove methods. This collection does not support the GetUtilInterface method.
The following table provides a list of the properties supported by the CatalogObjects within the RolesInPackage collection.
Property |
Description |
---|---|
|
|
Name |
The role name. |
ID |
The universally unique identifier (UUID) for the role. |
Description |
Describes the new Role. Description fields hold a maximum of 500 characters. |
See Also
UsersInRole, RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS UsersInRole Collection
The UsersInRole collection lists the members of the class of users that have been authorized to invoke methods on the component or component interface associated with the role. This collection supports the Add and Remove methods. This collection does not support the GetUtilInterface method.
The following table provides a list of the properties supported by the CatalogObjects within the UsersInRole collection.
Property |
Description |
---|---|
|
|
User |
The name of an NT user account or group. |
See Also
RelatedCollectionInfo, PropertyInfo, ErrorInfo
MTS ErrorInfo Collection
The ErrorInfo collection is used to retrieve extended error information about methods that deal with multiple objects. This collection does not support the Add, Remove, or GetUtilInterface methods. Use the GetCollection method on a collection to access the ErrorInfo collection associated with the original collection. The ErrorInfo collection is accessible from any collection except ErrorInfo, RelatedCollectionInfo, and PropertyInfo. When calling methods on a utility object, extended error information may be created in the ErrorInfo collection associated with the collection used to create the utility object.
The following table provides a list of the properties supported by the CatalogObjects within the ErrorInfo collection.
Property |
Description |
---|---|
|
|
Name |
Name of the object or file. |
ErrorCode |
Error code for the object or file. |
See Also
MTS LocalComputer Collection, MTS ComputerList Collection, MTS Packages Collection, MTS ComponentsInPackage Collection, MTS RemoteComponents Collection, MTS InterfacesForComponent and InterfacesForRemoteComponent Collections, MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections, MTS MethodsForInterface Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, MTS PropertyInfo Collection, MTS RelatedCollectionInfo Collection
MTS PropertyInfo Collection
The PropertyInfo collection is used to retrieve information about the properties that a specified collection supports. This collection does not support the Add, Remove, or GetUtilInterface methods. The PropertyInfo collection is accessible from any collection by using the GetCollection method.
The following table provides a list of the properties supported by the CatalogObject(s) within the PropertyInfo collection.
Property |
Description |
---|---|
|
|
Name |
Name of the property. |
See Also
MTS LocalComputer Collection, MTS ComputerList Collection, MTS Packages Collection, MTS ComponentsInPackage Collection, MTS RemoteComponents Collection, MTS InterfacesForComponent and InterfacesForRemoteComponent Collections, MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections, MTS MethodsForInterface Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, MTS ErrorInfo Collection, MTS RelatedCollectionInfo Collection
MTS RelatedCollectionInfo Collection
The RelatedCollectionInfo collection is used to retrieve information about other collections related to the collection from which this collection is called. The RelatedCollectionInfo collection is accessible from any collection by using the GetCollection method. The RelatedCollectionInfo collection will contain one object for each collection that is accessible from the original collection. Related collections follow the MTS Explorer folder hierarchy. This collection does not support the Add, Remove, or GetUtilInterface methods.
The following table provides a list of the properties supported by the CatalogObjects within the RelatedCollectionInfo collection.
Property |
Description |
---|---|
|
|
Name |
Name of the related collection. |
See Also
MTS LocalComputer Collection, MTS ComputerList Collection, MTS Packages Collection, MTS ComponentsInPackage Collection, MTS RemoteComponents Collection, MTS InterfacesForComponent and InterfacesForRemoteComponent Collections, MTS RolesForPackageComponent and RolesForPackageComponentInterface Collections, MTS MethodsForInterface Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, MTS ErrorInfo Collection, MTS PropertyInfo Collection
MTS Visual Basic Error Codes
The following table lists the error codes returned by methods called on the MTS catalog collection and catalog utility objects.
Error code |
Description |
---|---|
|
|
Visual Basic run-time error 5 |
Indicates one of the following: |
Visual Basic run-time error 445 |
Object has been removed from the collection or the method is not supported on this object. |
mtsErrObjectErrors |
Errors were encountered processing some objects or file. See the ErrorInfo collection for object and file-specific error codes. |
mtsErrNoUser |
User ID for user in role is not valid. |
MtsErrUserPasswdNotValid |
Package identity user ID and/or password are not valid. |
MtsErrAuthenicationLevel |
Required authentication level (package privacy) could not be set for package updates. |
mtsErrPDFReadFail |
An error occurred reading the package file. |
MtsErrPDFVersion |
Package file version is invalid. |
MtsErrBadPath |
Package file path is invalid. |
MtsErrPackageExists |
Package with the same ID is already installed. |
MtsErrRoleExists |
A role with the same ID is already installed. The role ID in the package file is likely corrupted. |
MtsErrCantCopyFile |
Errors occurred copying one or more files to the install directory. |
mtsErrInvalidUserids |
One or more user IDS for roles were invalid. |
MtsErrCLSIDOrIIDMismatch |
One or more component or interface identifiers in a component DLL do not match the identifiers saved in the package file. The package file is out of date. |
MtsErrPackDirNotFound |
Package install directory is invalid due to general registry read/write errors. |
MtsErrPDFWriteFail |
An error occurred writing the package file. |
mtsErrNoTypeLib |
Could not find the type library for one or more components. |
The following table lists the object or file-specific error codes returned in ErrorInfo collections.
Error code |
Description |
---|---|
|
|
mtsErrObjectInvalid |
One or more object properties is corrupted or invalid. |
mtsErrKeyMissing |
One or more objects is not found in the catalog data store. |
mtsErrAlreadyInstalled |
Component is already installed. |
mtsErrDownloadFailed |
One or more component files could not be copied to the client. |
mtsErrRemoteInterface |
No interface information is available for the component. Component files could not be downloaded. |
mtsErrCoReqCompInstalled |
Component in the same DLL file is already installed. |
mtsErrNoRegistryCLSID |
Component's CLSID is corrupted. |
mtsErrBadRegistryProgID |
Component's ProgID is corrupted. |
mtsErrDllLoadFailed |
Component's DLL could not be loaded. |
mtsErrDllRegisterServer |
DllRegisterServer method failed during component self-registration. |
mtsErrNoServerShare |
No file share is available on the server to copy component files from the network path. |
mtsErrNoAccessToUNC |
Network path registered for this component could not be accessed. |
mtsErrBadRegistryLibID |
Component type library ID is corrupted. |
mtsErrTreatAs |
Component TreatAs key was found, but is not supported. |
mtsErrBadForward |
IID forward entry is corrupted. |
mtsErrBadIID |
IID is corrupted. |
mtsErrRegistrarFailed |
Component registrar method failed during component install. |
mtsErrCompFileDoesNotExist |
Component file does not exist. |
mtsErrCompFileLoadDLLFail |
DLL file could not be loaded. |
mtsErrCompFileGetClassObj |
DllGetClassObject function call failed during the DLL self-registration process. |
mtsErrCompFileClassNotAvail |
Class coded in the type library was not supported. |
mtsErrCompFileBadTLB |
Type library was corrupted. |
mtsErrCompFileNotInstallable |
File does not contain COM components or type library information. |
mtsErrNotChangeable |
Changes to this object and sub-objects have been disabled. |
mtsErrNotDeletable |
Delete function for this object has been disabled. |
mtsErrSession |
Catalog version is not supported. |
The following tables lists general read and write registry errors.
Error Code |
Description |
---|---|
|
|
mtsErrNoRegistryRead |
Access control failure reading a registry key. |
mtsErrNoRegistryWrite |
Access control failure writing a registry key. |
mtsErrNoRegistryRepair |
Access control failure writing a registry key. |
MTS Administration Object Methods
The following topics list the methods of the MTS administration objects:
Add Method (CatalogCollection)
AddEnabled Property (CatalogCollection)
AssociateRole Method (RoleAssociationUtil)
AssociateRoleByName Method (RoleAssociationUtil)
Connect Method (Catalog)
Count Property (CatalogCollection)
DataStoreMajorVersion Property (CatalogCollection)
DataStoreMinorVersion Property (CatalogCollection)
ExportPackage Method (PackageUtil)
GetCLSIDs Method (ComponentUtil)
GetCollection Method (Catalog)
GetCollection Method (CatalogCollection)
GetUtilInterface Method (CatalogCollection)
ImportComponent Method (ComponentUtil)
ImportComponentByName Method (ComponentUtil)
InstallComponent Method (ComponentUtil)
InstallPackage Method (PackageUtil)
InstallRemoteComponent Method (RemoteComponentUtil)
InstallRemoteComponentByName Method (RemoteComponentUtil)
IsPropertyReadOnly Property (CatalogObject)
IsPropertyWriteOnly Property (CatalogObject)
Item Property (CatalogCollection)
Key Property (CatalogObject)
MajorVersion Property (Catalog)
MinorVersion Property (Catalog)
Name Property (CatalogObject)
Name Property (CatalogCollection)
Populate Method (CatalogCollection)
PopulateByKey Method (CatalogCollection)
Remove Method (CatalogCollection)
RemoveEnabled Property (CatalogCollection)
SaveChanges Method (CatalogCollection)
ShutdownPackage Method
Valid Property (CatalogObject)
Value Property (CatalogObject)
See the Automating MTS Administration topic for sample code that demonstrates how these methods are used to program administration using Microsoft® Visual Basic® or Microsoft Visual Basic Scripting Edition (VBScript).
Add Method (CatalogCollection)
Adds a member to a collection object and returns the CatalogObject object.
Syntax
object**.Add**
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
Remarks
Call the Add method to create a new object in a collection. This method is supported in the following collections:
Packages
RolesInPackage
UsersInRole
To install or create objects in other collections, use the catalog utility interfaces. Note that you must call the SaveChanges method to write the new object to the catalog data store.
For a list of the MTS collections and their properties, see Using MTS Collections.
See Also
MTS Packages Collection, MTS RolesInPackage Collection, MTS UsersInRole Collection, AddEnabled Property (CatalogCollection)
AddEnabled Property (CatalogCollection)
Returns a Boolean value indicating whether the Add method is enabled on this collection.
Syntax
object . AddEnabled
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
Remarks
If the value returned is True, then you can call the Add method to create a new object in a collection. If the value returned is False, you must use the catalog utility object methods to create a new object.
For a list of the MTS collections and their properties, see the Using MTS Collections topic.
See Also
Add Method (CatalogCollection)
AssociateRole Method (RoleAssociationUtil)
Associates a role with a component or component interface.
Syntax
object . AssociateRole( ID )
Parameters
object
Required. An object variable that evaluates to a RoleAssociationUtil object.
ID
Required. A String expression that specifies the role ID of the roles to associate with the object.
Remarks
The changes are applied immediately to the catalog.
For a list of properties supported by Role collections,see the Using MTS Collections topic.
See Also
AssociateRoleByName Method (RoleAssociationUtil)
AssociateRoleByName Method (RoleAssociationUtil)
The AssociateRoleByName method associates a role with a specified component or component interface.
Syntax
object . AssociateRoleByName( name )
Parameters
object
Required. An object variable that evaluates to a RoleAssociationUtil utility object.
name
Required; String. An expression providing the name of the role to associate with a component or component interface.
Remarks
The changes are applied immediately to the catalog. For a list of properties supported by Role collections,see the Using MTS Collections topic.
See Also
AssociateRole Method (RoleAssociationUtil)
Connect Method (Catalog)
Connects to a catalog and returns a root collection.
Syntax
set root object . Connect( name )
Parameters
root
Required. String containing the root collection that serves as a starting point to locate top-level collections.
Object
Required. An object variable that evaluates to a catalog object.
name
Required; String. String containing the name of a remote computer. To connect to a local computer, supply an empty string as this argument.
Remarks
The Connect method returns a root collection, which is bound to the connected computer. A root collection serves as a starting point to locate top-level collections, and does not contain any objects or properties.
Note that you can also use the GetCollection method to locate a package on the local computer without first having to call the Connect method.
You can get the following collections from the root collection:
Packages
RemoteComponents
RelatedCollectionInfo
ComputerList
LocalComputer
PropertyInfo
For a list of the MTS collections and their properties, see the Using MTS Collections topic.
See Also
GetCollection Method (CatalogCollection)
Count Property (CatalogCollection)
Returns an integer value indicating the number of objects in a collection.
Syntax
object . Count
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
Remarks
Upon instantiation, a CatalogCollection object returns a count of zero. Call the Populate method to read from the CatalogCollection object, and then use the Count method to return the number of objects in the collection.
for a list of the MTS collections and their properties, see the Using MTS Collections topic.
See Also
Populate Method (CatalogCollection)
DataStoreMajorVersion Property (CatalogCollection)
Returns an integer value indicating the major version number of the catalog.
Syntax
object . DataStoreMajorVersion
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
See Also
DataStoreMinorVersion Property (CatalogCollection)
DataStoreMinorVersion Property (CatalogCollection)
Returns an integer value indicating the minor version number of the catalog.
Syntax
object . DataStoreMajorVersion
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
See Also
DataStoreMajorVersion Property (CatalogCollection)
ExportPackage Method (PackageUtil)
Exports a package.
Syntax
object . ExportPackage( PackID, FileName, Options )
Parameters
object
Required. An object variable that evaluates to a PackageUtil object.
PackID
Required; String. An object variable that specifies the package ID of the package to export.
FileName
Required; String. An object variable that provides the name of the package file to export.
Options
Required; Long. An integer value specifying export options. This parameter can be 0 or MtsExportUsers, which includes users in roles in the package file.
GetCLSIDs Method(ComponentUtil)
Returns an array of installable class identifiers (CLSIDs) in the component DLL and/or type library.
Syntax
object . GetCLSIDs( bstrDLLFile, bstrTypeLibFile, aCLSIDs )
Parameters
BstrDLLFile
Required; String. A string variable that evaluates to the path of the DLL that you want checked.
BstrTypeLibFile
Required; String. A string variable that evaluates to the path of the type library that you want checked. If the type library is embedded with the DLL (as is the case with DLLs generated by Microsoft Visual Basic), this parameter should be an empty string).
aCLSIDS
Required; Variant. An output array of CLSIDs (VARIANTS) that can be installed from the supplied DLL and/or type library.
GetCollection Method (Catalog)
Instantiates a CatalogCollection object.
Syntax
set x object . GetCollection( Name )
Parameters
x
Required. An object variable (a variant, or object variable, or a CatalogCollection variable) for the returned collection.
object
Required. An object variable that evaluates to a catalog object.
Name
Required; String. A string expression containing the name of the collection to instantiate.
Remarks
You can use this method to get the following collections:
Packages
ComputerList
LocalComputer
RemoteComponents
RelatedCollectionInfo
After using the GetCollection method, you must fill the object by calling the Populate method. See the Populate method topic for further detail.
For a list of the MTS collections and their properties, see the Using MTS Collections topic..
GetCollection Method (CatalogCollection)
Retrieves a collection from the catalog.
Syntax
set x object . GetCollection( name, key )
Parameters
x
Required. An object variable (a variant, or object variable, or a CatalogCollection variable) for the returned collection.
object
Required. An object variable that evaluates to a CatalogCollection object.
name
Required. A String expression containing the name of the collection to instantiate.
key
Required. A Variant expression containing the key of the object from which to navigate.
Remarks
Note that the GetCollection method gets an empty collection; you must call the Populate method to fill the collection.
For a list of the MTS collections and their properties, see the Using MTS Collections topic.
See Also
Populate Method (CatalogCollection)
GetUtilInterface Method (CatalogCollection)
Instantiates a utility object for the collection.
Syntax
set util object . GetUtilInterface
Parameters
util
Required. An object variable that evaluates to a catalog utility object.
object
Required. An object variable that evaluates to a CatalogCollection object.
Remarks
Call the GetUtilInterface method to instantiate any one of the PackageUtil, ComponentUtil, RemoteComponentUtil, and RoleAssociationUtil utility objects. This method is only supported on Packages, ComponentsInPackage, RemoteComponents, RolesForPackageComponent, and RolesForPackageComponentInterface collections.
For a list of the MTS collections and their properties, see the Using MTS Collections topic.
ImportComponent Method (ComponentUtil)
Imports a component that is already registered as an in-process (in-proc) server.
Syntax
object . ImportComponent( CLSID )
Parameters
object
Required. An object variable that evaluates to a ComponentUtil object.
CLSID
Required; String. An expression containing the CLSID of the component to be installed.
Remarks
The changes are applied immediately to the catalog.
For a description of the Component collection and its associated properties, see the Using MTS Collections topic.
See Also
ImportComponentByName Method (ComponentUtil)
ImportComponentByName Method (ComponentUtil)
Imports a component that is already registered as an in-process server by the component's programmatic identifier (ProgID).
Syntax
object . ImportComponentByName( ProgID )
Parameters
object
Required. An object variable that evaluates to a ComponentUtil object.
ProgID
Required. A String expression identifying the ProgID of the component to be installed.
Remarks
The changes are applied immediately to the catalog. For a description of the Component collection and its associated properties, see the Using MTS Collections topic.
See Also
ImportComponent Method (ComponentUtil)
InstallComponent Method (ComponentUtil)
Installs a component into a package.
Syntax
object . InstallComponent( filepath, typelibrary, proxy-stub )
Parameters
object
Required. An object variable that evaluates to a ComponentUtil object.
filepath
Required. A String expression that provides the file path of the DLL containing the components to install.
typelibrary
Required. A String expression that provides the file path of the type library to use. Pass an empty string as this argument if the type library is embedded in the DLL.
proxy-stub
Required. A String expression that provides the file path of a custom proxy-stub DLL to use. Pass an empty string as this argument if there is no custom proxy-stub DLL.
Remarks
The changes are applied immediately to the catalog.
For a description of the Components collection and its associated properties, see the Using MTS Collections topic.
See Also
InstallRemoteComponent Method (RemoteComponentUtil), InstallRemoteComponentByName Method (RemoteComponentUtil)
InstallPackage Method (PackageUtil)
Installs a component or components that are valid within a package's collection.
Syntax
object . InstallPackage( FileName, InstallPath, options )
Parameters
object
Required. An object variable that evaluates to a Package utility object.
FileName
Required; String. String expression evaluating to the name of the package to install.
InstallPath
Required; String. String expression evaluating to the install path for component files.
options
Required; Long. A long value specifying install options. This parameter can be 0 or mtsInstallUsers, which adds users saved in the package file. If this option is not specified, users saved in the package file are not installed.
Remarks
All component files must be in the same directory of the package file. Component files arecopied to the install path specified as an argument of the InstallPackage method.
The changes are applied immediately to the catalog.
For a description of the Components collection and its associated properties, see the Using MTS Collections topic..
InstallRemoteComponent Method (RemoteComponentUtil)
Pulls remote components from a package on a remote server.
Syntax
object . InstallRemoteComponent( computer, PackID, CLSID )
Parameters
object
Required. An object variable that evaluates to a RemoteComponentUtil object.
computer
Required; String. A string expression providing the name of the remote computer.
PackID
Required; String. A string expression providing the package identification of the package containing the remote component.
CLSID
Required; String. A string expression containing the CLSID of the remote component.
Remarks
The changes are applied immediately to the catalog.
See the Working with Remote MTS Computers topic for a complete description of how to pull components from a remote server.
See Also
InstallRemoteComponentByName Method (RemoteComponentUtil)
InstallRemoteComponentByName Method (RemoteComponentUtil)
Pulls remote components by name from the package on a remote server.
Syntax
object . InstallRemoteComponentByName( computer, PackName, ProgID )
Parameters
object
Required. An object variable that evaluates to a RemoteComponentUtil object.
computer
Required; String. A string expression providing the name of the remote computer.
PackName
Required; String. A string expression providing the name of the package containing the remote component.
ProgID
Required; String. A string value containing the ProgID of the remote component.
Remarks
The changes are applied immediately to the catalog. See the Working with Remote MTS Computers topic for a complete description of how to pull components from a remote server.
See Also
InstallRemoteComponent Method (RemoteComponentUtil)
IsPropertyReadOnly Property (CatalogObject)
Returns a Boolean value that indicates if the property for an object is set to read-only.
Syntax
object . IsPropertyReadOnly( value )
Parameters
object
Required. An object variable that evaluates to a catalog object property.
value
Required. The name of the value for which to check the read-only property.
Remarks
If the value returned by the IsPropertyReadOnly method is True, then you cannot modify the property. If the value returned is False, you can modify the property using the Value property.
IsPropertyWriteOnly Property (CatalogObject)
Returns a Boolean value that indicates if the property for an object is set to write-only.
Syntax
object . IsPropertyWriteOnly( propertyname )
Parameters
object
Required. An object variable that evaluates to a catalog object property.
propertyname
Required. The name of the property for which to check the write-only status.
Remarks
If the value returned by the IsPropertyWriteOnly method is True, then you can write but not read the property value. If the value returned is False, you can read the property value.
See Also
IsPropertyReadOnly Property (CatalogObject)
Item Property (CatalogCollection)
Gets a specific object in a collection.
Syntax
object . Item( index )
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
index
Required; Long. A zero-based index that specifies the position of a member of the collection. Must be a number from 0 through the value of the collection's Count property -1.
Key Property (CatalogObject)
Gets the value of the key of the object.
Syntax
object . Key
Parameters
object
Required. An object variable that evaluates to a CatalogObject object.
Remarks
All catalog objects have a key. The object key is a single property that uniquely identifies the object. To access a related collection using the GetCollection method, provide the key of the object from which you want to navigate (such as the package identifier). The following table provides the key property for each collection supported:
Collection |
Key Property |
---|---|
|
|
Packages |
ID |
ComponentsInPackage |
CLSID |
RolesInPackage |
ID |
RolesForPackageComponent |
ID |
RolesForPackageComponentInterface |
ID |
UsersInRole |
User |
InterfacesForComponent |
IID |
InterfacesForRemoteComponent |
IID |
RemoteComponents |
CLSID |
MethodsForInterface |
Name |
MajorVersion Property (Catalog)
Returns an integer value indicating the major version number of the catalog.
Syntax
object . MajorVersion
Parameters
object
Required. An object variable that evaluates to a catalog object.
See Also
MinorVersion Property (Catalog)
MinorVersion Property (Catalog)
Returns an integer value indicating the minor version number of the catalog.
Syntax
object . MinorVersion
Parameters
object
Required. An object variable that evaluates to a catalog object.
See Also
MajorVersion Property (Catalog)
Name Property (CatalogObject)
Gets the name of an object.
Syntax
object . Name
Parameters
object
Required. An object variable that evaluates to a catalog object.
Remarks
All catalog objects have a name property. The following table provides the name property for each collection supported:
Collection |
Name Property |
---|---|
|
|
Packages |
Name |
ComponentsInPackage |
ProgID |
RolesInPackage |
Name |
RolesForPackageComponent |
Name |
RolesForPackageComponentInterface |
Name |
UsersInRole |
User |
InterfacesForComponent |
Name |
InterfacesForRemoteComponent |
Name |
RemoteComponents |
ProgID |
MethodsForInterface |
Name |
Name Property (CatalogCollection)
Gets the name of the collection.
Syntax
object . Name
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
Remarks
See the Using MTS Collections topic for a list of properties supported by each MTS collection.
Populate Method (CatalogCollection)
Fills a collection with objects from the catalog.
Syntax
object . Populate
Parameters
object
Required. An object variable that evaluates to the CatalogCollection object that you would like to fill.
Remarks
The Populate method reads the contents of the CatalogCollection object. Any changes that are still pending (such as property changes, objects added, or objects removed) are lost. See the SaveChanges method topic for instruction on how to preserve changes made to a CatalogCollection object.
PopulateByKey Method (CatalogCollection)
Populates the collection with information for the specified objects.
Syntax
object . PopulateByKey( aCLSIDs )
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
aCLSIDS
Required; Variant. An array of object keys (VARIANTS) denoting which objects should have their information read from the catalog.
Remove Method (CatalogCollection)
Removes an item from an object given the index position.
Syntax
object . Remove( index )
Parameters
object
Required; String. An object variable that evaluates to a CatalogCollection object.
index
Required; Long. A zero-based index indicating the position of the object to remove.
Remarks
The object is removed from the collection and all objects with higher indices are shifted up. Note that the Count property of a collection changes after the Remove method has been called.
Call the SaveChanges method to save the changes made to the collection using the Remove method.
RemoveEnabled Property (CatalogCollection)
Returns a Boolean value indicating that you can use the Remove method to delete an object from the collection.
Syntax
object . RemoveEnabled
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
Remarks
If the value returned is True, then you can call the Remove method to remove an object from the collection. If the value returned is False, objects cannot be removed from the collection.
SaveChanges Method (CatalogCollection)
Saves changes to a collection in the catalog, and returns an integer indicating the number of changes applied to the collection.
Syntax
object . SaveChanges
Parameters
object
Required. An object variable that evaluates to a CatalogCollection object.
Remarks
The SaveChanges method works exclusively on the collection on which you call it, and applies all pending changes to the catalog. If no changes are pending, then the method returns zero.
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ShutdownPackage Method (PackageUtil)
Initiates the shutting down of a package. Shutting down a package terminates that application's process.
Syntax
object . ShutdownPackage( bstrPackageID )
Parameters
object
Required. An object variable that evaluates to a PackageUtil object.
BstrPackageID
Required. A string variable that evaluates to the PackageID of a Package CatalogObject.
Remarks
The ShutdownPackage method shuts down a single package process.
See the Using MTS Collections topic for a list of the MTS collections and their properties.
Valid Property (CatalogObject)
Returns a Boolean value indicating whether all the object properties were successfully read from the catalog.
Syntax
object . Valid
Parameters
object
Required. An object variable that evaluates to a CatalogObject.
Remarks
If this property is False it indicates that one or more object properties could not be read from the catalog during a call to Populate. This property will be True for objects that have been added to the collection using the Add method.
Value Property (CatalogObject)
Gets or sets a value for an object property.
Syntax
object . Value( property ) value
Parameters
object
Required. An object variable that evaluates to a CatalogObject.
Property
Required. A String expression of any type that specifies the name of the property whose value to get or set.
Value
Required. A String expression that specifies the value of the property to get or set.
Remarks
See the Using MTS Collections topic for a description the properties supported by the MTS administration objects.
Automating MTS Administration With Visual C++
The topics in this section describe administration interfaces supported by Microsoft Transaction Server (MTS). This reference describes the following topics:
MTS Visual C++ Error Codes
ICatalog
ICatalogObject
ICatalogCollection
IPackageUtil
IComponentUtil
IRemoteComponentUtil
IRoleAssociationUtil
The ICatalog, ICatalogObject, and ICatalogCollection interfaces provide top-level functionality such as creating and modifying objects. The ICatalog interface enables you to connect to specific servers and access collections. Call the ICatalogCollection interface to enumerate, create, delete, and modify objects, as well as to access related collections. The ICatalogObject interface is used to get and set properties on an object.
The utility interfaces (IRemoteComponentUtil and IRoleAssociationUtil) allows you to program very specific tasks for collection types, such as associating a role with a user or class of users.
MTS Visual C++ Error Codes
The following is a list of the error codes returned by methods called on the catalog collection and catalog utility interfaces.
E_INVALIDARG
Indicates one of the following:
An invalid collection or property name was entered.
An out parameter was NULL.
The value is not one of the supported values or falls outside the supported range.
The property is read-only.
The property cannot be changed after the object is created.
An invalid index was entered.
E_NOTIMPL
Object has been removed from the collection and is not supported on this collection.
E_MTS_OBJECTERRORS
Errors were encountered processing some objects or file. See the ErrorInfo collection for object/file-specific error codes.
E_MTS_NOUSER
User ID for user in role is not valid.
E_MTS_USERPASSWDNOTVALID
Package identity user ID and/or password are not valid
E_MTS_AUTHENICATIONLEVEL
Required authentication level (package privacy) could not be set for package updates.
E_MTS_PDFREADFAIL
An error occurred reading the package file.
E_MTS_PDFVERSION
Package file version is invalid.
E_MTS_BADPATH
Package file path is invalid.
E_MTS_PACKAGEEXISTS
Package with the same ID is already installed.
E_MTS_ROLEEXISTS
A role with the same ID is already installed. The role ID in the package file is likely corrupted.
E_MTS_CANTCOPYFILE
Errors occurred copying one or more files to the install directory.
E_MTS_INVALIDUSERIDS
One or more user IDS for roles were invalid.
E_MTS_CLSIDORIIDMISMATCH
One or more component/interface identifiers in a component DLL does not match the identifiers saved in the package file. The package file is out of date.
E_MTS_PACKDIRNOTFOUND
Package install directory is invalid due to general registry read/write errors.
E_MTS_PDFWRITEFAIL
An error occurred writing the package file.
E_MTS_NOTYPELIB
Could not find the type library for one or more components.
The following is a list of the object or file-specific error codes returned in ErrorInfo collections:
E_OBJECTINVALID
One or more object properties is corrupted or invalid.
E_KEYMISSING
One or more objects is not found in the catalog.
E_ALREADYINSTALLED
Component is already installed.
E_DOWNLOADFAILLED
One or more component files could not be copied to the client.
E_REMOTEINTERFACE
No interface information is available for the component. Component files could not be downloaded.
E_COREQCOMPINSTALLED
Component in the same DLL file is already installed.
E_NOREGISTRYCLSID
Component's CLSID is corrupted.
E_BADREGISTRYPROGID
Component's ProgID is corrupted.
E_DLLLOADFAILED
Component's DLL could not be loaded.
E_DLLREGISTERSERVER
DllRegisterServer method failed during component self-registration.
E_NOSERVERSHARE
No file share is available on the server to copy component files from the network path.
E_NOACCESSTOUNC
Network path registered for this component could not be accessed.
E_BADREGISTRYLIBID
Component type library ID is corrupted.
E_TREATAS
Component TreatAs key was found, but is not supported.
E_BADFORWARD
IID forward entry is corrupted.
E_BADIID
IID is corrupted.
E_REGISTRARFAILED
Component registrarmethod failed during component install.
E_COMFILE_DOESNOTEXIST
Component file does not exist.
E_COMFILE_LOADDLLFAIL
DLL file could not be loaded.
E_COMFILE_GETCLASSOBJ
DllGetClassObject method call failed during the DLL self-registration process.
E_COMFILE_CLASSNOTAVAIL
Class coded in the type library was not supported.
E_COMFILE_BADTLB
Type library was corrupted.
E_COMFILE_NOTINSTALLABLE
File does not contain COM components or type library information.
The following is a list of general read and write registry errors:
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
E_MTS_NOTCHANGEABLE
Changes to this object and sub-objects have been disabled.
E_MTS_NOTDELETABLE
Delete function for this object has been disabled.
E_MTS_SESSION
Server catalog version is not supported.
MTS ICatalog Interface
The Catalog object enables you to connect to specific servers and access collections. The ICatalog interface contains the following methods:
ICatalog::GetCollection
ICatalog::Connect
ICatalog::get_MajorVersion
ICatalog::get_MinorVersion
ICatalog::GetCollection
The GetCollection method retrieves a local collection without reading any objects from the catalog.
Syntax HRESULT ICatalog::GetCollection(
BSTR |
bstrCollName |
IDispatch ** |
ppCatalogCollection ); |
Parameters
bstrCollName [in]
BSTR containing the name of the collection to retrieve from the catalog.
ppCatalogCollection [out]
Pointer to a pointer to the CatalogCollection object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Invalid collection name passed as a parameter. Can also indicate that an Out parameter is NULL.
ICatalog::Connect
The Connect method connects to a remote computer and returns a root collection, which is bound to a remote computer. HRESULT ICatalog::Connect(
BSTR |
bstrCollName |
IDispatch ** |
ppCatalogCollection ); |
Parameters
bstrConnectString [in]
BSTR expression containing the name of a remote computer.
PpCatalogCollection [out]
Pointer to a pointer to the CatalogCollection object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Comments
A root collection serves as a starting point to locate packages, and contains neither objects nor properties. Note that you can also use the GetCollection method to get a top-level collection on a local server without using the Connect method.
ICatalog::get_MajorVersion
The get_MajorVersion method returns the major version number of an administration object. HRESULT ICatalog::get_MajorVersion(
long* |
retval ); |
Parameters
retval [out]
Pointer to the major version number of the MTS object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Comments
Call the get_MajorVersion method and the get_MinorVersion method to determine if you are using the most current version of MTS
ICatalog::get_MinorVersion
The get_MinorVersion method retrieves the minor version number of an MTS administration object. HRESULT ICatalog::get_MinorVersion(
long* retval
);
Parameters
retval [out]
Pointer to the minor version number of the MTS object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Comments
Call the get_MajorVersion method and the get_MinorVersion method to determine if you are using the most current version of MTS
MTS ICatalogCollection Interface
The CatalogCollection object can be used to enumerate objects, create, delete, and modify objects, and access related collections. The ICatalogCollection interface contains the following methods:
ICatalogCollection::get_NewEnum
ICatalogCollection::get_Item
ICatalogCollection::get_Count
ICatalogCollection::Remove
ICatalogCollection::Add
ICatalogCollection::Populate
ICatalogCollection::SaveChanges
ICatalogCollection::GetCollection
ICatalogCollection::get_Name
ICatalogCollection::get_AddEnabled
ICatalogCollection::get_RemoveEnabled
ICatalogCollection::GetUtilInterface
ICatalogCollection::get_DataStoreMajorVersion
ICatalogCollection:: get_DataStoreMinorVersion
ICatalogCollection::PopulateByKey
ICatalogCollection::get_NewEnum
The get_NewEnum method returns the IEnumVariant enumerator interface. HRESULT ICatalogCollection::get_NewEnum(
IUnknown** |
ppEnumVariant ); |
Parameters
ppEnumVariant [out]
Pointer to a pointer to the IEnumVariant interface.
Return Values
S_OK
Method completed successfully.
INVALIDARG
Out parameter is NULL.
ICatalogCollection::get_Item
The get_Item method returns an object from the collection represented by the index. HRESULT ICatalogCollection::get_Item(
long |
1Index |
IDispatch** |
ppCatalogObject ); |
Parameters
1Index [in]
Index to the object in the collection.
Ppcatalogobject [out]
Pointer to a pointer to the Catalog object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out of range of index.
Comments
A collection object contains zero or more items (all MTS collections are zero-based).
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::get_Count
The get_Count method returns the number of objects in the collection. HRESULT ICatalogCollection::get_Count(
long* |
retval ); |
Parameters
retval [out]
Pointer to the number of elements in the object collection.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::Add
The Add method adds a default object to the collection and returns a pointer to the new object. HRESULT ICatalogCollection::Add(
IDispatch** |
ppCatalogObject ); |
Parameters
ppCatalogObject [out]
Pointer to a pointer to the new Catalog object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
E_NOTIMPL
Not supported on this collection.
Remarks
To update the objects in a collection, call the Add method to create a new object either before or after populating a collection.
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::Populate
The Populate method reads the collection objects from the catalog. HRESULT ICatalogCollection::Populate( );
Return Values
S_OK
Method completed successfully.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
E_MTS_OBJECTERRORS
Collection was read but some objects were invalid. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
Remarks
You call the Populate method to fill a package collection with objects from the catalog. This method uses the CoCreateInstance function internally, so CoCreateInstance error codes are included in the Populate method's return values.
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::SaveChanges
The SaveChanges method saves changes to the collection into the catalog. HRESULT ICatalogCollection::SaveChanges(
long* |
retval ); |
Parameters
retval [out]
Number of changes applied to the collection.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
E_MTS_OBJECTERRORS
Errors were encountered processing some objects. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOUSER
User ID is invalid.
E_MTS_USERPASSWDNOTVALID
Package identity user ID and/or password are invalid.
E_MTS_AUTHENTICATIONLEVEL
Required authentication level (package privacy) could not be set for package updates.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
CLASS_E_NOAGGREGATION
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Note that you must call this method after modifying any object in the collection. The SaveChanges method works exclusively on the collection on which it is called. This method also applies all pending changes to objects within a given collection. This method uses the CoCreateInstance function internally, so CoCreateInstance error codes are included in the SaveChanges method's return values.
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::GetCollection
The GetCollection method retrieves a collection related to a specific object. Data is not read from the catalog. See the Populate method topic for more information. HRESULT ICatalogCollection::GetCollection(
BSTR |
bstrCollName |
VARIANT |
varObjectKey |
IDispatch** |
ppCatalogCollection ); |
Parameters
bstrCollName [in]
BSTR containing the name of the collection.
VarObjectKey [in]
Value of the object key.
retval [out]
Pointer to a pointer to the CatalogCollection object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Invalid collection name passed as a parameter. Can also indicate that an Out parameter is NULL.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::get_Name
The get_Name method gets the name of a collection. HRESULT ICatalogCollection::get_Name(
VARIANT* retval**);**
Parameters
retval [out]
Pointer to the name of the collection.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::get_AddEnabled
The get_AddEnabled method returns a value that indicates if the Add method is supported in this collection. HRESULT ICatalogCollection::get_AddEnabled(
VARIANT_BOOL* varAddEnabled**);**
Parameters
VarObjectKey [out]
Boolean value indicating if the Add method is supported in this collection.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::Remove
The Remove method removes an item from a collection, given the index of the item. HRESULT ICatalogCollection::Remove(
long 1Index**);**
Parameters
1Index [in]
Index position of the object to remove.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Invalid index was entered.
E_NOTIMPL
Collection does not support removing objects.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::get_RemoveEnabled
The get_RemoveEnabled method returns a value that indicates if the Remove method is supported in this collection. HRESULT ICatalogCollection:: get_RemoveEnabled(
VARIANT_BOOL* boolRemoveEnabled**);**
Parameters
boolRemoveEnabled [out]
Boolean value indicating if the Remove method is supported in this collection.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::GetUtilInterface
The GetUtilInterface method returns a pointer to the interface of the utility object for a package, component, remote component, or role collection. HRESULT ICatalogCollection::GetUtilInterface(
IDispatch** ppUtil**);**
Parameters
ppUtil [out]
Pointer to a pointer to the interface on a utility object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
E_NOTIMPL
Not supported on this collection.
Remarks
Call the GetUtilInterface method to program your application for specific administration tasks, such as creating a package or installing a component.
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogCollection::get_DataStoreMajorVersion
The get_DataStoreMajorVersion method returns the major version number of the catalog from which you get the collection. HRESULT ICatalogCollection::get_DataStoreMajorVersion(
long* retval**);**
Parameters
retval [out]
Pointer to a pointer to the MTS major version number.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
See Also
get_DataStoreMinorVersion
ICatalogCollection::get_DataStoreMinorVersion
The get_DataStoreMinorVersion method returns the minor version number of the catalog from which you get a collection. HRESULT ICatalogCollection:: get_DataStoreMinorVersion(
long* retval**);**
Parameters
retval [out]
Pointer to a pointer to the MTS minor version number.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
See Also
get_DataStoreMajorVersion
ICatalogCollection::PopulateByKey
The PopulateByKey method populates the collection with information for the specified objects. HRESULT ICatalogCollection::PopulateByKey(
SAFEARRAY* saKeys**);**
Parameters
saKeys [in]
Pointer to a safearray of VARIANTS containing the CLSIDs of components for which the collection object should refresh its information.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
MTS ICatalogObject Interface
The CatalogObject object provides methods to get and set properties on an object. The ICatalogObject interface contains the following methods:
ICatalogObject::get_Value
ICatalogObject::put_Value
ICatalogObject::get_Key
ICatalogObject::get_Name
ICatalogObject::IsPropertyReadOnly
ICatalogObject::IsPropertyWriteOnly
ICatalogObject::get_Valid
ICatalogObject::get_Value
The get_Value method gets a property value of an object in a collection. HRESULT ICatalogObject::get_Value(
BSTR |
bstrPropName |
VARIANT* |
retval ); |
Parameters
bstrPropName [in]
BSTR expression containing the name of the property.
retval [out]
Pointer to the value of the property.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Invalid property name passed as a parameter. Can also indicate that an Out parameter is NULL.
E_NOTIMPL
Object has been removed from the collection.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogObject::put_Value
The put_Value method sets the property value of an object in a collection. HRESULT ICatalogObject::put_Value(
BSTR |
bstrPropName |
VARIANT |
val ); |
Parameters
bstrPropName [in]
BSTR containing the name of the property to set.
val [in]
Variant containing the new value for the property.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Invalid property name entered. Can also indicate either the property value is not one of the supported values or falls outside the supported range, the property is read-only, or the property cannot be changed after the object is created.
E_NOTIMPL
Object has been removed from the collection.
Remarks
See the Using MTS Collections topic for a list of the MTS collections and their properties.
ICatalogObject::get_Key
The get_Key method gets the value of the Key property. HRESULT ICatalogObject::get_Key(
VARIANT* |
retva l) ; |
Parameters
retval [out]
Pointer to the value of the Key property.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
OUT parameter is NULL.
E_NOTIMPL
Object has been removed from the collection.
Comments
All MTS objects have a key. The object key is a single property that uniquely identifies the object. To create a related collection in your Package collection object, provide the key of the object from which you want to navigate (such as the package identifier). The following table provides the key property for each collection supported by the MTS Explorer.
Collection |
Key Property |
---|---|
|
|
Packages |
ID |
ComponentsInPackage |
CLSID |
RolesInPackage |
ID |
RolesForPackageComponents |
ID |
UsersInRole |
User |
InterfacesForComponent |
IID |
InterfacesForRemoteComponent |
IID |
ICatalogObject::get_Name
The get_Name method provides the name of an object in the catalog. HRESULT ICatalogObject::get_Name(
VARIANT* |
retval ); |
Parameters
retval [out]
Pointer to the name of the object.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
E_NOTIMPL
Object has been removed from the collection.
All MTS objects have a name property. The following table provides the name property for each collection supported by the MTS Explorer:
Collection |
Name Property |
---|---|
|
|
Packages |
Name |
ComponentsInPackage |
ProgID |
RolesInPackage |
Name |
RolesForPackageComponents |
Name |
UsersInRole |
User |
InterfacesForComponent |
Name |
InterfacesForRemoteComponent |
Name |
RemoteComponents |
ProgID |
MethodsForInterface |
Name |
ICatalogObject::IsPropertyReadOnly
The IsPropertyReadOnly method determines if a property is read-only. HRESULT ICatalogObject::IsPropertyReadOnly(
BSTR |
bstrPropName |
VARIANT_BOOL* |
retval ); |
Parameters
bstrPropName [in]
BSTR containing the name of the property.
retval [out]
Boolean indicating if the property is read-only.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Invalid property name passed as a parameter. Can also indicate that an Out parameter is NULL.
Remarks
For more information about read-only property values and collections, see the Using MTS Collections topic.
See Also
IsPropertyWriteOnly
ICatalogObject::IsPropertyWriteOnly
The IsPropertyWriteOnly method indicates if a property can be written but not read. HRESULT ICatalogObject::IsPropertyWriteOnly(
BSTR |
bstrPropName |
VARIANT_BOOL* |
retval ); |
Parameters
bstrPropName [in]
BSTR containing the name of the property that may or may not be write-only.
retval [out]
Boolean indicating if the property is write-only.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Invalid property name passed as a parameter. Can also indicate that an Out parameter is NULL.
Remarks
For more information about read-only property values and collections, see the Using MTS Collections topic.
See Also
IsPropertyReadOnly
ICatalogObject::get_Valid
The get_Valid method determines if properties on an object were successfully read from the catalog. HRESULT ICatalogObject::get_Valid(
VARIANT_BOOL* |
retval ); |
Parameters
retval [out]
Boolean indicating if properties were successfully read. If this method returns True, all properties on an object were read from the catalog.
Return Values
S_OK
Method completed successfully.
E_INVALIDARG
Out parameter is NULL.
E_NOTIMPL
Object removed from the collection.
MTS IPackageUtil Interface
The IPackageUtil object enables a package to be installed and exported within the Packages collection. The IPackageUtil interface contains the following methods:
IPackageUtil::InstallPackage
IPackageUtil::ExportPackage
IPackageUtil::ShutdownPackage
See the Using MTS Collections topic for a list of the MTS collections and their properties.
IPackageUtil::InstallPackage
The InstallPackages method installs a pre-built package. HRESULT IPackageUtil::InstallPackage(
BSTR |
bstrPackageFile |
BSTR |
bstrInstallPath |
long |
1Options ); |
Parameters
bstrPackageFile [in]
BSTR containing the name of the package file to install.
bstrInstallPath [in]
BSTR containing component install path.
1Options [in]
Integer specifying export options. This method supports MtsExportUsers, which includes users in roles in the package file.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing objects and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_PDFREADFAIL
Error occurred reading the package file.
E_MTS_PDFVERSION
Package file version is invalid.
E_MTS_BADPATH
Package file path is invalid.
E_MTS_PACKAGEEXISTS
Package with the same ID is already installed.
E_MTS_ROLEEXISTS
Role with the same ID is already installed. The role ID in the package file is likely corrupted.
E_MTS_CANTCOPYFILE
Errors occurred copying one or more files to the install directory.
E_MTS_INVALIDUSERIDS
One or more user IDs for roles were invalid.
E_MTS_CLSIDORIIDMISMATCH
One or more component/interface identifiers in a component DLL do not match the identifiers saved in the package file. The package file is likely out of date.
E_MTS_PACKDIRNOTFOUND
The package install directory is invalid.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallPackage method's return values.
IPackageUtil::ExportPackage
The ExportPackage method exports a package according to its package identifier. HRESULT IPackageUtil::ExportPackage(
BSTR |
bstrPackageID |
BSTR |
bstrPackageFile |
long |
1Options ); |
Parameters
bstrPackageID [in]
BSTR containing the unique identifier of the package to export.
bstrPackageFile [in]
BSTR containing the name of the package file to export.
1Options [in]
Either zero (for no option selected) or MtsExportUsers, which includes users in roles in the package file.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing objects and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_PDFWRITEFAIL
Error occurred writing the package file.
E_MTS_NOTYPELIB
Could not find the type library for one or more components.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the ExportPackage method's return values.
IPackageUtil::ShutdownPackage
The ShutdownPackage method shuts down a single package, thereby terminating that application process. HRESULT IPackageUtil::ShutdownPackage(
BSTR |
bstrPackageID |
Parameters
bstrPackageID [in]
BSTR containing the unique identifier of the package to shut down.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing objects and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_PDFWRITEFAIL
Error occurred writing the package file.
E_MTS_NOTYPELIB
Could not find the type library for one or more components.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
MTS IComponentUtil Interface
The IComponentUtil object provides methods to install a component in a specific collection and to import components registered as an in-proc server. The IComponentUtil interface contains the following methods:
IComponentUtil::InstallComponent
IComponentUtil::ImportComponent
IComponentUtil::ImportComponentByName
IComponentUtil::GetCLSIDs
IComponentUtil::InstallComponent
The InstallComponent method installs a component. HRESULT IComponentUtil::InstallComponent(
BSTR |
bstrDLLFile |
BSTR |
bstrTypelibFile |
BSTR |
bstrProxyStubDLL ); |
Parameters
bstrDLLFile [in]
BSTR containing the name of the DLL file providing the components to install.
bstrTypelibFile [in]
BSTR containing the name of the external type library file. If the type library file is embedded in the DLL, pass in an empty string for this parameter.
bstrProxyStubDLL [in]
BSTR containing the name of the proxy-stub DLL file. If there is no proxy-stub DLL associated with the component, pass in an empty string for this parameter.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallComponent method's return values.
IComponentUtil::ImportComponent
The ImportComponent method imports a component that is already registered as an in-process (in-proc) server. HRESULT IComponentUtil::ImportComponent(
BSTR |
bstrCLSID ); |
Parameters
bstrCLSID [in]
BSTR containing the CLSID of the component to import.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the ImportComponent method's return values.
See Also
ImportComponentByName
IComponentUtil::ImportComponentByName
The ImportComponentByName method imports a component that is already registered as an in-process (in-proc) server. This method uses the component's programmatic identifier (ProgID) for the import procedure. HRESULT IComponentUtil::ImportComponentByName(
BSTR |
bstrProgID ); |
Parameters
bstrProgID [in]
BSTR containing the ProgID of the component to import.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the ImportComponentByName method's return values.
See Also
ImportComponent
IComponentUtil::GetCLSIDs
The GetCLSIDs method fills an array with the installable component CLSIDs from a DLL and/or type library. HRESULT IComponentUtil::GetCLSIDs(
BSTR |
bstrDLLFile |
BSTR |
bstrTypeLibFile |
SAFEARRAY** |
ppsaCLSIDs) |
Parameters
bstrDLLFile [in]
BSTR containing the name of the DLL file providing the components to check for allowable installation.
bstrTypeLibFile [in]
BSTR containing the name of the external type library file to check for installable components.
ppsaCLSIDs [out]
Pointer to a pointer to a SAFEARRAY containing VARIANTS which contain the CLSIDs of installable components in the given DLL and/or type library.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
MTS IRemoteComponentUtil Interface
You can use the IRemoteComponentUtil object to program your application to pull remote components from a package on a remote server. The IRemoteComponentUtil interface contains the following methods:
IRemoteComponentUtil::InstallRemoteComponent
IRemoteComponentUtil::InstallRemoteComponentByName
IRemoteComponentUtil::InstallRemoteComponent
The InstallRemoteComponent method pulls a component to install from a package on a remote server. HRESULT IRemoteComponentUtil::InstallRemoteComponent(
BSTR |
bstrServer |
BSTR |
bstrPackageID |
BSTR |
bstrCLSID ); |
Parameters
bstrServer [in]
BSTR containing the name of the remote server from which to pull the component to install.
PackageID [in]
BSTR containing the identifier of the package containing the remote component.
bstrCLSID [in]
BSTR containing the class identifier (CLSID) of the remote component.
Return Values
S_OK
Method returned successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallRemoteComponent method's return values.
See Also
InstallRemoteComponentByName
IRemoteComponentUtil::InstallRemoteComponentByName
The InstallRemoteComponentByName method pulls remote components from the package on a remote server and installs the component by package name and programmatic ID (ProgID). HRESULT IRemoteComponentUtil::InstallRemoteComponentByName(
BSTR |
bstrSever |
BSTR |
PackageName |
BSTR |
bstrProgID ); |
Parameters
bstrSever [in]
BSTR containing the name of the remote server from which to pull the component to install.
PackageName [in]
BSTR containing the name of the package containing the remote component.
bstrProgID [in]
BSTR containing the ProgID of the component to install.
Return Values
S_OK
Method completed successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing objects. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the InstallRemoteComponentByName method's return values.
See Also
InstallRemoteComponent
MTS IRoleAssociationUtil Interface
Call methods on the IRoleAssociationUtil object to associate roles with a component or component interface. The IRoleAssociationUtil interface contains the following methods:
IRoleAssociationUtil::AssociateRole
IRoleAssociationUtil::AssociateRoleByName
IRoleAssociationUtil::AssociateRole
The AssociateRole method associates a role with a component or component interface. HRESULT IRoleAssociationUtil::AssociateRole(
BSTR bstrRoleID
);
Parameters
bstrRoleID [in]
BSTR containing the ID of the role to associate with a component or component interface.
Return Values
S_OK
Method returned successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing objects. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the AssociateRole method's return values.
See Also
AssociateRoleByName
IRoleAssociationUtil::AssociateRoleByName
The AssociateRoleByName method associates a role by its name with a specified component or component interface. HRESULT IRoleAssociationUtil::AssociateRoleByName(
BSTR |
bstrRoleName ); |
Parameters
bstrRoleName [in]
BSTR containing the name of the role to associate with a component or component interface.
Return Values
S_OK
Method returned successfully.
E_MTS_OBJECTERRORS
Errors were encountered processing components and/or files. See the ErrorInfo collection for object-specific error codes.
E_MTS_NOREGISTRYREAD
Access control failure reading a registry key.
E_MTS_NOREGISTRYWRITE
Access control failure writing a registry key.
E_MTS_NOREGISTRYREPAIR
Access control failure writing a registry key.
REGDB_E_CLASSNOTREG
The MTXCatEx.CatalogServer.1 component is not registered on the target computer. MTS is not installed properly on the target computer.
Remarks
Because this method uses the CoCreateInstance function internally, CoCreateInstance error codes are included in the AssociateRoleByName method's return values.
See Also
AssociateRole