Automating MTS Administration

Article
02/20/2014

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.

Microsoft Transaction Server (MTS) developers and advanced web administrators can use scriptable administration objects to automate MTS application deployment and administration. The scriptable objects correspond to the Microsoft Transaction Server Explorer collection hierarchy. You can automate administrative procedures by calling interfaces on the appropriate scriptable administration object. The following diagram shows the types of collections administered and deployed by the MTS Explorer:

methhier

In order to effectively use the scriptable administration objects, you should have a thorough understanding of the tasks that your application automates in the MTS Explorer. You can use any OLE Automation-compatible language to develop your application because the scriptable administration objects are derived from the IDispatch interface. Microsoft Visual Basic™ version 5.0 and Microsoft Visual C++ version 5.0, which support ActiveX technology, are recommended development tools. See the MTS Administrative Reference for a complete Visual Basic sample that demonstrates how to use the scriptable administration objects.

This section discusses the following topics:

MTS Administration Objects
Visual Basic Script Sample for Automating MTS Administration
Visual Basic Sample Application for Automating MTS Administration
Automating MTS Administration with Visual Basic
Automating Advanced MTS Administration with Visual Basic

MTS Administration Objects

The following scriptable objects are used for administration:

Catalog Object

CatalogObject Object

CatalogCollection Object

PackageUtil Object

ComponentUtil Object

RemoteComponentUtil Object

RoleAssociationUtil Object

These scriptable objects provide general and utility interfaces for your different scripting needs. The Catalog, CatalogObject, and CatalogCollection objects comprise the catalog collection object layer, and provide top-level functionality such as creating and modifying objects. The Catalog object enables you to connect to specific servers and access collections. Call the CatalogCollection object to enumerate, create, delete, and modify objects, as well as to access related collections. The CatalogObject object is used to get and set properties on an object.

In the catalog utility object layer, the PackageUtil, ComponentUtil, RemoteComponentUtil, and RoleAssociationUtil objects enable more specific task automation, such as installing components and exporting packages. This utility layer allows you to program very specific tasks for collection types, such as associating a role with a user or class of users.

The following diagram illustrates how your configuration program uses methods on the administrative objects to read and write data to the catalog.

To learn how to obtain the administrative samples and reference documentation, see the Installing MTS Development Samples and Documentation topic.

Using MTS Catalog Collection Objects

Each folder in the MTS Explorer corresponds to a collection stored in the catalog. The Catalog, CatalogObject, and CatalogCollection objects comprise the catalog collection object layer. These objects enable you to automate general administrative procedures into your applications such as creating, deleting, or modifying objects.

Instantiating an MTS CatalogCollection Object

You can instantiate a CatalogCollection object in order to access any type of collection or data from any MTS Explorer folder. To instantiate a CatalogCollection object, use the GetCollection method and supply a collection name. The CatalogCollection object is a generic object used to access any type of collection (such as data from any Explorer folder). You can call the GetCollection method from a Catalog object to get a top-level collection. You can also call the GetCollection method from a CatalogCollection object to get a related collection.

Populating an MTS CatalogCollection Object

Use the administrative objects to populate a CatalogCollection object with data from the catalog. Note that instantiating the object does not read any data from the catalog. To browse or change the data in the collection, call the Populate or PopulateByKey method first. Populate will read all the data into the collection. PopulateByKey will only read the objects that you specify. You do not need to populate the collection to add data to the collection or use a utility object interface.

Retrieving MTS Objects and Getting/Setting Properties

The CatalogCollection object supports methods for iterating through the objects in the collection. If you are using Visual Basic as your development tool, you can iterate using the For Each statement. If you use Visual C++, invoke the Item and Count methods to enumerate through a collection. Access object properties using the object's Value property, and supply a property name as a parameter.

Creating New MTS Objects

Some collections support the Add method to create a new object. Other collections require that you use a utility interface to install objects (such as a component). See the Using MTS Catalog Utility Objects topic for more details.

Saving Changes to MTS Objects

Property changes and new objects (created using the Add method) and object removal (deleted using the Remove method, which most collections support to delete an object) are held in-memory until you call the SaveChanges method. When you call the SaveChanges method, any changes in the CatalogCollection object are applied to the catalog. If you release the CatalogCollection object before you call the SaveChanges method or call the Populate or PopulateByKey method before calling the SaveChanges method, all pending changes will be lost.

Using MTS Catalog Utility Objects

The utility object layer consists of the PackageUtil, ComponentUtil, RemoteComponentUtil, and RoleAssociationUtil objects. These objects are used to perform specific actions directly on the catalog (such as installing components or installing pre-built packages). Utility objects are specific to a particular type of collection. Obtain a utility object by calling the GetUtilInterface method on the CatalogCollection object.

vipa02

When using a utility object, the changes made to the catalog do not affect the CatalogCollection object from which you obtained the utility object. You must call the Populate or PopulateByKey method on the CatalogCollection object in order to view any changes. There is no need to call the SaveChanges method after using a utility method, as changes are written immediately to the catalog.

Handling MTS Catalog Errors

The catalog collection and catalog utility methods return HRESULTS that indicate success or failure. In Visual Basic, you use the On Error handler and the Err object to trap these errors and access the failure code. Methods that deal with many objects (such as the SaveChanges or InstallPackage methods) may capture multiple error codes to describe specific object failures. You access this set of codes through a collection called ErrorInfo. You can use the GetCollection method to access an ErrorInfo collection. Each CatalogCollection object that you instantiate maintains an ErrorInfo collection that stores failure codes for the last method call that failed. If you are installing a package, you can see which components are already installed by accessing the ErrorInfo collection for that object.

It is recommended that you program your application to check each method call for success or failure. Your program should especially test for the E_INVALIDARG return code (run-time error 5 in Visual Basic) when supplying collection names or property names. This code indicates that one or more of the supplied collection or property names is not supported.

Visual Basic Script Samples for Automating MTS Administration

You can use an OLE-Automation compatible language (such as VBScript) to call the scriptable administration objects. MTS provides administrative sample scripts to demonstrate how to use the scriptable objects to automate MTS Explorer procedures.

In order to run an Automation script outside of an HTML page, you must have the Windows Script Host (WSH) installed on your computer. WSH is a command-line scripting utility that can be installed by the Window NT 4.0 Option Pack for Windows NT computers. WSH enables scripts to be executed directly on the Windows desktop or command console. You do not need to embed those scripts in an HTML document; instead, scripts can be run directly from the desktop by clicking a script file, or from the command console. For more detailed information, see the Windows Script Host documentation.

To demonstrate how to use the administration objects in a script, run the sample scripts contained in the \Program Files\Mts\Samples sub-directory. The WSH sub-directory contains the following five sample scripts written in VB Script:

InstDLL.vbs
InstPak.vbs
Uninst.vbs
InstDllCLI.vbs
InstPakCLI.vbs

These scripts automate administrative procedures for Sample Bank. For example, the InstDLL.vbs script calls scriptable objects to first delete existing versions of Sample Bank, create a new package named Sample Bank, install components from the Sample Bank Visual Basic, Visual C++, and Visual J++ DLLs into the new package, change transaction attributes, and add a new role. The InstPak.vbs script also uses the scriptable objects to install Sample Bank, while Uninst.vbs automates uninstalling the Sample Bank package from MTS. After running a script, you can see the results of the script in the MTS Explorer after clicking the Refresh toolbar button.

In order to use the InstDLL.vbs, InstPak.vbs, and Uninst.vbs scripts, you must modify the file path in the script to point to the location of the required files on your computer. For example, the file path in the InstPak.vbs script is the default location for the Sample Bank package, which is:

path="C:\Program Files\Mts\Samples\Packages\"

If you have the Sample Bank package installed in a different location, modify that line in the script to point to the current location of the package.

The InstDllCLI.vbs and InstPakCLI.vbs scripts support command line parameters so you can include the file location as a parameter when running your script in a console window. At the command prompt, open the directory containing the script you want to use, and type the name of the script and the location of the package or DLLs. For example, to install the Sample Bank package located in the default directory, open the directory containing the samples scripts and use the following command at the command prompt:

InstPakCLI.vbs "C:\Program Files\Mts\Samples\Packages\"

To use the InstDLL.vbs script, you must first do one of the following to register the Java components in the vjacct.dll file:

Install the package by running the InstDLL.vbs script
Register the Java components using the Microsoft Visual Studio 97 ActiveX Wizard.

Visual Basic Sample Application for Automating MTS Administration

The Visual Basic version 5.0 sample application demonstrates how to use the methods on the Catalog, CatalogObject, and CatalogCollections objects to automate basic administration functionality for a package named "Scriptable Admin Demo."

Note: You must configure your Visual Basic project to reference the MTS administrative type library (MTSAdmin type library). To reference the MTSAdmin type library, select the References option from the Visual Basic Project toolbar. Then browse the available reference files for the "MTS 2.0 Admin Type Library." For late-binding variables (binding that occurs when you run the program), Visual Basic will locate the type library without further configuration if the MTXADMIN.DLL file is registered on your local machine.

To delete any existing packages named "Scriptable Admin Demo"

Call the CreateObject method to instantiate a catalog object.

Dim catalog As Object Set catalog = CreateObject("MTSAdmin.Catalog.1")

Get a Packages collection object by calling the GetCollection method. The Packages collection returns without retrieving any data from the catalog so that the collection will be empty upon return from the GetCollection method.

Dim packages As Object Set packages = catalog.GetCollection("Packages")

Find the previous version of the "Scriptable Admin Demo" package by populating the Packages collection to read in all packages and search for "Scriptable Admin Demo." Enumerate through the collection, starting at the highest index so the Remove method can be called from within the loop. The Remove method releases the object, removes the object from the collection, and shifts the objects in the collection so that object(n+1) becomes object(n) for all n greater than or equal to the index being removed. The effect of Remove method on the collection object is immediate. The Item and Count methods called any time after the Remove method will reflect the change in the index. However, the removal of the package is not applied to the catalog until the SaveChanges method is called (see step 4).

packages.Populate Dim pack As Object n = packages.Count For i = n - 1 To 0 Step -1 If packages.Item(i).Value("Name") = "Scriptable Admin Demo" Then packages.Remove (i) End If Next

Call the SaveChanges method to save changes to the data store.

packages.SaveChanges

To create a new package named "Scriptable Admin Demo Package"

Add a new package using the Add method, and note the package ID assigned. The Add method adds the object to the collection but does not apply the changes to the catalog until the SaveChanges method is called (see step 3). Note that the Add method will apply default values to all properties. The default ID will be a new unique identifier.

Dim newPack As Object Dim newPackID As Variant Set newPack = packages.Add newPackID = newPack.Value("ID")

Update the Name and SecurityEnabled properties.

newPack.Value("Name") = "Scriptable Admin Demo" newPack.Value("SecurityEnabled") = "N"

Call the SaveChanges method to save the new package to the catalog. The return value of this call is the number of objects changed, added, or deleted. If no changes were pending, the method returns 0.

n = packages.SaveChanges

To update the "Scriptable Admin Demo" package properties and get the ComponentsInPackage collection.

Call the PopulateByKey method to read the package back from the catalog. Pass an array containing the keys of the objects to read. In the sample code, we use an array containing a single element (the ID of the package just created).

Dim keys(0) as Variant keys(0) = newPackId packages.PopulateByKey keys

Get the package object from the collection

Dim package As Object Set package = packages.Item(0)

Update the SecurityEnabled property for the package.

package.Value("SecurityEnabled") = "Y"

Call the GetCollection method to retrieve the ComponentsInPackage collection. Supply the key of the "Scriptable Admin Demo package as a parameter.

Set components = packages.GetCollection("ComponentsInPackage",_ package.Key)

Call the SaveChanges method to save the changes to the catalog.

packages.SaveChanges

To install a componentasdefcomponent into the "Scriptable Admin Demo package":

Call the GetUtilInterface method to get the component utility object. This object is used to install components.

Dim util As Object Set util = components.GetUtilInterface On Error GoTo installFailed

Call the InstallComponent method, passing in a string containing the name of the dynamic-link library (DLL) of the component to be installed. If the component does not have an external type library or a proxy-stub DLL, pass in empty strings as the second and third arguments. Note that you do not have to call the SaveChanges method after installing a new component. All components contained in a DLL will be installed by this method, and are immediately written to the catalog. Call the GetCLSIDs method to get the CLSIDs of the components installed.

Form2.Show 1 Dim thePath As String thePath = Form2.MTSPath + "\samples\packages\vbacct.dll" util.InstallComponent thePath, "", "" Dim installedCLSIDs() as Variant util.GetCLSIDs thePath, "", installedCLSIDs On Error GoTo 0

Call the PopulateByKey method to read back the components just installed. Note that the components installed into the package via the InstallComponent method are not visible in the collection until the Populate or PopulateByKey method is called to read the data from the catalog.

components.PopulateByKey installedCLSIDs

To find and delete the Bank.CreateTable component from the "Scriptable Admin Demo package":

Iterate through the components and change transaction attributes using the Item and Count methods.

Dim component As Object n = components.Count For i = n - 1 To 0 Step -1 Set component = components.Item(i) component.Value("Transaction") = "Required"

Find and delete the Bank.CreateTable component by index. Note that you must iterate though the collection backwards in order to call the Remove method during the loop.

If component.Value("ProgID") = "Bank.CreateTable" Then components.Remove (i) End If Next

Retrieve a new count and iterate through the collection again. Note that the Bank.CreateTable component will not be deleted from the data store until the SaveChanges method is called. Display a message box that informs the user if the installation succeeded.

n = components.Count For i = 0 To n - 1 Set component = components.Item(i) Debug.Print component.Value("ProgID") Debug.Print component.Value("DLL") Next n = components.SaveChanges MsgBox "Scriptable Admin Demo package installed and configured." Exit Sub installFailed: MsgBox "Error code " + Str$(Err.Number) + " installing " + thePath + " Make sure the MTS path you entered is correct and that vbacct.dll is not already installed." End Sub

Automating MTS Administration with Visual Basic

The scriptable administration objects can be used to install, delete, and update properties for packages and components. These topics provide a sample procedure and Visual Basic version 5.0 sample code using methods on the scriptable administration objects to automate the following administrative tasks:

Automating Installation of a Pre-Built MTS Package
Automating a New MTS Package and Installing Components
Automating Enumerating Through Installed MTS Packages to Update Properties
Automating Enumerating Through Installed MTS Packages to Delete a Package
Automating Enumerating Through Installed MTS Components to Delete a Component

Automating Installation of a Pre-Built MTS Package

To install a pre-built package named "Test.pak" into the MTS Explorer:

Declare the objects that you will be using to install a pre-built package.

Private Sub InstallPackage_Click()
 Dim catalog As Object
 Dim packages As Object
 Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.
```
On Error GoTo failed
```

Call the CreateObject method to instantiate the Catalog object. Retrieve the top level Packages collection by calling the GetCollection method.
```
Set catalog = CreateObject("MTSAdmin.Catalog.1")
Set packages = catalog.GetCollection("Packages")
```

Instantiate the PackageUtil object, and call the InstallPackage method to install a package named "test.pak."
```
Set util = packages.GetUtilInterface
 util.InstallPackage "c:\test.pak", "", 0
 Exit Sub
```

Use the Err object to display an error message if the installation of the package fails.
```
failed:
     MsgBox "Failure code " + Str$(Err.Number)
 End Sub
```

Automating Creating a New MTS Package and Installing Components

To create a new package named "My Package" and install the components in that package:

Declare the objects that you will be using to create a new package and install components into that package.

Dim catalog As Object
 Dim packages As Object
 Dim newPack As Object
 Dim componentsInNewPack As Object
 Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.
```
    On Error GoTo failed
```

Call the CreateObject method to instantiate the Catalog object. Retrieve the top level Packages collection from the CatalogCollection object by calling the GetCollection method. Then call the Add method to add a new package.
```
Set catalog = CreateObject("MTSAdmin.Catalog.1")
 Set packages = catalog.GetCollection("Packages")
 Set newPack = packages.Add
 Dim newPackID As String
```

Set the package name to "My Package" and save changes to the Packages collection.

newPackID = newPack.Key
	  newPack.Value("Name") = "My Package"
	  packages.SaveChanges

Call the GetCollection method to access the ComponentsInPackage collection. Then instantiate the ComponentUtil object in order to call the InstallComponent method to populate the new package with components.
```
Set componentsInNewPack =
```

packages.GetCollection("ComponentsInPackage", newPackID) Set util = componentsInNewPack.GetUtilInterface util.InstallComponent"d:\dllfilepath", "", "" Exit Sub

Use the Err object to display an error message if the installation of the package fails.

failed: MsgBox "Failure code " + Str$(Err.Number) End Sub

Automating Enumerating Through Installed MTS Packages to Update Properties

To enumerate through installed packages in order to update properties in the package named "My Package":

Declare the objects that you will be using to enumerate through installed packages to update package properties.

Private Sub BrowseUpdate_Click() Dim catalog As Object Dim packages As Object Dim pack As Object Dim componentsInNewPack As Object Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the Packages collection by calling the GetCollection method. Then call the Populate method to fill the collection with packages from the catalog.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set packages = catalog.GetCollection("Packages") packages.Populate

Enumerate through a collection to find the package named "My Package." When "My Package" is located, set the SecurityEnabled property to "Y." Call the SaveChanges method to save the property update for the package.

For Each pack In packages If pack.Name = "My Package" Then pack.Value("SecurityEnabled") = "Y" Exit For End If Next packages.SaveChanges Exit Sub

Use the Err object to display an error message if the installation of the package fails.

failed: MsgBox "Failure code " + Str$(Err.Number) End Sub

Automating Enumerating Through Installed MTS Packages to Delete a Package

To enumerate through installed packages to delete the package named "My Package":

Declare the objects that you will be using to enumerate through installed packages to delete a specific package.

Dim catalog As Object Dim packages As Object Dim pack As Object Dim componentsInPack As Object Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the Packages collection by calling the GetCollection method. Then call the Populate method to fill the collection with packages installed in the catalog.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set packages = catalog.GetCollection("Packages") packages.Populate

Use the Count and Item methods to enumerate through the package collection to find the package named "My Package." When "My Package" is located, call the Remove method to delete the package. Then save changes to the collection by calling the SaveChanges method.

For i = 0 To packages.Count-1 Set pack = packages.Item(i) If pack.Name = "My Package" Then packages.Remove (i) packages.savechanges Exit For End If Next Exit Sub

Use the Err object to display an error message if the installation of the package fails.

failed: MsgBox "Failure code " + Str$(Err.Number) End Sub

Automating Enumerating Through Installed MTS Components to Delete a Component

To enumerate through installed components to delete a component:

Declare the objects that you will be using to enumerate through installed components to delete a specific component.

Dim catalog As Object Dim packages As Object Dim pack As Object Dim componentsInPack As Object Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the Packages collection by calling the GetCollection method. Then call the Populate method to fill the collection with packages installed in the catalog.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set packages = catalog.GetCollection("Packages") packages.Populate

Enumerate through the collection to look for the package named "My Package." Then call the GetCollection method to get the ComponentsInPackage collection. Fill the ComponentInPackages collection using the Populate method, and then enumerate through the collection to find the "Bank.Account" component. Call the Remove method to delete the component, and save changes to the collection by calling the SaveChanges method.

For Each pack In packages If pack.Name = "My Package" Then Set componentsInPack = packages.GetCollection("ComponentsInPackage", pack.Key) componentsInPack.Populate For i = 0 To componentsInPack.Count Set comp = componentsInPack.Item(i) If comp.Name = "Bank.Account" Then componentsInPack.Remove (i) componentsInPack.savechanges Exit For End If Next Exit For End If Next Exit Sub

Use the Err object to display an error message if the installation of the package fails.

failed: MsgBox "Failure code " + Str$(Err.Number) End Sub

Automating Advanced MTS Administration with Visual Basic

The scriptable administration objects can be used to configure clients and roles, export packages, and access the names of collections and properties supported by the catalog. The following topics provide a procedure and Visual Basic version 5.0 sample code using methods on the scriptable administration objects to automate the following administrative tasks:

Automating Access to MTS Related Collection Names
Automating Access to MTS Property Information
Automating MTS Role Configuration
Automating MTS Package Export
Automating Configuration of an MTS Client to Use Remote Components
Automating MTS Package Property Updates on Remote Servers

The RelatedCollectionInfo collection provides a list of related collections that you can access from a given collection. See the RelatedCollectionInfo topic in the MTS Administrative Reference for a list of properties supported by this collection.

To access and display related collection names:

Declare the objects that you will be using to access the object that provides the names of related collections

Dim catalog As Object Dim packages As Object Dim RelatedCollectionInfo As Object Dim collName As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the Packages collection by calling the GetCollection method. Then call the GetCollection method on the Packages collection object to obtain the RelatedCollectionInfo collection. Note that the key value is left blank when calling GetCollection to access the RelatedCollectionInfo collection. The key value is not used because the information in RelatedCollectionInfo will be the same for all packages. Fill the RelatedCollectionInfo collection with information from the catalog by calling the Populate method.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set packages = catalog.GetCollection("Packages") Set RelatedCollectionInfo =_ packages.GetCollection("RelatedCollectionInfo", "") RelatedCollectionInfo.Populate

Enumerate through the RelatedCollectionInfo collection and display the names of each collection.

For Each collName In RelatedCollectionInfo Debug.Print collName.Name Next Exit Sub

Use the Err object to display an error message if the installation of the package fails.

failed: MsgBox "Failure code " + Str$(Err.Number)

End Sub

Automating Access to MTS Property Information

The PropertyInfo collection stores information about each property in a collection. See the PropertyInfo topic in the MTS Administrative Reference for more information about this collection.

To access and list the name of each property in a collection:

Declare the objects that you will be using to access property information stored in the catalog.

Dim catalog As Object Dim packages As Object Dim propertyInfo As Object Dim property As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the Packages collection by calling the GetCollection method. Call the GetCollection method on the Packages collection to obtain the PropertyInfo collection. Note that the key value is left blank when calling GetCollection to access the PropertyInfo collection. The key value is not used because the information in PropertyInfo will be the same for all packages. Fill the PropertyInfo collection with information from the Catalog by using the Populate method.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set packages = catalog.GetCollection("Packages") Set propertyInfo = packages.GetCollection("PropertyInfo", "") propertyInfo.Populate

Enumerate through the PropertyInfo collection and list the names of each property in the collection.

For Each property In propertyInfo Debug.Print property.Name Next Exit Sub

Use the Err object to display an error message if the installation of the package fails.

failed: MsgBox "Failure code " + Str$(Err.Number) End Sub

Automating MTS Role Configuration

To configure a role a package and component, and assign administrative privileges to a user:

Declare the objects that you will be using to configure a role for a specific component.

Dim catalog As Object Dim packages As Object Dim pack As Object Dim comp As Object Dim newUser As Object Dim newRole As Object Dim componentsInPack As Object Dim RolesInPackage As Object Dim usersInRole As Object Dim rolesForComponent As Object Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the Packages collection by calling the GetCollection method. Then populate the Packages collections with data from the catalog.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set packages = catalog.GetCollection("Packages") packages.Populate

Enumerate through the Packages collection to look for the package named "My Package." When "My Package" is located, call the GetCollection method to obtain the RolesInPackage collection. Add a new role to package using the Add method. Name the new role "R1," and save changes to the collection.
```
If pack.Name = "My Package" Then
```

Set rolesInPack = packages.GetCollection("RolesInPackage", pack.Key) Set newRole = rolesInPack.Add newRole.Value("Name") = "R1" rolesInPack.savechanges

Call the GetCollection method on the RolesInPackage collection to get the UsersInRole collection. Use the Add function to add an existing NT user to the role. Set the user name to "administrator." Save changes to the UsersInRole collection.
```
        Set usersInRole = RolesInPackage.GetCollection("UsersInRole",
```

newRole.Key) Set newUser = usersInRole.Add newUser.Value("User") = "administrator" usersInRole.savechanges

Get the ComponentsInPackage collection using the GetCollection method. Populate the ComponentsInPackage collection, and enumerate through the collection to find the Bank.Account component. To associate the new role with the component, instantiate the RoleAssociationUtil object using the GetUtilInterface method. Then associate the new role with the component by calling the AssociateRole method.

Set componentsInPack = packages.GetCollection("ComponentsInPackage", pack.Key) componentsInPack.Populate For Each comp In componentsInPack If comp.Name = "Bank.Account" Then Set rolesForComponent = componentsInPack.GetCollection ("RolesForPackageComponent", comp.Key) Set util = rolesForComponent.GetUtilInterface util.associateRole (newRole.Key) Exit For End If Next Exit For End If Next Exit Sub

Use the Err object to display an error message if the installation of the component fails.
```
failed:
 MsgBox "Failure code " + Str$(Err.Number)
 End Sub
```

Automating MTS Package Export

To export a package named "test.pak":

Declare the objects that you will be using to export a package.

Dim catalog As Object Dim packages As Object Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the Packages collection by calling the GetCollection method. Call the Populate method to fill the package with data from the catalog.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set packages = catalog.GetCollection("Packages") packages.Populate

Enumerate through the Packages collection to find the package named "My Package." Once that package is located, instantiate the package utility object and call the ExportPackage method.

For Each pack In packages If pack.Name = "My Package" Then Set util = packages.GetUtilInterface util.ExportPackage pack.Key, "c:\test.pak", 0 Exit For End If Next Exit Sub

Use the Err object to display an error message if the installation of the component fails.

failed: MsgBox "Failure code " + Str$(Err.Number) End Sub

Automating Configuration of an MTS Client to Use Remote Components

To configure a client to use the Bank.CreateTable remote component:

Declare the objects that you will be using to configure a client (running MTS) to run remote components.

Dim catalog As Object Dim remoteComps As Object Dim util As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Retrieve the RemoteComponents collection by calling the GetCollection method. Then instantiate the RemoteComponentUtil object by using the GetUtilInterface method. To install the remote component, call the InstallRemoteComponentByName method and supply the name of the server computer, the package name on the server, and the component name.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set remoteComps = catalog.GetCollection("RemoteComponents") Set util = remoteComps.GetUtilInterface util.InstallRemoteComponentByName "remote1", "New","Bank.CreateTable" Exit Sub

Use the Err object to display an error message if the installation of the component fails.
```
failed:
 MsgBox "Failure code " + Str$(Err.Number)
 End Sub
```

Automating MTS Package Property Updates on Remote Servers

To update package properties on a remote computer named "remote1":

Declare the objects that you will be using to configure a client (running MTS) to deploy and administrator remote components.

Dim catalog As Object Dim packages As Object Dim pack As Object Dim root As Object

Use the On Error statement to handle run-time errors if a method returns a failure HRESULT. You can test and respond to MTS trappable errors using the On Error statement and the Err object.

On Error GoTo failed

Call the CreateObject method to instantiate the Catalog object. Call the Connect method to access the root collection on the computer named "remote1." The root collection is a collection object that can be used to access top-level collections on the given computer. The root collection contains no objects and has no properties. Note that the key value is not used when calling GetCollection from a root collection. Get the Packages collection on the remote computer by calling the GetCollection method. Then use the Populate method to fill the packages collection.

Set catalog = CreateObject("MTSAdmin.Catalog.1") Set root = catalog.Connect("remote1") Set packages = root.GetCollection("Packages", "") packages.Populate

Set the SecurityEnabled setting to "Y" for "My Package" and save changes to the package collection.

For Each pack In packages If pack.Name = "My Package" Then pack.Value("SecurityEnabled") = "Y" Exit For End If Next packages.savechanges Exit Sub

Use the Err object to display an error message if the installation of the component fails.
```
failed:
 MsgBox "Failure code " + Str$(Err.Number)
 End Sub
```

Automating MTS Administration

MTS Administration Objects

Using MTS Catalog Collection Objects

Visual Basic Script Samples for Automating MTS Administration

Visual Basic Sample Application for Automating MTS Administration

Automating MTS Administration with Visual Basic

Automating Installation of a Pre-Built MTS Package

Automating Advanced MTS Administration with Visual Basic

Automating Access to MTS Related Collection Names

Additional resources