Export (0) Print
Expand All

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".
Data Type: String
Default value: N/A
Access: Read only.

Description

Description of the computer.
Data Type: String
Default value: Empty string
Access: Read/write

Transaction Timeout

The transaction timeout setting in seconds.
Data Type: Integer
Default value: 60
Access: Read/write

RemoteComponent InstallPath

The path in which remote component files will be installed when remote components are configured
Data Type: String
Default value: the subdirectory "Remote" in the MTS install path
Access: Read/write

PackageInstall Path

The default path in which component files will be installed when pre-built packages are installed.
Data Type: String
Default value: the subdirectory "Packages" in the MTS install path
Access: Read/write

ResourcePooling Enabled

"Y" enables resource pooling. "N" disables resource pooling. Note that resource pooling is currently only supported by the ODBC resource dispenser.
Data Type: String
Default value: "Y"
Access: Read/write

ReplicationShare

When replicating the MTS catalog, the name of a share that the target system should use to access installed packages.
Data Type: String
Default value: Empty string
Access: Read/write

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.
Data Type: String
Default value: Empty string
Access: Read/write

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.
Data Type: String
Default value: "NewComputer"
Access: Read/Write while using the Add method. After adding, read-only.

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.
Data Type: String
Default value: "New package"
Access: Read/Write

ID

A universally unique identifier (UUID) for the package.
Data Type: String
Default value: A unique identifier is generated
Access: Read/Write when using the Add method. Read-only
after using the Add method.

Description

Describes the package. Description fields hold a maximum of 500 characters.
Data Type: String
Default value: None
Access: Read/Write

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.
Data Type: String
Default value: "N"
Access: Read only

Authentication

Sets authentication level for calls. Possible values are 0 through 6, which correspond to the Remote Procedure Call (RPC) authentication settings.
Data Type: Long
Default value: 4
Access: Read/Write

ShutdownAfter

Sets the delay before shutting down a server process after it becomes idle. Shutdown latency ranges from 0 to 1440 minutes.
Data Type: Long
Default value: 3
Access: Read/Write

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.
Data Type: String
Default value: "N"
Access: Read/Write

SecurityEnabled

Checks the security credentials of any client that calls the package if value is set to "Y."
Data Type: String
Default value: "N"
Access: Read/Write

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.
Data Type: String
Default value: "Interactive User"
Access: Read/Write

Password

Sets the password used by the server process to log on under the identity above.
Data Type: String
Default value: None
Access: Write only

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"
Data Type: String
Default Value: "Local"
Access: Read/Write

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
Default Value: Y
Access: Read/Write

Deleteable

Sets whether the package or its components can be deleted (either programmatically, or through the MTS UI).
Data Type: String
Default Value: "Y"
Access: Read/Write

CreatedBy

Informational string to describe the package creator.
Data Type: String
Default Value: Empty string
Access: Read/Write

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.
Data Type: String
Default value: None
Access: Read only

CLSID

The universally unique identifier (UUID) for the component.
Data Type: String
Default value: None
Access: Read only

Transaction

Determines how a component supports transactions. Must be one of the following transaction settings:
"Required"
"Requires New"
"Not Supported"
"Supported"
Data Type: String
Default value: "Not supported"
Access: Read/Write

Description

Describes the component. Description fields hold a maximum of 500 characters.
Data Type: String
Default value: None
Access: Read/Write

PackageID

Defines the identity of the owning package.
Data Type: String
Default value: None
Access: Read only

PackageName

Defines the name of the owning package.
Data Type: String
Default value: "New Package"
Access: Read only

ThreadingModel

Determines how instances of the component are assigned to threads for method execution. Possible values are those supported by Component Object Model (COM).
Data Type: String
Default value: None
Access: Read only

SecurityEnabled

Checks the security credentials of any client that calls the component if value is set to "Y."
Data Type: String
Default value: "Y"
Access: Read/Write

DLL

Displays the name of the DLL containing the component implementation.
Data Type: String
Default value: None
Access: Read only

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.
Data Type: String
Default value: "N"
Access: Read only

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.
Data Type: String
Default value: None
Access: Read only

CLSID

The universally unique identifier (UUID) for the component.
Data Type: String
Default value: None
Access: Read only

Description

Describes the remote component. Description fields hold a maximum of 500 characters.
Data Type: String
Default value: None
Access: Read/Write

Server

Name of the server hosting the remote component.
Data Type: String
Default value: None
Access: Read only

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.
Data Type: String
Default value: None
Access: Read only

ID

Displays the unique interface identifier (IID).
Data Type: String
Default value: None
Access: Read only

Description

Describes the interface. Description fields hold a maximum of 500 characters.
Data Type: String
Default value: None
Access: Read/Write

ProxyCLSID

Displays the CLSID of the proxy/stub.
Data Type: String
Default value: None
Access: Read only

ProxyDLL

Displays the file name of the proxy/stub DLL.
Data Type: String
Default value: None
Access: Read only

ProxyThreadingModel

Displays the threading model of the selected proxy/stub.
Data Type: String
Default value: None
Access: Read only

TypeLibID

Displays the UUID of the type library.
Data Type: String
Default value: None
Access: Read only

TypeLibVersion

Displays the version of the type library.
Data Type: String
Default value: None
Access: Read only

TypeLibLangID

Displays the language identification number of the type library.
Data Type: String
Default value: None
Access: Read only

TypeLibPlatform

Displays the platform of the type library.
Data Type: String
Default value: None
Access: Read only

TypeLibFile

Displays the file name of the type library.
Data Type: String
Default value: None
Access: Read only

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.
Data Type: String
Default value: None
Access: Read only

ID

Displays the universally unique identifier (UUID) of the role.
Data Type: String
Default value: None
Access: Read only

Description

Describes the role. Description fields hold a maximum of 500 characters.
Data Type: String
Default value: None
Access: Read only

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.
Data Type: String
Default value: None
Access: Read only

Description

Describes the method. Description fields hold a maximum of 500 characters.
Data Type: String
Default value: None
Access: Read only

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.
Data Type: String
Default value: "New Role"
Access: Read/write

ID

The universally unique identifier (UUID) for the role.
Data Type: String
Default value: A unique identifier is generated.
Access: Read/Write while using the Add method. After adding an object, Read-only.

Description

Describes the new Role. Description fields hold a maximum of 500 characters.
Data Type: String
Default value: None
Access: Read/write

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.
Data Type: String
Default value: "New User"
Access: Read/Write while using the Add method. After adding, read-only.

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.
Data Type: String
Default value: None
Access: Read only.

ErrorCode

Error code for the object or file.
Data Type: Long
Default value: None
Access: Read only

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.
Data Type: String
Default value: None
Access: Read only

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.
Data Type: String
Default value: None
Access: Read only

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:
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.

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

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft